API 版本管理策略：来自生产事故和修复的真实教训
Source: Dev.to
（请提供需要翻译的正文内容，我将按照您的要求保留链接、格式和代码块，仅翻译正文文本。）
介绍
当你意识到刚刚上线的全新 API 更改把生产环境中一半的客户端都砸坏时，那种沉重的感觉真是无可比拟。我们都有过这种经历——不止一次。如果你还没有经历过，总有一天会遇到。让我们坦诚地讨论一下，在用户把邮件塞满你的收件箱之前，如何处理会导致破坏性的 API 更改。
不管你计划得多么周全，业务需求总会变化。数据模型会演进。你在 2018 年设计的 UserDTO 现在缺少字段，出现了你后悔的字段，并且出于没人记得的原因使用了 camelCase。有时候，你只能破坏一些东西。
但在深思熟虑地进行破坏和放任混乱之间，差距是巨大的。让我们来看看真正的选项。我在 C#/.NET（Web API、Clean Architecture）、Python（FastAPI）以及与使用 React 的前端团队集成时，都曾面对并处理过这些问题。
URI 版本控制
示例: /api/v1/orders, /api/v2/orders
优点
- 易于实现和发现
- 多个版本可以并行运行
缺点
- 客户端可能会忽略更新的版本
- 如果不小心，你会永远需要支持
/v1
实际情况:
/v1 被保留“仅几个月”。两年后，它仍然存在，流量惊人。淘汰旧版本是一个项目，而不是一个开关。
Header 版本控制
示例:
GET /orders
Api-Version: 2优点
- 保持 URL 干净
- 允许在细粒度层面（每个资源）进行版本控制
缺点
- 人类调试更困难
- 某些代理和工具会剥离自定义头部（我吃了大亏才发现）
生产痛点:（为简洁起见省略细节）
查询参数版本控制
示例: /orders?version=2
优点
- 简单测试和部署
- 对客户端可见
缺点
- 感觉有点 hack（虽然有时也可以接受）
- 可能使缓存和路由更复杂
Lessons Learned
- 支持多个版本一段时间。 提前规划；不要假设所有人都会在第一天就升级。
- 提前且大声地沟通破坏性更改。 使用内部文档、变更日志和 Slack 提醒。先假设没人会阅读，然后再提醒一次。
- 在所有受支持的版本上自动化测试。 只在 CI 中检查 v2？那是未来的事故在等着发生。
- 制定切实可行的停用政策。 要准备好与那个从不迁移的关键合作伙伴进行谈判。
代码示例：ASP.NET Core 中的最小化版本控制
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
[HttpGet]
public IActionResult Get() { /* ... */ }
}您可以将其与 Microsoft.AspNetCore.Mvc.Versioning 结合使用，以获得更大的灵活性。请记住，之后再添加版本控制要比一开始就引入它困难得多。
面向前端团队的契约优先方法
React 开发者讨厌意外。我们曾因删除一个字段而破坏了契约。结果如何？前端崩溃，用户看到空白页面，大家都不满意。
解决方案： 使用 OpenAPI 规范作为契约。
- 使用类似 openapi-typescript 的工具为 React 自动生成类型。
- 在 CI 中运行契约测试，以在部署前捕获破坏性更改。
何时进行破坏性更改（以及何时不该）
- 只有在必须时才进行破坏性更改。 如果可以通过弃用字段或添加新字段而不导致破坏，请这样做。
- 批量进行破坏性更改。 如果你要推出 v2，请让它有意义。不要为每一个细微的改动都创建新版本。
- 为客户端提供迁移路径。 使用功能标记、双写，或在一段时间内同时接受旧格式和新格式。
我们今天可以做的事
- 现在就选择版本管理策略，而不是以后。 即使你认为不需要，可能也会需要。
- 自动化向后兼容性测试。 不要指望自己记住所有边缘情况。
- 编写文档并进行沟通。 文档固然重要，但 Slack 提醒和真实对话可以防止意外。
- 毫不留情地淘汰旧版本。 预期会有阻力，但必须执行。
如果你经历过一次棘手的 API 版本管理事故（或者强烈不同意我的做法），我真诚想听你的故事。你遇到过最糟糕的版本管理痛点是什么？或者，如果你找到了一种真正让你轻松的策略，请在评论中分享。