API 设计的原则

Charles@TechBlog

已于 2024-03-10 17:08:23 修改

阅读量726

点赞数

文章标签：系统架构

于 2024-03-10 12:28:57 首次发布

本文链接：https://blog.csdn.net/shaoshaoh/article/details/136598407

版权

在这里插入图片描述

我在 Thoughtworks 上曾经读到过一篇文章《API 设计的几条原则》我觉得写得非常不错，链接我放底下，推荐阅读。

在我多年的工作历程中，我深刻意识到 API 的设计至关重要，但是我发现，在一般的组织中，API 的设计却往往草率。这主要体现在几个方面：

操刀人选草率 ：不少团队的 API 设计，都是负责实现的同事进行的，这些同事很多情况下，并不是团队里最资深，最了解各个系统构造的人，在设计的时候，就不能考虑到更多的东西；
接口缺乏标准 ：公司稍微大一点的情况下，很容易缺乏全公司统一的标准，往往就是各个团队有各个团队的标准，如果仅是如此尚好，有时候不同团队的标准不兼容；
命名草率：接口上选用的单词，往往非常随机，取决于设计者的个人修养，而这些命名有时候并某有经过审计，在定稿的时候，上下游都没有认真的思考过，有时候名字取得过大，有时候取得过小，非常妨碍使用者的理解，甚至造成误导；

我观国内外一些顶级的开源项目，API 动辄几年十几年不变，就深感佩服。那么 API 设计到底要考虑些什么因素，怎样设计，才能做到这样的稳定呢？

API 本质上是系统不同部分之间通信的协议，当然也包括跟外部系统之间的通信。要想设计得好，就要将系统充分的抽象，这个过程之中，要尽量摒弃掉抽象之外的因素的影响。比如，接口运行的网络协议（TCP/UDP），内容格式（文本/二进制），调用者的形态（服务器/客户端），这类都不应该预定一种假设。

原文的作者认为，设计 API 是非常难的，评估 API 的好坏也是非常难的，所以给出一些原则，共参考：

使用成熟度合适的 RESTful API

RESTful 风格的 API 具有一些天然的优势，例如通过 HTTP 协议降低了客户端的耦合，具有极好的开放性。因此越来越多的开发者使用 RESTful 这种风格设计 API，但是 RESTful 只能算是一个设计思想或理念，不是一个 API 规范，没有一些具体的约束条件。

因此在设计 RESTful 风格的 API 时候，需要参考 RESTful 成熟度模型。

成熟度等级	解释	示例
Level 0	定义一个 URI 所有请求通过 POST 完成	`POST /?action=changeUserPassword`
Level 1	创建独立的资源地址，隔离 API 的范围	`POST /user?action=update`
Level 2	使用 HTTP 动词定义对资源的操作	`GET /user/01`
Level 3	使用 API 超媒体（HATEOAS，返回的 body 中索引相关的资源地址	`{ "links" : [ "/users/", "/products/" ] }`

一般团队选用的等级在 Level 2，这是一个参考，不过我自己实践下来看，Level 2 也是比较难的，我所在的团队可能还在使用 Level 1，因为更直观一点，比较容易掌握，大家的理解也比较容易一致。

这里补充一个对成熟度模型的解释：

Level 0，有点像系统间的 RPC 调用一样，类比一下编程泛型的话，就是面向过程编程。你远程调用服务器的一个方法，得到返回值。
Level 1，引入资源的概念，资源与资源之间隔离了。有点像面向对象编程，调用一个对象上的方法。
Level 2，引入 HTTP 动词，把 HTTP 协议当成原本设计的意图去使用，而不是退化个一个管道。
Level 3，引入超媒体概念，HATEOAS（作为应用状态引擎的超文本）

避免简单封装

API应该服务业务能力的封装，避免简单封装让API彻底变成了数据库操作接口。例如标记订单状态为已支付，应该提供形如 POST /orders/1/pay 这样的API。而非 PATCH /orders/1，然后通过具体的字段更新订单。

因为订单支付是有具体的业务逻辑，可能涉及到大量复杂的操作，使用简单的更新操作将业务逻辑泄漏到系统之外。同时系统外也需要知道订单状态这个内部使用的字段。

更重要的是，破坏了业务逻辑的封装，同时也会影响其他非功能需求。例如，权限控制、日志记录、通知等。

关注点分离

