resultful

介紹

链接: resultful详细笔记
目前最流行的接口设计规范，提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。

具体的HTTP方法和方法含义如下：

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）。
• DELETE（DELETE）：从服务器删除资源。

从请求的流程来看，RESTful API和传统API大致架构如下：

• 

URI指向资源：URI = Universal Resource Identifier 统一资源标志符，用来标识抽象或物理资源的一个紧凑字符串。URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。

**无状态：**服务器不能保存客户端的信息， 每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存， 服务器端根据这些状态信息来处理请求。 当客户端可以切换到一个新状态的时候发送请求信息， 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

REST架构限制条件（RESTful 6大原则）

1. 客户端-服务端（Client-Server）: 这个更专注客户端和服务端的分离，服务端独立可更好服务于前端、安卓、IOS等客户端设备。
2. 无状态（Stateless）：服务端不保存客户端状态，客户端保存状态信息每次请求携带状态信息。
3. 可缓存性（Cacheability） ：服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。
4. 统一接口（UniformInterface）：通过一定原则设计接口降低耦合，简化系统架构，这是RESTful设计的基本出发点。当然这个内容除了上述特点提到部分具体内容比较多详细了解可以参考这篇REST论文内容。
5. 分层系统（Layered System）：客户端无法直接知道连接的到终端还是中间设备，分层允许你灵活的部署服务端项目。
6. 按需代码（Code-On-Demand，可选）：按需代码允许我们灵活的发送一些看似特殊的代码给客户端例如JavaScript代码。

RESTful API设计规范

1. URL设计规范
   URL为统一资源定位器 ,接口属于服务端资源，首先要通过URL这个定位到资源才能去访问，而通常一个完整的URL组成由以下几个部分构成：

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http默认为80端口
path: 访问资源的路径，就是各种web 框架中定义的route路由
query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
fragment: 锚点，定位到页面的资源

通常一个RESTful API的path组成如下

/{version}/{resources}/{resource_id}

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
resources：资源，RESTful API推荐用小写英文单词的复数形式。
resource_id：资源的id，访问或操作该资源。

1. 不用大写字母，所有单词使用英文且小写。
2. 连字符用中杠"-“而不用下杠”_"
3. 正确使用 "/"表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
4. 结尾不要包含正斜杠分隔符"/"
5. URL中不出现动词，用请求方式表示动作
6. 资源表示用复数不要用单数
7. 不要使用文件扩展名

状态码

1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

主要常用状态码罗列在下面：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - []：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - []：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [] ：表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - []：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

GET、POST、 PUT 、DELETE请求

1. GET请求用来获取资源：GET请求会向数据库发索取数据的请求，从而来获取资源，该请求就像数据库的select操作一样，只是用来查询数据，不会影响资源的内容。无论进行多少次操作，结果都是一样的。
   并且GET请求会把请求的参数附加在URL后面，但是不同的浏览器对其有不同的大小长度限制。
2. POST请求用来新增一个资源 : POST请求向服务器发送数据，但是该请求会改变数据的内容(新添)，就像数据库的insert操作一样，会创建新的内容。且POST请求的请求参数都是请求体中，其大小是没有限制的。
3. PUT请求用来更新资源，PUT请求是向服务器端发送数据的， 与POST请求不同的是，PUT请求侧重于数据的修改 ,就像数据库中update一样，而POST请求侧重于数据的增加。
4. DELETE 请求用来删除资源，DELETE请求用途和它字面意思一致，用来删除资源。和数据库中delete相对应。