Restful风格接口的理解

基本概念

全称是 Resource Representational State Transfer

通俗来讲就是，资源在网络中以某种表现形式进行状态转移。

分解开来：Resource：资源，即数据（前面说过网络的核心）；

Representational：某种表现形式，比如用JSON，XML，JPEG等；

State Transfer：状态变化。通过HTTP动词实现，GET,PUT,POST,DELETE

RESTful API设计规范

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对path的设计做了一些规范，通常一个RESTful API的path组成如下

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

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。

resources：资源，RESTful API推荐用小写英文单词的复数形式。

resource_id：资源的id，访问或操作该资源。

路径规范

1.使用小写字母，多个单词用”-“分隔，提高URL的可读性

2.资源嵌套层次避免过深，尽量不超过2层

HTTP动词

GET /collection:从服务器查询资源的列表
GET /collection/resource:从服务器查询单个资源
POST /collection:在服务器创建新的资源
PUT /collection/resource:更新服务器资源
DELETE /collection/resource:从服务器删除资源

状态码和返回数据

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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

不符合 CRUD 的情况

在实际资源操作中，总会有一些不符合CRUD的情况，一般有几种处理方法。

1.为需要的动作增加一个 endpoint，使用 POST 来执行动作，比如 POST /resend 重新发送邮件。

2.增加控制参数

添加动作相关的参数，通过修改参数来控制动作。

比如一个博客网站，会有把写好的文章“发布”的功能，可以用上面的POST /article/{:id}/publish方法，

3.把动作转换成资源

把动作转换成可以执行 CRUD 操作的资源， github 就是用了这种方法。

比如”喜欢”一个 gist，就增加一个/gists/:id/star子资源，然后对其进行操作：“喜欢”使用PUT /gists/:id/star，”取消喜欢”使用DELETE /gists/:id/star。

总结

任何一门技术或者思想都有其优缺点，虽然其诞生的初衷都是为了解决我们的问题，而不是带来更大的灾难。REST同样如此。它的优点很明显，优雅、规范，行为和资源分离，更容易理解。

但是也有其缺点，它面向资源，这种设计思路是反程序员直觉的，因为在本地业务代码中仍然是一个个的函数，是动作，但表现在接口形式上则完全是资源的形式， 对于后端开发人员要求高，有些业务逻辑难以被抽象为资源的增删改查。甚至有些时候RESTful其实是个效率很低的东西，为了实现一个资源，你需要定义它的一套方式， 如果要联合查询又会要求对其衍生或定义一个新的资源。它提供的接口一般是“粗”粒度的，它通常返回的都是完整的数据模型，难以查询符合特殊要求的数据，有些特殊的业务要比普通的API需要更多次HTTP请求。

RESTful API是REST风格的API，它是一种API设计风格，规范了API设计中的一些原则。它让我们的API更加优雅、规范。但也尤其缺点，在实际使用过程中我们应该充分的取理解它，综合考量其使用场景。

参考

• https://docs.github.com/zh/rest/quickstart?apiVersion=2022-11-28
• https://juejin.cn/post/7128790457550635021