题干与适用场景
提供方希望在迁移窗口后移除 /v1/items，但客户端属于不同团队，其中一些长期不活跃。假设提供方能按客户端身份观察请求，并可并行运行 /v2/items。方案必须区分弃用通知和移除日期，保留安全回退，不能假设仅凭响应头就能迁移客户端。
面试官考察点
- 区分协议提示、文档、客户端清单和执行措施。
- 设计增量兼容与可度量的迁移门槛。
- 处理未知客户端、长期集成和紧急回滚。
- 选择状态码和响应头，不超出标准定义自行发明语义。
回答前需要澄清的问题
确认客户端是否发送稳定身份、/v2 是否能增量兼容、最短支持期、合同通知要求，以及移除前是否能只读。若缺少身份，迁移证据应来自凭证、网络元数据或显式注册，而不是猜测 User-Agent。
30 秒回答框架
我会盘点调用方，发布版本化迁移指南，增量上线 /v2，并按客户端测量流量和错误对等性。给 /v1 响应加标准 Deprecation 信号和 Sunset 日期，同时提供仪表板并通知已知负责人。保持旧路径到明确窗口结束，满足证据门槛后才执行，返回有文档的终止响应和迁移链接。用功能开关和可逆路由支持关键客户端出问题时回滚。
分步骤深入解答
1. 建立兼容性和证据
定义字段差异、默认行为、分页、错误和认证变化。对两个版本运行契约测试并比较代表性响应。指标按客户端、版本、端点、状态和迁移阶段标记；不能只看汇总流量，因为低流量客户端可能很关键。
2. 精确表达弃用信号
Deprecation 响应头表示资源已弃用；Sunset 响应头表示计划停止提供的日期。它们只是信号，不能保证每个客户端都会理解。文档和负责人通知中重复日期，并在响应体或 API 契约定义的 Link 关系中提供稳定迁移引用。
3. 分阶段迁移与执行
先发出警告并建立仪表板，再要求未达目标的客户端申请明确例外。提供影子比较或选择加入的流量后再切换默认版本。执行门槛到达后，只拒绝可以安全退役的旧操作，返回机器可读错误并保留支持路径。风险不同的场景可让只读兼容期长于写入兼容期。
4. 让回滚和治理可执行
在变更记录中保存日落日期、负责人、例外原因和审批。监控迁移后的错误差异和未知客户端请求。旧路径通过功能开关路由，回滚只需改配置而非重新部署。移除后保留足够长的遥测和墓碑响应，解释失败但不泄露密钥。
高质量示范回答
我会先盘点 1 万个调用方，明确 /v1 到 /v2 的契约差异。两个版本并行运行，按客户端收集指标并执行契约测试。/v1 响应携带 Deprecation 和 Sunset 信号，文档与负责人通知重复日期和步骤。提供方经过警告、选择加入、默认 v2、执行四阶段，并支持明确例外和机器可读终止错误。功能开关保证可回滚，日落门槛依据客户端证据，而不是汇总流量百分比。
常见错误
- 认为响应头会自动迁移 → 许多客户端会忽略 → 结合标准信号、负责人发现和迁移指南。
- 没有清单就设日期 → 休眠但关键的客户端会突然失败 → 要求客户端身份和例外审查。
- 只比较总错误率 → 单租户故障会淹没在平均值里 → 监控每客户端对等性和流量。
/v2上线后立即删除 → 客户端没有兼容证据 → 先并行或选择加入。- 回滚必须重新部署 → 故障时恢复缓慢 → 用可逆开关路由版本。
- 日落时返回无文档的 404 → 自动化无法区分退役和拼写错误 → 发布稳定终止错误和迁移引用。
追问及应对
客户端从不发送身份头，迁移门槛是什么？
使用提供方已有的凭证、账户、网络或注册身份。没有可靠身份时延长旧端点支持期，并在执行前要求显式注册。
Sunset 日期可以调整吗？
可以，但必须同步更新变更记录、文档、响应头和负责人通知。把日期当作治理承诺，并持续提醒仍依赖旧路径的客户端。
/v2 正确但某个客户端更慢，怎么办？
单独比较该客户端的延迟和错误预算，再优化或授予有时限例外。没有证据证明是系统性问题时，不要延长所有客户端的日落窗口。
如何安全退役写入端点？
证据门槛通过后停止新写入，尽可能保留读取，并让重试返回确定性终止错误。移除前确认下游队列和审计记录不再依赖旧写入。