restful编码风格

待我称王封你为后i 2021-10-18 13:32 363阅读 0赞

转载：[https://jsbintask.cn/2019/03/20/api/restful-api-best-practices/][https_jsbintask.cn_2019_03_20_api_restful-api-best-practices](食用效果最佳)，转载请注明出处!

## 介绍 ##

`rest`是`REpresentational State Transfer`三个单词的缩写，由Roy Fielding于2000年论文中提出，它代表着分布式服务的架构风格。而如果想你的api被称为restful api，只要遵循其规定的约束即可。

## rest设计原则 ##

1.  客户端-服务器：通过将用户UI与数据存储分开，我们可以简化服务器组件来提高跨多个平台的用户界面的可移植性并提高可伸缩性。 它可以比表现成前后端分离的思想。
2.  无状态：从客户端到服务器的每个请求都必须包含理解请求所需的所有信息，并且不能利用服务器上任何存储的上下文。 这表示你应该尽可能的避免使用session，由客户端自己标识会话状态。（token）
3.  规范接口：REST接口约束定义：资源识别; 请求动作; 响应信息; 它表示通过uri标出你要操作的`资源`，通过请求动作（http method）标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。
4.  可缓存： 缓存约束要求将对请求的响应中的数据隐式或显式标记为可缓存或不可缓存。如果响应是可缓存的，则客户端缓存有权重用该响应数据以用于以后的等效请求。 它表示get请求响应头中应该表示有是否可缓存的头（Cache-Control)  
    其中1，2，3约束最为重要，其中1容易理解。接下来我们就谈谈无状态和规范接口的原则。

### uri规范 ###

资源的描述构成了uri，它一般有以下约束：

