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

背景与价值 API下线需提前告知并提供指引。统一弃用与日落策略可以平滑迁移并减少中断。 统一规范 - 通知头：下发 `Deprecation` 与 `Sunset`、`Warning` 提示与时间。 - 迁移指引：通过 `Link` 提供替代接口文档与时间表。 - 宽限期：保障在宽限期内服务可用并收集使用数据。 核心实现 下发通知头 ```ts 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` 并指向迁移文档。