Restful API设计最佳实践

RESTFul

我们说传统项目是拼字符串的方式，最早拼字符串就是一行行拼，这没什么好说的，
是最笨重的方式。后来呢将，HTML和我们的要用的数据分离。数据是后来填充进去的，
填充在一个模板当中
这个是在服务器端，我们拼凑好内容，这个内容是混杂着HTML标签，加数据，他们称
为一个大字符串。互相做好的字符串直接返回回去，注意这个内容是动态生成的。如
果用模板的话，局部是动态生成的，然后跟哪些原来写好的字符串之间进行拼接在
一起。拼接出大字符串。然后返回回去，

客户端这边不知道，不服务器端是动态生成还是静态生成的。客户端不知道也不关心，
他就说你给我的是不是HTML，如果你给我的是HTML，那就简单了。那就解析渲染，
浏览器就能看到好看的页面了。这就是传统的解决方案。这个传统的解决方案有什么
问题呢？

主要是在服务器端，在服务器端的话就是，我们在使用的过程中发现，
做网页开发的人，跟做后端开发的人，他们是工作的比较紧密的结合在一起的。
你比如说我现在要实现一个首页的展示。
首页需要什么功能呢？也可以提前商量，但是我首页最终要求别人能够看，或者能够测
试。一般
情况下，需要等你模板写完。或者自己写一个模板。等你把图片、HTML啥的整理好之
后，我在合并进去。合并进去之后我把你原来写的那个，也就是填充数据的地方，
给扣掉，要写出模板。


从项目组来说，前端的人员，必须和我后端的人在一起开发，甚至呢，我必须等你，
如果你这边换模板，我后端这里就需要重新做空。

有些地方需要多处理一下，比如奇偶行。总之有一部分，前端和后端是需要重合在一
起的。甚至你这个工作必须等待网页好了，才能设置后端。但是最终还是需要转为模板

深度结合的坏处，就是需要互相等待，还有就是，我们在做这件事的时候，前端需要跟
后端是耦合在一起的。前端要换模板，后端就需要重新做Djanog模板。耦合的太紧密了

要解决的话，就需要你和网页中的HTML解决分离，HTML的标签到底用什么格式，
我不关心，我后端只提供数据，把后端的动态网页技术，以前我是提供一个Response，
这个响应里面有HTML
带数据、格式、标签、我换一种思路，只提供数据。

那我直接用数据库不就好了，问题是数据库是提供数据存储的地方，你要是什么数据是
根据需求来改变的，这个需求是业务层，由业务层来决定，该访问什么样子的数据，
该组合什么样的数据
该查询什么样的数据。还是需要前端来访问，需求不同，来查询不同的表。来形成不同
的结果集。

结果集在通过True里面，最后得到一个结果发给浏览器，浏览器直接显示结果吗？
如果浏览器显示的都是JSON数据，用户是看不懂的。这个思路是一个好思路，就是
说我们给用户的是纯粹的数据。页面由前端搞定。

前端之后提供HTML标签，标签缺什么，由页面发起异步请求，Ajax请求，
通过发起这个异步请求
发URL请求，找到我现在写的程序，通过路由来解决这给问题。

第一种是拼接大的HTML字符串，直接在内存中拼接，我们后来发现这种方式太笨重了。
	第二种方式我们刚才说的是模板技术，这个模板技术结合了一些静态访问技术，通过
	模板去找文件系统，文件系统中存放着某种模板，如果用模板技术，模板技术需要
  怎么样呢
	模板技术就需要找这个模板，找到的这个模板，就代表着标签，并不代表里面的内容
	这个内容需要动态生成，所以模板里面就有模板语法，我们找到以后，就进行加载。
	加载它，可以认为它是一个不完整的字符串，找到模板之后进行渲染。

	渲染本质就是填充数据，填充数据的目的就是拼接大的HTML字符串，以前是在内存
  中直接拼接，有点像demoApp,然后发现这种拼接方式很麻烦，所以我们先把HTML
  文件给弄出来，然后我们现在有一种特殊语法，我们找到它里面的空，填充数据。
  但是最终的目的，还是拼接成大的HTML字符串。然后把 HTML字符串封装返回给
  浏览器。

	但是这样子的过程会带来一些问题，就是两边的工作会有一个等待的过程，
  在一个模板要是改变，要对模板重新进行挖空。关键是每次换模板，
  就需要重新挖空。美工需要做第一版模板。

	第三种呢，不用模板技术，不提供HTML了，不提供格式了，只提供数据，
  纯提供数据，提供
	数据需要有描述方式。我们的数据通过JSON来实现，JOSN数据怎么来的呢？
  照样要做映射。

	就是你给我提供是URL，提供URL之后，给我了很多参数，我把参数拿到之后呢，
  找相应的视图函数，通过视图函数呢，去视图函数中查数据库也好，等等都可以。
  做完之后，我会
	得到一个数据结果，这个结果我用JSON表达，JSON里面就是纯粹的数据，
  将数据返回给你

	MIME类型，最早用在邮件系统中，是一种互联网的标准。能做多媒体应用程序的
  关联
	更多的是描述文件的类型。

	但是在这个Web Server中这个MIME类型是application/json，
  传给客户端是这样的纯数据，这里是动态网页服务器。它提供

	第三种是首先同一个浏览器，

