回答“API 从设计、发布、使用、版本演进到废弃下线，怎样不变成永久兼容包袱”
| 生命周期阶段 | 常见问题 | 治理判断 |
|---|---|---|
| 设计 | 接口按内部实现暴露，领域边界和错误语义混乱 | 先审业务语义、权限、幂等、分页、错误码和扩展方式 |
| 发布 | 文档、实现、Mock、SDK 和网关配置不一致 | API 发布必须绑定契约、测试、网关和可观测性 |
| 演进 | 改字段、改错误码、改默认行为导致静默破坏 | 兼容规则要覆盖结构、语义、默认值和错误行为 |
| 下线 | 没人知道还有谁在调用，只能永久保留旧接口 | 必须有消费者观测、弃用窗口、迁移通知和下线标准 |
| 阶段 | 必须回答的问题 | 产出物 |
|---|---|---|
| 设计准入 | 这个 API 属于哪个业务能力，谁是 owner，哪些消费者需要它，是否已有可复用接口。 | API 提案、领域语义、权限模型、幂等规则、错误模型和兼容策略。 |
| 契约冻结 | 字段、错误码、分页、排序、默认值、限制条件和敏感数据是否清楚。 | OpenAPI / Proto / Schema、Mock、示例、契约测试和变更记录。 |
| 发布接入 | 消费者如何发现、申请权限、拿到 SDK 或示例，调用失败时找谁。 | API 目录、接入指南、网关策略、Dashboard、告警和支持入口。 |
| 演进维护 | 新增字段是否兼容，语义变化如何标记，旧行为支持多久。 | 版本策略、变更公告、消费者影响面、灰度和回滚方案。 |
| 弃用迁移 | 谁还在调用旧 API，迁移成本多大，是否存在豁免消费者。 | 弃用公告、迁移指南、调用量看板、提醒节奏和例外审批。 |
| 下线验收 | 调用量是否归零，未知消费者是否清完，文档、SDK、网关和告警是否同步删除。 | 下线清单、回滚窗口、监控验证、服务目录更新和复盘记录。 |
| 变更类型 | 是否通常兼容 | 治理动作 |
|---|---|---|
| 新增可选字段 | 通常兼容，但消费者可能有严格反序列化或字段白名单。 | 先做契约测试和灰度，确认主要消费者不会因未知字段失败。 |
| 字段语义变化 | 通常不兼容，即使字段名和类型不变。 | 新增字段或新版本，旧字段进入弃用窗口，不允许静默改含义。 |
| 错误码 / 默认行为变化 | 高风险，消费者常把错误码和默认值写进流程。 | 提前公告，提供双行为窗口，观测旧错误码使用面。 |
| 权限和限流收紧 | 可能破坏已有消费者。 | 先识别调用方和业务影响，按消费者分批调整并提供申诉 / 豁免入口。 |
| 删除字段或接口 | 破坏性变更。 | 必须走弃用、迁移、调用归零、下线验收，不靠一次发布直接删除。 |
| 误区 | 为什么危险 | 修正方式 |
|---|---|---|
| API 上线就是生命周期结束 | 真实成本从消费方接入、兼容和下线才开始 | 把使用面观测和废弃策略纳入上线标准 |
| 大版本号能解决兼容问题 | 没有迁移窗口和消费者管理，多版本只会长期并存 | 版本号必须绑定迁移计划和下线机制 |
| 内部 API 不需要治理 | 内部调用同样会跨团队扩散并形成稳定承诺 | 按影响范围和消费者数量决定治理强度 |
| 检查项 | 最低要求 |
|---|---|
| 设计准入 | owner、用途、权限、幂等、错误码、分页、限流和数据语义明确 |
| 契约一致 | 文档、schema、SDK、Mock、测试和实现保持一致 |
| 观测接入 | 调用量、消费者、版本、错误率、延迟和弃用字段使用情况可见 |
| 版本规则 | 破坏性变更、弃用窗口、迁移指南和下线流程明确 |
| 安全边界 | 认证、授权、租户隔离、审计和敏感字段暴露已检查 |
| 登记字段 | 要写清楚什么 | 缺失后的后果 |
|---|---|---|
| API 身份 | 名称、业务能力、owner、版本、状态、服务归属、文档和支持入口 | 接口被调用多年后没人知道归谁维护、是否还能继续使用 |
| 契约与语义 | schema、字段含义、错误码、幂等键、分页规则、默认行为和兼容承诺 | 消费者按各自理解接入，字段语义一改就静默破坏 |
| 消费者画像 | 调用方、调用量、版本分布、业务路径、权限范围、SLO 和联系人 | 准备下线时不知道谁还在用，只能无限期保留旧接口 |
| 安全与合规 | 认证方式、授权模型、租户隔离、敏感字段、审计要求和限流策略 | API 生命周期只管可用性，不管数据暴露和越权风险 |
| 生命周期状态 | 草案、试用、稳定、弃用、冻结、下线的状态、进入条件和退出条件 | API 状态全靠口头约定，消费者无法判断是否应该接入 |
| 废弃迁移证据 | 最小内容 | 验收问题 |
|---|---|---|
| 弃用公告 | 弃用原因、替代 API、兼容窗口、迁移截止日、支持联系人和例外申请方式 | 消费者是否明确知道为什么迁、迁到哪里、什么时候必须完成？ |
| 影响面清单 | 消费者、调用量、版本、关键业务路径、权限范围和未知调用来源 | 是否还有未识别消费者或高影响业务路径？ |
| 迁移指南 | 字段映射、错误码变化、默认行为变化、权限变化、示例、SDK 和测试环境 | 消费者是否能不靠口头支持完成迁移？ |
| 迁移进度 | 消费者完成状态、验证结果、剩余调用量、豁免原因和二次提醒记录 | 旧接口调用量是否持续下降，还是只发过一次通知？ |
| 下线验收 | 调用归零、网关规则删除、文档归档、SDK 标记、告警清理和回滚窗口 | 下线后是否不会再出现未知消费者报警或幽灵文档入口？ |
| 场景 | 最小落地包 | 验收信号 |
|---|---|---|
| 新增跨团队 API | 先登记 owner、消费者、权限、SLO、schema、错误码和变更规则，再允许接入 | 消费方能从 API 目录找到文档、示例、告警入口和支持人 |
| 字段语义需要调整 | 禁止静默改语义；新增字段或版本，标注旧字段弃用窗口和迁移指南 | 老消费者不破坏，新消费者能按新语义接入，旧字段使用量持续下降 |
| 准备下线旧接口 | 先用网关和日志确认消费者，再公告、限流提醒、迁移验证，最后执行下线 | 下线前调用量归零或豁免明确，下线后无未知消费者报警 |
| 相关页 | 连接关系 |
|---|---|
| API / 系统集成 | API 生命周期治理是 API 集成从设计到下线的长期管理层 |
| 数据契约 | API schema、字段语义和兼容承诺需要契约治理支撑 |
| 认证与 IAM | API 权限、凭证、租户隔离和机器身份都要进入生命周期治理 |
| 服务目录与系统地图 | API 目录应能回到服务 owner、运行入口和依赖地图 |
| 依赖治理 | 高频 API 一旦被多人依赖，就需要按依赖资产治理 |