系统接口规范：把约定变成文档

命名：资源导向

URL 用名词不用动词：/users/{id}/orders 而不是 /getUserOrders。方法语义固定：GET 读取、POST 创建、PUT 全量更新、PATCH 局部更新、DELETE 删除。团队里最常见的争论（「这个接口用 POST 还是 PUT」）在规范定死后自然消失。

版本：路径式

/v1/ 起步，大版本升级才动路径。三条纪律：字段只增不减；废弃字段先标记后移除（至少留一个版本周期）；版本变更写 changelog。这些纪律在开发模式的里程碑里要作为验收项。

错误码：两层结构

HTTP 状态码表大类（4xx 客户端错、5xx 服务端错），业务错误码表细节（六位数字：前三位模块、后三位具体错误）。错误响应必须带三个字段：code（机器读）、message（人读）、traceId（排查用）。没有 traceId 的报错信息，排查全靠猜。

文档标准

• 每个接口：用途一句话、请求响应各一个完整示例、错误码列表。
• 全局说明：鉴权方式、限流规则、时间格式（建议 ISO 8601 + UTC）。
• 文档与代码同仓库，改接口必须同步改文档。

联调检查清单

联调前过一遍：双方时钟同步（NTP）、出口 IP 白名单互认、沙箱数据覆盖边界场景、回调地址可公网访问。联调中的验签、重试、幂等细节，以及数据层面的迁移核对，都在上线流程检查点里有对应条目。