/tags/rest/ Recent content in rest on Hugo -- gohugo.io en Sun, 26 Apr 2026 12:45:14 +0800 /posts/api-versioning-strategies/ Sun, 26 Apr 2026 12:45:14 +0800 /posts/api-versioning-strategies/ API 版本管理是微服务架构中一个看似简单、实则充满细节的话题。客户端很多，升级节奏也各不相同，一个"破坏性变更"稍有不慎就可能让线上支付或推送流程出问题。本文尝试梳理四种主流策略，并逐一对比 Spring Boot 4 原生支持与历史实现方案，最后总结生产环境中常见的问题。 为什么需要版本管理 REST API 一旦对外发布，就变成了一份"隐式合同"。只要还有一个客户端在运行，你就不能随意更改字段含义、删除字段或修改响应结构。版本管理的本质，是为破坏性变更（Breaking Change）提供一条可控的演进通道，让新旧客户端能在同一套基础设施上共存。 什么算 Breaking Change？ 删除或重命名字段 修改字段类型（如 amount: int → amount: BigDecimal） 修改 HTTP 状态码语义 业务流程从同步改为异步 认证机制变更（如从 API Key 改为 OAuth2） 非破坏性变更（如新增可选字段、新增接口）通常不需要升版本。 四种主流策略 1. URL 路径版本化 版本号嵌入 URL 路径，是目前很常见的方案，Stripe、GitHub、PayPal 等公开 API 也都能看到这种风格。 GET /api/v1/payments GET /api/v2/payments 优点： 直观、易调试、网关路由配置简单（前缀匹配）、Swagger 文档可以生成完全隔离的两套页面。 缺点： 粒度较粗。90% 的接口没有变化，但客户端却需要将所有调用路径从 /v1/ 改为 /v2/。 关于 /api/v1/payments 与 /api/payments/v1 的选择：前者将版本视为整个 API 服务的快照，网关路由更友好；后者将版本视为某个资源的属性，粒度更细但运维复杂度更高。在我接触到的大多数团队里，前者更常见。 2. 查询参数版本化 版本号以 Query Parameter 的形式传递： GET /api/payments?version=1 GET /api/payments?