两种方式，一种是找到动态资源，然后通过某种路径映射，采用模板技术。
动态资源访问去访问
MIME，还有就是你访问的是静态资源HTML，给你返回了。浏览器拿到了这个静态资源，
但是呢
浏览器在展示的过程中，缺少Ajax,需要js代码发起Ajax请求


 Ajax会发起一个异步请求来找动态资源，由于路径的特殊处理，找到动态服务器，
 通过相应的路径映射找到相应的视图函数，视图函数会返回一个JSON，
 这个JSON就返回回去了，然后再运行JS代码，这个JS代码对表格进行填充。

 一个浏览器如果访问纯静态资源的话，其实找文件系统就行了，
 Nigix呀Http是都可以做到的
 访问动态资源，nignx做代理。前端后端混合再一起的是模板技术。可以用

 前后端分离，就是浏览器依然访问的是静态资源，HTML CSS 给返回过去，
 只不过我再解析
 这个HTML的过程当中，发现有一段内容，是没用展示内容的。当我们解析完的时候
 有一个
 download触发了，触发了之后，才会发起一个异步请求，
 这个请求悄悄的发给了Nginx
 Nginx一看这部分，要数据，这个需要需要从数据库查询的，
 这时候Nginx会把请求代理到一个 动态服务器上的。这个动态服务器中会通过动态
 映射，找到视图函数，让视图函数去帮你查数据库。查完数据，将数据库做处理，
 最后返回一个纯数据JSON。这个纯数据是不能用的，所以我们需要，回调函数。

 这个回调函数来解析这个JSON数据，如果JSON返回的是数组的话，会一行行进行遍历
 这就是基本的Web架构。所有复杂的Web架构都是基于这个架构的。

 JS会帮助填充数据，他们是帮助我们把数据填充到HTML的DOM树节点上的，
 从而渲染出来效果

表现层就是给人看的东西，说到底就是HTML,再表现层发现的状态转移，
就代表中我们看到的东西。发生了变化，你要想到，表现成状态变化是由什么引起的，
这才是关键。

表现层是资源的表现层，资源表现层状态的变化，本身指的是。它后背资源变化所引
起来的变化而资源是通过URL来表达的。

URL表示什么意思呢？它再HTTP协议中表示，就包含着URL，统一资源定位符，
你就可以理解再网络当中，我们就可以通过统一资源定位符来指向资源，
指向的这个资源发生了状态的变化
从而导致了它表面的表现层状态的迁移，状态的转移就是这个意思，
说到底就是资源变化，
资源是通过URL所指向的，URL所指向的数据那个资源动态服务后面所指向的数据发生了
变化数据发生了变化，你请求资源就发生了变化，再表现层就应该发生转移。
从一种状态到另一种状态，和数据库状态是一个意思，从一个一致性状态，
到另一个一致性的状态。

符合Rest风格的就叫做Restful，fuL形容词后缀，这个风格没用统一标准。
这种实践没用统一标准，只有你愿不愿意用。
每个项目组都有了自己对RESTFul自己的理解和使用方式。

比如：定义模块应该定义什么名字，应该使用什么前缀和后缀，定义变量的时候，
要不要去考虑什么风格，加不加下划线，是否还有一些见名知意的要求，
单词应该使用什么

这些需要加到项目组中，不然代码整理的时候什么起名字都有

你把Web接口定义好

项目未动，接口先行，我们是一个前后端分离的项目，前端是写网页的，写JS的，
后端是写
Django的，如果要做前后端分离项目，大家以后要配合，前后端通信使用的URL接口。
必须定义好。项目还没开写，项目的接口要定义好。

js react vue jquery 必须知道这个接口定义a