1.  使用名词。如 user, student, class  
    [http://api.example.com/class-management/students][http_api.example.com_class-management_students]  
    [http://api.example.com/device-management/managed-devices/\{device-id\}][http_api.example.com_device-management_managed-devices_device-id]  
    [http://api.example.com/user-management/users/][http_api.example.com_user-management_users]  
    [http://api.example.com/user-management/users/\{id\}][http_api.example.com_user-management_users_id]
2.  http method对应不同的请求动作（数据库或者业务逻辑）  
    `GET`：查询操作：  
    HTTP GET /devices?startIndex=0&size=20  
    HTTP GET /configurations?startIndex=0&size=20  
    HTTP GET /devices/\{id\}/configurations  
    HTTP GET /devices/\{id\}  
    `POST`：新增操作：  
    HTTP POST /device  
    `PUT` 更新操作（代表更新一个实体的所有属性）  
    HTTP PUT /devices/\{id\}  
    `PATCH` 部分更新（代表更新一个尸体的部分属性）由于有的浏览器兼容性问题，一般推荐使用put  
    HTTP PATCH /devices/\{id\}  
    `DELETE` 删除操作  
    HTTP DELETE /devices/\{id\}
3.  使用连字符（ - ）而不是（\_）来提高URI的可读性  
    [http://api.example.com/inventory-management/managed-entities/\{id\}/install-script-location][http_api.example.com_inventory-management_managed-entities_id_install-script-location] //更易读  
    [http://api.example.com/inventory\_management/managed\_entities/\{id\}/install\_script\_location][http_api.example.com_inventory_management_managed_entities_id_install_script_location] //更容易出错
4.  在URI中使用小写字母  
    [http://api.example.org/my-folder/my-doc][http_api.example.org_my-folder_my-doc]
5.  不要使用文件扩展名 文件扩展名看起来很糟糕，不会增加任何优势。删除它们也会减少URI的长度。没理由保留它们。  
    [http://api.example.com/device-management/managed-devices.xml][http_api.example.com_device-management_managed-devices.xml] / *不要使用它* /  
    [http://api.example.com/device-management/managed-devices][http_api.example.com_device-management_managed-devices] / *这是正确的URI */
6.  使用查询组件过滤URI集合  
    很多时候，我们会遇到需要根据某些特定资源属性对需要排序，过滤或限制的资源集合的要求。为此，请不要创建新的API - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数作为查询参数传递。例如  
    [http://api.example.com/device-management/managed-devices][http_api.example.com_device-management_managed-devices]  
    [http://api.example.com/device-management/managed-devices?region=USA][http_api.example.com_device-management_managed-devices_region_USA]  
    [http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ][http_api.example.com_device-management_managed-devices_region_USA_brand_XYZ]  
    [http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date][http_api.example.com_device-management_managed-devices_region_USA_brand_XYZ_sort_installation-date]
7.  不要在末尾使用`/`  
    作为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能导致混淆。最好完全放弃它们。
8.  使用http状态码定义api执行结果  
    **1xx：信息**  
    通信传输协议级信息。

**2xx：成功**  
表示客户端的请求已成功接受。

**3xx：重定向**  
表示客户端必须执行一些其他操作才能完成其请求。

**4xx：客户端错误**  
此类错误状态代码指向客户端。

**5xx：服务器错误**  
服务器负责这些错误状态代码。  
另外完整的更为详细的状态码此处不做赘述。一般简化版本的api会使用200，400，500，其中400代表客户端调用有误，将错误信息放入response：

<table> 
 <tbody> 
  <tr> 
   <td> <pre>1
2
3
</pre> </td> 
   <td> <pre>{
  "error": "username.or.password.error"
}
</pre> </td> 
  </tr> 
 </tbody> 
</table>

1.  api版本定义  
    当我们需要对现有的api接口升级的时候，因为该api接口已经投入使用，所以新添加的业务可能无法保证兼容原来的逻辑，这个时候就需要新的接口，而这个接口一般表示对原来的接口的升级（不同版本），那版本怎么定义呢？

*  URI版本控制（推荐）  
    [http://api.example.com/v1][http_api.example.com_v1]  
    [http://apiv1.example.com][http_apiv1.example.com]
 *  使用自定义请求标头进行版本控制  
    Accept-version：v1  
    Accept-version：v2
 *  使用Accept header 进行版本控制  
    Accept:application / vnd.example.v1 + json  
    Accept:application / vnd.example + json; version = 1.0

### 无状态 ###

使REST API无状态有一些非常显着的优点：

1.  无状态通过将API部署到多个服务器，有助于将API扩展到数百万并发用户。任何服务器都可以处理任何请求，因为没有与会话相关的依赖。（集群）
2.  无状态使得REST API不那么复杂 - 可以删除所有服务器端状态同步逻辑。（删除session，清理多余空间）
3.  无状态API也很容易缓存。特定软件可以通过查看该一个请求来决定是否缓存HTTP请求的结果。从先前的请求中获得的状态可能会影响这个请求的可缓存性，这并不存在任何不确定性。它提高了应用程序的性能。
4.  服务器永远不会忘记每个客户端身份”，因为客户端会在每个请求中发送所有必要的信息。（携带token）

[https_jsbintask.cn_2019_03_20_api_restful-api-best-practices]: https://jsbintask.cn/2019/03/20/api/restful-api-best-practices/
[http_api.example.com_class-management_students]: http://api.example.com/class-management/students
[http_api.example.com_device-management_managed-devices_device-id]: http://api.example.com/device-management/managed-devices/%7Bdevice-id%7D
[http_api.example.com_user-management_users]: http://api.example.com/user-management/users/
[http_api.example.com_user-management_users_id]: http://api.example.com/user-management/users/%7Bid%7D
[http_api.example.com_inventory-management_managed-entities_id_install-script-location]: http://api.example.com/inventory-management/managed-entities/%7Bid%7D/install-script-location
[http_api.example.com_inventory_management_managed_entities_id_install_script_location]: http://api.example.com/inventory_management/managed_entities/%7Bid%7D/install_script_location
[http_api.example.org_my-folder_my-doc]: http://api.example.org/my-folder/my-doc
[http_api.example.com_device-management_managed-devices.xml]: http://api.example.com/device-management/managed-devices.xml
[http_api.example.com_device-management_managed-devices]: http://api.example.com/device-management/managed-devices
[http_api.example.com_device-management_managed-devices_region_USA]: http://api.example.com/device-management/managed-devices?region=USA
[http_api.example.com_device-management_managed-devices_region_USA_brand_XYZ]: http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
[http_api.example.com_device-management_managed-devices_region_USA_brand_XYZ_sort_installation-date]: http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
[http_api.example.com_v1]: http://api.example.com/v1
[http_apiv1.example.com]: http://apiv1.example.com/