Restful API 设计最佳实践 —— 11条规则

工作中常常见到不规范的restful设计，今天写一篇文章总结所有自己遇到的场景与设计方法。

核心理念

Restful请求的地址是一个资源，请求的方法是对资源的操作。

1. URL中的单词命名使用中线

/children-books
/children_books
/childrenBooks
/ChildrenBooks
复制代码

虽然有部分网站的restful设计也会使用下划线，但对比起来看，中线在显示效果和url感观上最好

2. 不要使用动词，用POST/GET/PATCH/PUT/DELETE代表动作

资源地址是一个名词路径，而方法是一个动词操作，restful这样的设计就是要规避在url使用动词，因为动词写法很多，比如说修改一本书可以是

POST /modify-book
POST /update-book
PUT /book-change
复制代码

这样不同的写法容易造成混乱，不如统一操作动词。

资源操作动词（Http请求方法）

GET 获取资源的信息
POST 添加资源
PUT 更新整个资源
PATCH 更新资源的部分信息
DELETE 删除资源
复制代码

例子

资源地址 https://www.example.com/books/1

GET /books 获取所有的书列表
GET /books/1 获取id为1的书
POST /books 添加一本新书
PUT /books/1 更新id为1的本书的整体信息
PATCH /books/1 更新id为1的书的部分信息
DELETE /books/1 删除id为1的书
复制代码

3. 资源单词使用复数

资源的命名如果使用单数+复数容易造成混乱，所以统一复数

GET /books 获取图书列表
GET /book/1 获取id为1的书
PUT /book/1
复制代码

上面的例子中获取图书列表因为是拿多本书所以书加了复数，如果取单本或者其他请求有的单数有的复数url显得混乱。
统一复数的另外一个原因是后端的SpringBoot等框架通常会把url前缀用注解方式写在Controller上，又是单数又是复数会让代码编写变得麻烦。

4. 正确使用资源归属

对于资源有归属特征，可以使用以下形式

/users/{id}/books/{id}  某某用户的某本书
/books/5/comments id为5书的评论列表
复制代码

设计url的时候要注意归属性的先后顺序。

5. 使用http状态码作为请求结果状态

200 请求成功
3XX 重定向
4XX 客户端请求错误
5XX 服务器请求处理错误
复制代码

详细 www.runoob.com/http/http-s…

有了状态码表示，那么200就可以直接返回接口信息，只有非200的请求需要返回ErrorCode。

6. 使用query过滤资源

/books?type=fiction 获取小说类型的书
复制代码

======================================

前文提到，restful的核心理念是对资源地址上的资源操作，但是实际的业务场景常常有超出这个范围的，这些请求的设计不一定能完全遵循以上原则。请求方法通常都是POST。

======================================

7. 资源获取接口扩展

用户的基础信息+详细信息

因业务需求 /users 接口需要设计成2个扩展，一个只返回用户的基础信息例如名字，头像等，另外一个则在用户详情页面使用，返回更多的用户信息，比如兴趣爱好甚至加上一些链接表的内容。

GET /users/1
GET /users/1/detail
复制代码

8. 资源操作接口扩展

订单商品信息修改+订单延期收货

对于一个资源如果修改信息只有一个PUT或PATCH接口，不能处理复杂的业务场景，比如说一个订单，需要多个接口处理不同的用户操作

PUT /orders/100
POST /orders/100/postpone  订单延期
复制代码

注意资源之后的操作，这里使用动词还是使用名词化动词存在争议，本着地址即资源不应该存在动词的原则，有观点认为这里的动词应该全部名词化例如 “cancel转cancellation”，也有观点认为使用动词即可。在参考了国外多个网站的restful设计后我个人建议使用动词，因为不是所有动词都能名词化，anyway团队自己内部商量统一就好。
另外，这类扩展操作通常用POST方法

生成一本书的PDF

这里没有对资源做任何增删改查操作

POST /books/1/pdf-generation (名词化）
POST /books/1/pdf-generate(动词）
复制代码

9. 多资源查找

网站全局查找功能

这个查找功能是查找所有的资源，而且不是特别针对某个资源，可以设计成

POST /searches?keyword=xxx
复制代码

这个可以理解成你在使用keyword创建了一个search资源，然后返回了结果。

10. 多资源操作

银行转账功能

这个转款的实际操作了多个数据，要自己的银行账户扣款，在新账户加款，里面还伴随很多操作，例如保存转账记录等。

POST /transfer
复制代码

修改发票功能

修改发票伴随着几个过程，并不是简单的去修改数据库信息，原来的发票信息是保留的，而是做了一个新的红冲发票，并且有生成pdf发送邮件等操作。

POST /invoices/1
复制代码

11. 合同法律相关

对于合同，法律，条款需要留保证据的任何操作，一律用POST
例如同意用户协议，确认租赁合同，生成电子合同，确认身份信息。