API设计的几条原则
极客时间编辑部
讲述：丁婵大小：8.11M时长：05:54
你好，欢迎收听极客视点。
通常来说，一个好的 API 设计需要满足两个主要目的：
一是平台独立性。任何客户端都能消费 API，而不需要关注系统内部实现。API 应该使用标准的协议和消息格式对外部提供服务。传输协议和传输格式不应该侵入到业务逻辑中，也就是系统应该具备随时支持不同传输协议和消息格式的能力。
二是系统可靠性。在 API 已经被发布和非 API 版本改变的情况下，API 应该对契约负责，不应该导致数据格式发生破坏性的修改。在 API 需要重大更新时，使用版本升级的方式修改，并对旧版本预留下线时间窗口。
实践中发现，API 设计是一件很难的事情，同时也很难衡量设计是否优秀。根据系统设计和消费者的角度，以下是一些简单的设计原则。
1. 使用成熟度合适的 RESTful API
RESTful 风格的 API 具有一些天然的优势，例如通过 HTTP 协议降低了客户端的耦合，具有极好的开放性。因此越来越多的开发者使用 RESTful 这种风格设计 API，但是 RESTful 只能算是一个设计思想或理念，不是一个 API 规范，没有一些具体的约束条件。
因此在设计 RESTful 风格的 API 的时候，需要参考 RESTful 成熟度模型。
2. 避免简单封装
API 应该服务业务能力的封装，避免简单封装让 API 彻底变成了数据库操作接口。例如标记订单状态为已支付，应该提供形如 POST /orders/1/pay 这样的 API，而非 PATCH /orders/1，然后通过具体的字段更新订单。
因为订单支付是有具体的业务逻辑，可能涉及到大量复杂的操作，使用简单的更新操作将业务逻辑泄露到系统之外。同时系统外也需要知道“订单状态”这个内部使用的字段。
更重要的是，破坏了业务逻辑的封装，同时也会影响其他非功能需求。例如，权限控制、日志记录、通知等。
3. 完全穷尽，彼此独立
API 之间尽量遵守完全穷尽，彼此独立 (MECE) 原则，不应该提供相互叠加的 API。这样的好处是不会存在重复的 API，造成维护和理解上的复杂性。如何做到完全穷尽和彼此独立呢？
简单的方法是使用一个表格设计 API，标出每个 URI 具备的能力。
资源 URL 设计来源于 DDD 领域建模就非常简单了，聚合根作为根 URL，实体作为二级 URI 设计。聚合根之间应该彻底没有任何联系，实体和聚合根之间的责任应该明确。
产生这类问题的根源还是缺乏合理的抽象。如果存在 API 中可以通过用户组操作用户，通过用户的 URI 操作用户属于的用户组，这其中的问题是缺少了成员这一概念。用户组下面的本质上并不是用户，而是用户和用户组的关系，即成员。
4. 版本化
一个对外开放的服务，极大的概率会发生变化。业务变化可能修改 API 参数或响应数据结构，以及资源之间的关系。一般来说，字段的增加不会影响旧的客户端运行。但是当存在一些破坏性修改时，就需要使用新的版本将数据导向到新的资源地址。
版本信息的传输，可以通过 URI 前缀、Header、Query 这几种方式。
5. 合理命名
设计 API 时候的命名涉及多个地方：URI、请求参数、响应数据等。通常来说最主要，也是最难的一点是全局命名统一。
其次，命名需要注意这些：
尽可能和领域名词保持一致，例如聚合根、实体、事件等
RESTful 设计的 URI 中使用名词复数
尽可能不要过度简写
尽可能使用不需要编码的字符
用领域名词来对 API 设计命名不是一件特别难的事情。识别出的领域名词可以直接作为 URI 来使用。如果存在多个单词的连接可以使用中横线。
6. 安全
安全是任何一项软件设计都必须要考虑的事情，对于 API 设计来说，暴露给内部系统的 API 和开放给外部系统的 API 略有不同。
内部系统，更多的是考虑是否足够健壮。对接收的数据有足够的验证，并给出错误信息，而不是什么信息都接收，然后内部业务逻辑由于边界值的影响变得莫名其妙。
而对于外部系统的 API 则有更多的挑战：
错误的调用方式
接口滥用
浏览器消费 API 时因安全漏洞导致的非法访问
所以设计 API 时应该考虑相应的应对措施。针对错误的调用方式，API 不应该进入业务处理流程，及时给出错误信息；对于接口滥用的情况，需要做一些限速的方案；对于一些浏览器消费者的问题，可以在让 API 返回一些安全增强头部。
以上就是今天的内容，希望能给你带来参考价值。
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线笔记
复制
AI
- 深入了解
- 翻译
- 解释
- 总结
该免费文章来自《极客视点》，如需阅读全部文章，
请先领取课程
请先领取课程
免费领取
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
登录 后留言
全部留言(1)
- 最新
- 精选
小斧设计 API 时应该考虑相应的应对措施。针对错误的调用方式，API 不应该进入业务处理流程，及时给出错误信息；对于接口滥用的情况，需要做一些限速的方案；对于一些浏览器消费者的问题，可以在让 API 返回一些安全增强头部。1
收起评论