API 文档对接：文档质量就是对接成本

判断文档质量的五个信号

• 每个接口有完整的请求/响应示例，而不是只有字段表。
• 错误码有明确语义和分类，不是清一色的「system error」。
• 写明了限流规则和配额，而不是等你超了才发现。
• 有沙箱环境且数据可复现。
• 版本变更历史可查，废弃接口有迁移说明。

五个信号缺两个以上，对接周期建议按双倍估。

接口治理怎么做

包网平台的接口数量上来之后，要有治理动作：所有接口登记入册（用途、负责人、状态）、按业务域分组、废弃接口定期清理。没有登记册的平台，半年之后没人说得清哪些接口还在被调用。

版本管理规范

URL 路径带版本号（/v1/、/v2/）是务实的选择。升级策略提前和对方约定：旧版本保留多久、字段只增不减的原则怎么执行。字段级别的兼容性破坏，是联调返工的最大来源，处理思路参见一体化方案里的模块边界设计。

监控与告警

每个外部接口监控三个指标：成功率、延迟分位数（P95/P99）、调用量。告警阈值分层：连续失败告警、延迟突增预警、调用量异常（可能是被刷）提示。接口监控数据要留存，是和外部服务方扯皮时的唯一凭据。