API设计的8个技巧

原文: 高效 API 设计的8个技巧 - 小红书 (xiaohongshu.com)

本文是笔者在该文章基础上加入自己理解以及一定的扩展,如有问题欢迎指出

1.贴合主要模型

在设计Restful API的路径结构时，我们可以参考系统中的模型及其附带关系。即使用模型的名称和逻辑来设计路径。

例如:

• 有关订单的API可以是/order/**
• 若是某个订单中详细信息则可以是/order/{id}/items

2.选择一个合适的Http请求类型

定义一些基本的,简单的HTTP方法可以简化API的设计。例如，PATCH等复杂不常见的请求类型通常会给团队带来不便。

最常见的几个请求类型: GET,POST,PUT,DELETE

• GET: 一般用于查询请求
• POST: 一般用于复杂的请求,类似创建,其他功能等
• PUT: 一般用于更新请求
• DELETE: 一般用于删除

3.正确实现幂等性

简单来说幂等性就是多次同样的操作和一次操作是否会有同样的结果。

常见于分布式系统、网络请求和API设计中，由于各种原因（如网络延迟、重试机制、请求重放等），请求可能会被多次发送，这时如果API没有实现幂等性，就可能导致数据不一致、重复处理等问题。

分布式锁也是用来解决相关问题。

• GET请求: 天生就是幂等的,因为是查询,并不会对数据进行操作
• PUT&DELETE请求: 应该被设计为幂等

• • PUT: 无论PUT请求被发送一次还是多次，资源的最终状态都应该是相同的。这意味着，如果资源已经处于请求所期望的状态，那么后续的PUT请求将不会改变资源的状态。可以理解为若原来数据和更新数据已经一致则会直接返回。
  • DELETE: 无论DELETE请求被发送一次还是多次，指定的资源都应该被删除，且系统状态不会因此而有额外的变化。同理，一旦资源被删除，后续的DELETE请求应该被视为已经成功(尽管它们可能返回一个指示资源已不存在的错误码)。

• POST: 应根据业务逻辑具体而定

4.选择正确的请求状态码

定义一定数量的 HTTP 状态代码，用于简化应用程序开发。

常见的状态码网上都可以找到,就不再赘述。

5.版本号

提前设计应用程序接口的版本号可以简化升级工作。

例如:届时版本更新调用只需从/order/v1/变到/order/v2

一般从三个方面来设置版本号:

• 路径中(推荐): GET /v1/users
• 请求路径参数: GET /users?v1
• 请求头: Header Version: v1

6.路径语义明确

尽量做到让使用者看到就能理解请求大致作用。

例如: /user/login是用户登录

Tip:

• 尽量使用文件夹一样的格式而不是一个动词
• 区分单数及双数

7.批量操作

涉及到批量操作,例如:查询,插入多条数据时,可以将其关键字插入到路径的尾部,使该请求作用更加明显。

POST请求: /users/batch批量操作用户

GET请求: /users?ID=1,2,3..批量查询用户

8.查询模板

一套查询的规则，能使API更加灵活。 例如，页数、排序、过滤等。

常见的设计:

• 分页查询: 携带参数第几页page和一页的条数size
• 排序查询: 携带排序字段sortField和排序规则sortOrder
• 筛选查询: 携带筛选条件