API弃用与迁移治理（Deprecation/Sunset/Warning）最佳实践

背景与价值API下线需提前告知并提供指引。统一弃用与日落策略可以平滑迁移并减少中断。统一规范通知头：下发 `Deprecation` 与 `Sunset`、`Warning` 提示与时间。迁移指引：通过 `Link` 提供替代接口文档与时间表。宽限期：保障在宽限期内服务可用并收集使用数据。核心实现下发通知头type Res = { setHeader: (k: string, v: string) => void; end: (b?: string) => void } function deprecate(res: Res, sunsetAt: Date, docUrl: string) { res.setHeader('Deprecation', new Date().toUTCString()) res.setHeader('Sunset', sunsetAt.toUTCString()) res.setHeader('Warning', `299 - "API deprecated; see ${docUrl}"`) res.setHeader('Link', `<${docUrl}>; rel="deprecation"`) } 落地建议为即将弃用的接口下发通知头并提供明确迁移文档与时间表。在宽限期内监控使用量并与调用方沟通，确保迁移成功。到期后返回合理错误码与提示信息，并保留必要的灰度支持。验证清单是否统一下发 `Deprecation/Sunset/Warning/Link` 并指向迁移文档。