1. 版本化策略概览
1.1 常见的版本化策略
版本化策略 是接口契约的核心，决定前后端在演进过程中的耦合方式与兼容性走向。URI版本化、请求头版本化、以及 媒体类型版本化 是最常见的三大方向，彼此在可维护性、易用性和前向兼容性上各有取舍。
在 SpringBoot 场景中，选择合适的版本化策略需要结合线上接口数量、对外生态以及客户端能力。URI版本化直观、路由清晰，但容易导致路由爆炸；请求头版本化保持端点稳定，利于内部治理，但对初学者不直观；媒体类型版本化实现了契约化的版本感，但对客户端支持要求更高。
{"策略": "URI版本化","示例": "/api/v1/pets"
}在大规模对外 API 场景中，混合使用也很常见，例如通过 URI 标识主版本，通过媒体类型或头部标识子版本，以实现渐进式演进。
1.2 版本号的语义设计
版本号通常采用 主版本号、次版本号、以及可选的 修订号 的组合，确保对外契约的清晰度。主版本号变更通常意味着向后不兼容的重大改动，而 次版本号变更往往伴随向后兼容的新增功能或修复。
在实践中，建议在 API 文档中明确标注 版本含义、弃用计划、以及对客户端的迁移路径，降低对接成本与误解。
1.3 生命周期与弃用
为避免版本堆积与维护压力，需要给每个版本设置明确的 生命周期。在落地实现时，通常包含 版本发布阶段、占用期、弃用通知期、以及最终移除阶段。通过这一路径，可以实现对旧版本的渐进退出，同时给客户端保留足够的迁移时间。
落地策略应当辅以 版本清单、时间线文档、以及 API 文档自动化生成，以便前端团队与合作方同步进度。
2. SpringBoot实现路径
2.1 基于URI的版本化实现
URI 路径版本化在 SpringBoot 中最直观，便于路由和文档一体化管理。每个版本拥有独立的路由，后续变更可以通过新增版本来实现，而非直接修改现有接口，从而降低对现有客户端的冲击。
优点：路由清晰、客户端易理解、版本切换显性化；缺点：路由数量随版本增多而增加，需要额外治理。以下示例展示了如何在 SpringBoot 中实现版本化路由。
// URI 路径版本化示例
@RestController
@RequestMapping("/api")
public class PetControllerV1 {@GetMapping("/v1/pets")public List<Pet> getPetsV1() {// 版本 1 的实现逻辑}
}@RestController
@RequestMapping("/api")
public class PetControllerV2 {@GetMapping("/v2/pets")public List<Pet> getPetsV2() {// 版本 2 的实现逻辑}
}
设计要点：把版本作为路由的一部分、确保文档可驱动生成、并在后端服务层实现中区分版本相关的业务逻辑分支。
2.2 基于请求头的版本化实现
通过请求头来表达版本，可以保持端点的稳定性，同时实现向后兼容的演进。常见写法是在 @RequestMapping 或 @GetMapping 上通过 headers 条件进行分发。
此法的优点在于端点不随版本改变，但对客户端需要具备正确的请求头能力，适合内部治理和多客户端共用同一组端点的场景。
// 基于请求头的版本化实现
@RestController
@RequestMapping("/api")
public class PetControllerHeader {@GetMapping(value = "/pets", headers = "X-API-VERSION=1")public List<Pet> getPetsV1() {// 版本 1 的实现}@GetMapping(value = "/pets", headers = "X-API-VERSION=2")public List<Pet> getPetsV2() {// 版本 2 的实现}
}
关键点：使用 请求头 façade 来区分版本，同时保留统一的入口路径，便于中间件统一鉴权、限流等横向治理。
2.3 基于媒体类型的版本化实现
通过内容协商（content negotiation）来实现版本控制，把版本信息放在 Accept 头中的媒体类型中，例如 application/vnd.example.v1+json。
这种方式把版本信息从 URL/头部中分离出来，契约性更强，客户端需要在请求头中指定合适的媒体类型。它在微服务网格中尤其有用，但对客户端的实现要求较高。
// 基于媒体类型的版本化实现
@RestController
@RequestMapping("/api")
public class PetControllerMedia {@GetMapping(value = "/pets", produces = "application/vnd.example.v1+json")public List<Pet> getPetsV1() {// 版本 1 的实现}@GetMapping(value = "/pets", produces = "application/vnd.example.v2+json")public List<Pet> getPetsV2() {// 版本 2 的实现}
}
注意事项：客户端需要正确设置 Accept 头并解析返回的版本信息；服务器端要配置正确的序列化策略以匹配不同版本的契约。
3. API版本控制实战落地
3.1 路由设计与治理
实际落地中，路由设计 应与后端服务分层解耦，避免在控制器中混杂过多版本逻辑。通过建立版本路由表与 路由门控，可以在不修改业务代码的情况下实现版本切换。与此同时，自动化文档生成（如 Swagger/OpenAPI）需要支持版本维度，以便前端快速查阅。
在 SpringBoot 中，可以结合 OpenAPI 规范与自定义注解来标注版本信息，从而在文档里直观呈现版本演进路径。
3.2 兼容性与客户端沟通
实现 API 版本控制的核心目标是保持向后兼容，为此需要明确的 弃用策略、以及对客户端的明确迁移路径。通过在文档和变更日志中标注 弃用日期、迁移指南，可以降低对接成本并减少上线风险。
对外发布新版本时，建议提供一个 并行运行的过渡期，允许客户端同时调用老版本与新版本，从而实现渐进式切换。
3.3 自动化测试与回归
为确保版本控制策略的稳定性，需要覆盖不同版本的回归测试。集成测试可以验证版本间契约的一致性，端到端测试则应覆盖通过各版本的业务路径。持续集成过程中，应该对 v1、v2 版本分别触发测试用例，确保变更不会破坏现有接口。
可以在测试用例中使用模拟客户端，验证不同版本契约的行为是否符合预期，并将测试结果对外展示以提升透明度。
# CI 流水线片段（示意）
stages:- testtest_v1:script:- mvn -Dtest=PetControllerV1Test testtest_v2:script:- mvn -Dtest=PetControllerV2Test test
