# API契约比演示更长久，《API设计模式》该这样读

> 先从资源而非端点入手，再把精力放在客户集成最常出问题的三处：长时间运行操作、重试和版本管理。

原文: https://fdetimes.net/zh/books-courses/api-design-patterns-reading-order-fde/

前线部署工程师（FDE）离开客户之后，留存最久的很少是演示或幻灯片，而是 API 契约：资源叫什么名字、怎么调用、错误怎么报告。客户团队会在这些决定之上继续写好几年代码。

所以，一本 2021 年的书依然值得放在桌上。JJ Geewax 所著的 *API Design Patterns* 由 Manning 于 2021 年出版。出版方称它汇集了一系列适用于内部 API 和对外 API 的设计原则。

Manning 表示，这本书写给用任何语言构建 Web API 和内部 API 的开发者。FDE 既要把自家系统接到客户系统上，又要为客户设计端点，这几乎就是这份工作的写照。实际的问题是：第一次集成会议之前，该读哪些部分。

## 先从资源入手，而不是端点

第 1 章“Introduction to APIs”把 API 定义为计算机系统之间交互的方式。这一章讲基础概念及其意义：接口、围绕资源组织 API，以及什么样的 API 才算好。

听起来很初级，但正是这一层决定了契约。设想客户的某个内部 API 里，`getOrder`、`fetch_customer` 和 `LoadInvoiceData` 并排存在。

API 照样能用，但调用方猜不出下一个端点叫什么。先按资源思考（订单、客户、发票），就能指出问题所在，又不会让讨论变成个人口味之争。

System Design Space 上的本书摘要，开篇是一组被称为“API 即产品与契约”的观点。这种归类出自摘要作者，而非 Manning 的目录，但抓住了要义：资源层一旦设计错，后面的每个模式都得绕着它打补丁。

## 长时间运行的操作，最先让集成出问题

Nicolas Fränkel 在 DEV Community 上的书评证实，书中有一个模式专门处理不会立即返回结果的方法。System Design Space 的摘要将其概括为：把启动操作与获取结果分开，并配以清晰的状态语义。

假设你在为一家保险公司部署文档处理数据管道。每批要处理好几分钟，而客户网关 30 秒就断开连接。如果端点等处理完成才响应，客户就会看到报错，尽管任务其实还在运行。

这个模式的做法是立即返回一个带状态的操作，由客户端轮询。客户拿到的不再是一个含糊的错误，而是一个可以追踪的对象。

## 从第一天起就问重试和版本管理

Fränkel 还证实书中有一章名为“Request retrial”，讲如何用算法安全地重试请求。摘要建议为重要的写操作使用请求标识符和幂等键，并配合一套统一的结构化错误格式。

看一个假设的例子：客户的 ERP 发送 1,000 个创建订单的请求。其中 20 个在网络上超时，但服务端其实已经写入，于是 ERP 把这 20 个全部重发。

没有幂等，客户最终会有 1,020 个订单，其中 20 个重复，而发现问题的是财务部门，不是你。有了幂等键，第二次调用只会拿到第一次的结果。

最后一个主题是“Versioning and compatibility”一章，它定义了兼容性的含义，并给出几种版本管理策略。摘要把向后兼容的变更列为默认策略。新增一个可选字段，旧客户端照常运行；把某个字段改成必填，客户团队写过的所有脚本可能同时出错。

**要点:** 你留给客户的 API 契约，会比你的项目周期活得更久。

## 给手上有项目的人的阅读顺序

如果下周就有集成会议，先读第 1 章，再读长时间运行操作、安全重试，最后读版本管理。上面的章节名来自一篇书评和一份摘要，请对照你手中版本的目录找到对应部分。其余内容留到空闲时再读。

Fränkel 向所有刚接触 API 的开发者推荐这本书，但也指出它作为参考手册还不够。对 FDE 来说，这意味着别等出了事故才翻开它找答案。提前读完上面这几部分，再列出自己要带去见客户的问题清单。

## 浪费这本书的两种方式

第一个错误是跳过第 1 章，直接去读重试或长时间运行操作。这些模式都建立在资源之上。资源命名一团乱，再好的模式也只会让契约更纠缠。

第二个错误是把书中的模式硬套到客户已经在生产环境运行的 API 上。System Design Space 的摘要把向后兼容的变更视为默认的版本管理策略。按这个思路，大批量重命名别人已经在用的端点，等于自己制造事故。

把这些模式用在即将新增的部分，而不是拆掉已经运转良好的东西。

## 在简历上证明这一点

简历上不要列这本书。要写你留下的契约以及它的实际表现，例如“设计带幂等键的集成 API；客户开启重试后未出现重复订单”。招聘启事里提到“设计 API”或“构建集成”时，面试中就讲这个故事。

读书的目的不是背模式，而是在下一次会议上第一个问出：“这个调用如果执行两次，会发生什么？”

**本周动手试试:**

- 在 Manning 的 liveBook 上读第 1 章，然后写下你正在对接的 API 有哪些资源：每个叫什么、属于哪个资源。
- 在当前项目里挑一个写数据的端点，问一句：如果客户系统在超时后再调用一次，会发生什么？把答案记进设计文档。
- 列出所有可能超过客户超时时间的操作，再为每个操作草拟一种返回状态、供客户端轮询的方式。

## 信源

- [API Design Patterns (Manning Publications)](https://www.manning.com/books/api-design-patterns)

- [API Design Patterns, Chapter 1: Introduction to APIs (Manning livebook)](https://livebook.manning.com/book/api-design-patterns/chapter-1)

- [API Design Patterns (short summary), System Design Space](https://system-design.space/en/chapter/api-design-patterns-book)

- [API Design Patterns (Nicolas Fränkel, DEV Community)](https://dev.to/nfrankel/api-design-patterns-5208)

- [API Design Patterns, 1st edition (Pearson)](https://www.pearson.com/store/en-gb/p/api-design-patterns/P200000004835/9781617295850)