核心问题

边界两侧如何稳定协作？

API 不是函数签名，而是团队之间的条约。

它承诺输入、输出、错误、幂等性、版本、延迟、废弃策略和兼容边界。

工程映射

一个好的 API 契约要说明：

  • 成功返回什么
  • 失败有哪些 code
  • 是否幂等
  • 是否向后兼容
  • 如何 deprecate
  • 谁是 owner
  • 调用方如何测试

例如：

POST /orders/:orderId/refund

需要承诺重复请求是否安全、退款后访问权何时撤销、错误码如何表达。

小结

改 API 不是改一段代码，而是在修改两个团队之间的信任。