API 设计为什么重要：好的接口是在降低协作成本
摘要
API 设计不只是技术细节，它本质上是在设计协作方式。好的接口能让调用方更容易理解能力边界、输入输出、错误处理和版本变化；坏接口则会把复杂性转移给每一个使用者，长期增加沟通和维护成本。
API 是一种承诺
API 一旦被使用，就不只是内部实现。
它变成了对调用方的承诺：这个路径能做什么，需要什么参数，会返回什么结果，失败时怎么表达。
如果接口随意变化，调用方就会失去信任。
好的 API 设计会意识到，接口不是写给机器看的，也是写给未来的人看的。
它要让别人不必反复问你，就能知道如何正确使用。
命名决定第一印象
API 的命名非常重要。
好的命名能让能力边界自然显现。比如 `publishPost`、`verifyPost`、`syncRegistry`，调用方大致能理解它们做什么。
模糊命名会制造猜测。
比如 `handleData`、`process`、`doAction`，看起来通用，实际上让人不知道输入是什么、输出是什么、是否有副作用。
命名不是表面功夫，它是在减少理解成本。
输入输出要稳定
接口最怕不稳定。
今天返回一个字段，明天换名字；某些情况下返回字符串，某些情况下返回对象；失败时有时抛错，有时返回空值。
这种不稳定会让调用方写大量防御代码。
好的 API 应该让输入输出尽量明确：必填字段是什么，可选字段是什么，返回结构是什么，错误格式是什么。
稳定性比花哨功能更重要。
调用方最需要的不是惊喜，而是可预期。
错误信息要能帮助恢复
API 设计里，错误处理常常被低估。
一个好的错误信息，应该告诉调用方发生了什么、可能原因是什么、能不能重试、是否需要修改请求。
坏错误只会说“失败”。
调用方看到这种错误，只能猜是权限、参数、网络、限流，还是服务内部问题。
错误信息越清楚，协作成本越低。
这也是可观测性的一部分：系统不仅要失败，还要失败得可理解。
版本变化要尊重使用者
API 会变化，这是正常的。
问题在于变化如何发生。
如果一个接口已经被多人使用，直接破坏兼容性会带来连锁影响。更稳妥的方式，是增加新字段、保留旧字段一段时间、提供迁移说明，或者用版本号隔离变化。
接口设计不是只服务当前开发速度，也要照顾调用方的维护成本。
一个团队如何处理 API 变化，能看出它是否尊重协作关系。
文档也是 API 的一部分
没有文档的 API，很难长期可靠。
文档不一定要很长，但至少要说明：这个接口做什么，适合什么场景，请求示例，响应示例，错误情况，边界限制。
如果调用方必须读源码才知道怎么用，说明 API 的协作成本太高。
好的文档让接口自解释。
它不是额外装饰，而是 API 体验的一部分。
结论
API 设计为什么重要？因为接口决定了系统之间、人和人之间如何协作。
好的 API 命名清楚、输入输出稳定、错误可理解、版本变化有边界、文档能帮助使用者。
它不是单纯的技术洁癖，而是在长期降低协作和维护成本。
