API 合约
合约是对你无法控制、也无法修复的代码做出的承诺。这就是 API 变更与内部重构的区别:错误的成本由别人承担,在你无法选择的时间发生。
设计
将资源命名为名词,让方法携带动词。建模的是事物本身,而不是当前显示它的界面——一个围绕今日 UI 形状构造的负载,会在下次重新设计时变得不合时宜。
对于你所暴露的内容要深思熟虑。你返回的每一个字段,都必须保持返回。内部标识符、行版本号和实现细节会将你的模式泄露到调用方的代码中,并固化为该代码的一部分。
让操作具有幂等性,适用于调用方可能重试的任何场景——也就是任何通过网络可达的操作。对于任何创建或收费的操作,给调用方一个幂等键,这样超时后的重试不会导致重复操作。
返回一致的错误模型:一个稳定的机器可读代码、一个人类可读的消息,以及验证失败所涉及的字段。调用方依据代码进行分支,因此代码是合约的一部分——即使结构不变,更改代码也是一种破坏性变更。
对每个列表都进行分页,从第一个版本开始。一个返回全量数据的端点,在表不断变大之前工作良好,然后在拥有最多数据的客户那里崩溃。当行被并发插入时,优先使用游标而非偏移量。
什么会破坏调用方
破坏性变更,无论模式语言允许什么:
- 删除或重命名字段、端点、方法或枚举值。
- 将可选请求字段变为必填,或缩小字段的接受范围。
- 更改类型,包括将整数改为字符串、将单个值改为列表。
- 保持字段名称和类型不变但改变其含义——最糟糕的一种,因为没有事物会大声失败,而数据会静默地变错。
- 在请求中添加新的必填字段。
- 针对已有条件更改错误码或 HTTP 状态码。
- 收紧默认值,或更改字段被省略时的行为。
安全:添加可选请求字段、添加响应字段、添加新端点或方法、添加枚举值仅当所有消费者已经能够容忍未知值——请验证这一点,而不要假设。
在 protobuf 中,切勿重用或重新编号字段标签,并且在移除字段时保留标签和名称。重用的标签会将旧数据解码到新字段中并静默地损坏它。
安全地变更合约
先添加再删除,并使两者至少在一个发布周期内同时工作:
- 在旧字段或方法旁边添加新字段或方法。
- 两者都写入,读取新字段并回退到旧字段。
- 迁移消费者,并确认每个消费者已完成迁移。
- 在后续发布中移除旧路径。
当资源的含义真正改变时才进行版本控制,而不是为每次添加都创建新版本。每次变更都创建一个版本会倍增你需要维护的表面区域。
部署顺序
生成的代码和服务器分别部署,中间的间隙就是故障发生的地方。首先推出能够容忍两种形态的一方:生产者发射新字段之前,消费者接受新字段;调用方发送新请求之前,生产者接受新请求。
当模式通过网关、代理或生成的客户端共享时,链路上的每个组件都需要重新生成和重新部署。在服务中添加但未在服务前端层中添加的字段,在到达调用方之前就会消失,而服务自身的测试是注意不到的。
验证
在改变形态之前检查实际消费者——通过 grep 调用方代码,而不是相信合约的文档。
测试合约本身:一个断言序列化形状的测试,能够捕获意外的重命名事件,而仅针对处理程序进行的单元测试会完全漏掉该事件。