API与接口设计

为什么接口会反过来咬你

代码写得快，接口欠债却要还很久。常见的翻车场景并不复杂：一个没写进文档的字段顺序，被下游用来做展示排序；一段顺手返回的错误文案，被用户的正则表达式依赖；一次响应时间的细微抖动，成为某个超时重试逻辑的假设。这类行为在发布那一刻没人承诺，但一旦有人依赖，就成了事实契约——这正是 Hyrum's Law 的核心含义。

更隐蔽的还有版本问题。当不同调用方需要同一个依赖或 API 的不同版本时，diamond dependency 会让升级变成一场赌博：你改了一版，另一条链路却悄悄回退到旧行为。

这个技能怎么做

它不教你怎么把接口"写得好看"，而是给一套让接口难以误用的约束。

• 有意暴露可观察行为。 凡是用户能观察到的东西——字段、错误文本、时序、顺序——都默认会变成承诺。设计时要逐项确认：这是我愿意长期维护的吗？
• 不泄漏实现细节。 如果用户可以看到它，就会依赖它。内部结构、临时错误码、中间态字段都应藏在边界之后，只通过 interface 暴露稳定形状。
• 契约先行（Contract First）。 先定义接口，再写实现。例如先声明 createTask(input) 返回服务端生成字段的任务对象，实现只是填充这份规格。契约本身就是文档，测试也照着它写。
• 单一版本，扩展而非分叉。 设计一个同一时间只存在一个版本的世界：新增能力靠扩展字段、可选参数和默认值，而不是复制一套 v1/v2。
• 设计阶段就规划废弃。 公开出去的东西迟早要改，迁移路径要在定义契约时一起想清楚，而不是事后补救。

适用边界与注意点

• 覆盖 REST API、GraphQL schema、模块边界、组件 props，以及任何两段代码互相通信的表面。
• 典型场景：设计新端点、定义跨团队契约、创建组件 props 接口、确立影响 API 形状的数据库 schema、修改已有公开接口。
• 注意：契约测试再完整，也挡不住依赖未文档化行为的用户；破坏性变更需要配合废弃与迁移策略，而不是直接重写。