API 契约设计

接口为何越改越脆弱

当你的 API 被多个团队调用后，一些奇怪的事情开始发生：有人依赖了 404 响应中的特定错误消息文本，有人习惯了某个端点返回字段的顺序，还有人用着你没写进文档的边角行为。这就是 Hyrum's Law 的现实——只要有足够多的用户，你所有的可观测行为都会被某人依赖。

结果就是：你以为是"安全"的重构，却让线上用户的应用突然崩溃。接口文档和实现逐渐脱节，新团队成员面对混乱的错误格式和随意的命名，只能在复制粘贴中摸索。

从契约开始，而非从实现开始

这个技能把"设计稳定接口"拆成可执行的步骤。核心是两条定律：贺拉斯定律提醒你，所有可观测行为都会被依赖，所以设计时就规划弃用策略；单一版本规则避免让消费者在多个版本间二选一，而是通过扩展而非分叉来演进。

具体执行时遵循五条原则：

• 契约优先：先定义接口契约，实现跟随契约，而非反过来
• 一致的错误语义：全局统一错误格式，比如 REST 用 HTTP 状态码 + {error:{code, message, details?}} 结构，绝不混用不同模式
• 边界处校验：只在系统边缘（API 路由、表单提交、第三方响应）校验输入，内部代码间信任类型契约
• 偏好新增而非修改：用可选字段扩展接口，不破坏既有消费者
• 可预测命名：REST 用复数名词、camelCase 字段、is/has/can 布尔前缀

对于 REST API，它规定了资源设计的标准方法（GET 列表/详情、POST 创建、PATCH 局部更新、DELETE 删除），列表端点必须分页，过滤用查询参数。对于 TypeScript 场景，它推荐可辨识联合、输入/输出分离、branded types 防止 ID 混用。

什么时候不该用它

这个技能面向需要长期维护的公开接口、团队间契约和组件 props。如果你只是写一个内部一次性的临时变量，它可能显得太重——不过即便如此，至少也该有个类型契约。

它不会替你写实现代码，而是输出结构化的 ApiDesign 工件，可以交给下游的 spec-driven-development、incremental-implementation、deprecation-and-migration 等技能继续处理。