这个意思就是Ajax请求是前端做的，前端发请求，URL是什么？使用什么样子的方法，
GET还是POST方法，应该提交什么样子的数据呢？都必须先定义好，对于后端来说，
我能接收到什么数据，提取什么样子的数据，应该关注什么样子的方法都需要同一。

后端再写视图函数中，必须解决如何将请求，路由到对应的视图函数中，
最终按照接口规范
有了接口规范，前端的开发人员和后端的代码开发人员可以各自开发自己的代码。
互补干扰

接口定义风格流行使用Restful

1.选择合适的协议
	比如HTTP和HTTPS，HTTPS，后面的S表示加了SSL这样的协议，这样的协议有什么
  用呢？
	就是给数据加密，就是传输数据过程中加密，或者对敏感数据加密。这个加密呢？
  破解起来就有难度了，你如果用HTTP：// 这样 ，也会有一个三系列的状态码，
  它希望你提升，如果你允许提升的话， 就变成了HTTPS：//，也就说，
  通过加密来通信了。

	你的所以数据需要再浏览器端进行加密，加密之后传送到服务器端，
  由于采用证书加密
	有一些好处，第一个你们协商了你们加密的密钥，这个密钥定期会改变。
  这样加密有什么好处呢？也就是如果有人拦截你的数据，是没用的，
  就算破解了数据，我们隔一段时间传输的密钥，也都变化了，攻击一个时间点的
  数据对其他时间点传输的数据是没用的。

	还不允许窜改，有时候想伪造数据不做不到的，就是一旦伪造数据我们是能
  立即判断出来的，从而把数据丢弃。所以证书加密有这样的好处。但是一般
  来讲是安全要求。所以效率会下降，这也是没办法的事情。如果同学们使用
  的数据不敏感就用HTTP就行，一般内网中都使用HTTP，内网服务调用，
  使用HTTP。有安全性考虑就需要使用HTTPS，效率差也没事。

	Nginx是对外的

URL指向资源，再URL路径的描述中，只需要出现名词，而不要出现动词。
由于汉语当中是没有明显的单复数的，动作也是没用时态的。我们的名词也没用单复数

我们汉语对单复数不敏感，你如果指向一批资源则可以使用复数，
当然也能用单数。用单数就一直单数，用复数就一直用复数。不能一会单数，
一会复数。一定要统一。

千万不要再路径中出现动词，不要出现名词和动作进行混搭

比如说去拿所有的文章，文章拿过来是默认排序，如果你想要排序该怎么办呢？
还是要用参数的方式告诉他。这就是拿回来的方式。

怎么排呢？sort= title,RESTFUL是特别在意这些状态码的：
200 201 204 400 401 403
404 500 我们要学会读懂这些状态码

不要给用户长篇描述这个错误是怎么回事，用户会越看越头疼。
成功了返回什么，错误返回什么
这些我们都是可以自己定义规范的

现在问题是这样的，我们的项目是持续开发的隔了一段时间以后我们发现，
我们原来再设计上
有很多不足。如果我们新增了一些业务功能，新增业务功能我们可能会这样子：

	http://www.magedu.com/python/p29/1
	增加业务后：
	http://wwwmagedu.com/linux/m42/2
		我们又多了一个业务功能

	python/p29/1对于这个业务功能，我们原来的接口里面，我发现咱们的一些约定
  由于功
	能的增强需要破坏掉，可能就是返回的JSON字段，多了几个。这些就带了问题，
  你是再原来的接口修改呢？还是增加接口呢？或者说我可以保留原接口不变，
  我再新增一些接口定义。但是你也知道，兼容旧的呢，就在原基础上进行修改。

	比如原来再POST里面传数据需要3个字段，现在变成5个字段。如果一旦全面进行
  修改的话
	就会导致一个问题，又很多人都是，遵照接口规范开发的，你这边改变了，
  那边是不知道的。

	比如说，后端的人说这个接口改了，从原来的3个参数变为5个参数，
  但是前端开发人员不知道呀，前端还认为是3个，所有容易出错。
  再原有接口进行改动是不好的。

	给出第一种方案，我们原有接口不动，再出现版本1、版本2、版本3，
  适合少量的。原有的项目使用老接口可以，新代码可调用新接口。
  但是这种方案适合小规模的接口变化。

	如果有大的构成业务上的重构， 接口定义发生了巨大变化该怎么办呢？

		这时候就需要加版本号了
		原有接口修改，往往会有兼容性的问题

接口先行，所有业务的接口要提前定义好