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

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

技术杂谈小彩虹2021-07-10 14:34:05110A+A-

工作中常常见到不规范的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 例如同意用户协议,确认租赁合同,生成电子合同,确认身份信息。

点击这里复制本文地址 以上内容由权冠洲的博客整理呈现,请务必在转载分享时注明本文地址!如对内容有疑问,请联系我们,谢谢!

支持Ctrl+Enter提交

联系我们| 本站介绍| 留言建议 | 交换友链 | 域名展示
本站资源来自互联网收集,仅供用于学习和交流,请遵循相关法律法规,本站一切资源不代表本站立场,如有侵权、后门、不妥请联系本站删除

权冠洲的博客 © All Rights Reserved.  Copyright quanguanzhou.top All Rights Reserved
苏公网安备 32030302000848号   苏ICP备20033101号-1

联系我们