好的接口应该做到不多东西，不少东西。怎么理解呢？在用户修改密码和修改个人资料的场景中，这两个操作看起来很类似，然后设计API的时候使用了一个通用的 /users/1/udpateURI。

然后定义了一个对象，这个对象可能直接使用了User这个类：

{
  "username": "用户名",
  "password": "密码"
}

这个对象在修改用户名的时候， password是不必要的，但是在修改密码的操作中，一个password字段却不够用了，可能还需要confirmPassword。

于是这个接口变成：

{
  "username": "用户名",
  "password":"密码",
  "confirmPassword":"重复密码"
}

这种类的复用会给后续维护的开发者带来困惑，同时对消费者也非常不友好。合理的设计应该是两个分离的 API：

// POST /users/{userId}/password

{
  "password":"密码",
  "confirmPassword":"重复密码"
}
// PATCH /users/{userId}

{
  "username":"用户名",
  "xxxx":"其他可更新的字段"
}

对应的实现，在 Java 中需要定义两个 DTO，分别处理不同的接口。这也体现了面向对象思想中的关注点分离。

互斥穷举

API 之间尽量遵守 MECE （互斥穷举）原则，不应该提供相互叠加的 API。例如订单和订单项这两个资源，如果提供了形如 PUT /orders/1/order-items/1 这样的接口去修改订单项，接口 PUT /orders/1 就不应该具备处理某一个 order-item 的能力。

这样的好处是不会存在重复的 API，造成维护和理解上的复杂性。如何做到完全穷尽和彼此独立呢？

简单的方法是使用一个表格设计 API，标出每个 URI 具备的能力。

资源 URL 设计来源于 DDD 领域建模就非常简单了，聚合根作为根 URL，实体作为二级 URI 设计。聚合根之间应该彻底没有任何联系，实体和聚合根之间的责任应该明确。

产生这类问题的根源还是缺乏合理的抽象。如果存在 API 中可以通过用户组操作用户，通过用户的 URI 操作用户属于的用户组，这其中的问题是缺少了成员这一概念。用户组下面的本质上并不是用户，而是用户和用户组的关系，即成员。

版本化

一个对外开放的服务，极大的概率会发生变化。业务变化可能修改 API 参数或响应数据结构，以及资源之间的关系。一般来说，字段的增加不会影响旧的客户端运行。但是当存在一些破坏性修改时，就需要使用新的版本将数据导向到新的资源地址。

版本信息的传输，可以通过下面几种方式

URI 前缀
Header
Query

比较推荐的做法是使用 URI 前缀，例如/v1/users/表达获取 v1 版本下的用户列表。

常见的反模式是通过增加 URI 后缀来实现的，例如/users/1/updateV2。这样做的缺陷是版本信息侵入到业务逻辑中，对路由的统一管理带来不便。

使用 Header 和 Query 发送版本信息则较为相似，不同之处在于，使用 URI 前缀在 MVC 框架中实现相对简单，只需要定义好路由即可。使用 Header 和 Query 还需要编写额外的拦截器。

合理命名

设计 API 时候的命名涉及多个地方：URI、请求参数、响应数据等。通常来说最主要，也是最难的一个是全局命名统一。

其次，命名需要注意这些：

尽可能和领域名词保持一致，例如聚合根、实体、事件等
RESTful 设计的 URI 中使用名词复数
尽可能不要过度简写，例如将 user 简写成usr
尽可能使用不需要编码的字符

用领域名词来对 API 设计命名不是一件特别难的事情。识别出的领域名词可以直接作为 URI 来使用。如果存在多个单词的连接可以使用中横线，例如 /orders/1/order-items

安全

安全是任何一项软件设计都必须要考虑的事情，对于 API 设计来说，暴露给内部系统的 API 和开放给外部系统的 API 略有不同。

内部系统，更多的是考虑是否足够健壮。对接收的数据有足够的验证，并给出错误信息，而不是什么信息都接收，然后内部业务逻辑应该边界值的影响变得莫名其妙。

而对于外部系统的 API 则有更多的挑战。

错误的调用方式
接口滥用
浏览器消费 API 时因安全漏洞导致的非法访问

所以设计 API 时应该考虑响应的应对措施。针对错误的调用方式，API 不应该进入业务处理流程，及时给出错误信息；对于接口滥用的情况，需要做一些限速的方案；对于一些浏览器消费者的问题，可以在让 API 返回一些安全增强头部，例如：X-XSS-Protection、Content-Security-Policy 等。