api-versioning

API 版本控制（Boot 3 / Framework 6）

Boot 3 不提供 Boot 4 内置映射中的 version 属性。请选择一种明确的策略并保持一致：URL 路径段、请求标头或媒体类型参数。

优先采用清晰、可测试的契约

对于公共 API，/api/v1/orders 和 /api/v2/orders 通常是最清晰的选择。如果 URL 必须保持稳定，请在 Web 边界解析请求标头，并路由到对应版本的处理程序。不要在业务服务中隐藏版本选择逻辑，也不要在过滤器和控制器中重复实现。

@RestController
@RequestMapping("/api/v1/orders")
class OrderV1Controller {
    @GetMapping("/{id}")
    OrderV1 get(@PathVariable UUID id) { ... }
}

在 OpenAPI 中记录受支持的版本，定义移除策略，并对不受支持的版本返回一致的错误。弃用某个版本时，通过响应通知或过滤器添加 Deprecation、Sunset 和 Link 标头。

迁移边界

保持特定版本的 DTO 和控制器精简。将两个版本都映射到相同的应用用例，不要在每个版本中复制领域逻辑。为每个受支持的版本添加契约测试；如果使用媒体类型，请验证内容协商。

常见问题

• Agent 在 Boot 3 中使用 Boot 4 的 version 属性——该属性不可用；请选择明确的路由策略。
• Agent 混用 URL、标头和媒体类型解析——请选择唯一的事实来源。
• Agent 在服务中处理版本分支——请在 Web 适配器边界处理兼容性。
• Agent 更改响应字段却不进行版本控制——请保留旧契约或发布新版本。
• Agent 在每个控制器中自行添加弃用标头——请通过通知或过滤器集中处理。
• Agent 只记录最新版本——请为每个受支持的版本维护 OpenAPI 文档和契约测试。