api-versioning

用途

该技能面向在 Spring Boot 3 / Spring Framework 6 中为 Spring MVC 或 WebFlux API 引入版本管理的场景。由于 Boot 3 不提供 Boot 4 的内置映射版本属性（mapping version attribute），技能的核心目标是帮助开发者选择一种明确、一致的版本策略，并在 Web 层边界完成版本解析与路由。

主要能力

• 覆盖三种显式版本策略：URL 路径段、请求头、媒体类型参数。
• 强调优先采用可见、可测试的契约，例如公开 API 使用 /api/v1/orders 与 /api/v2/orders。
• 若 URL 必须保持稳定，建议在 Web 边界解析请求头并路由到带版本的处理器。
• 要求在 OpenAPI 中记录受支持的版本，定义移除策略，并对不支持的版本返回一致的错误。
• 在退役某个版本时，通过响应通知（response advice）或过滤器集中添加 Deprecation、Sunset 和 Link 响应头。
• 迁移边界方面：保持各版本 DTO 与控制器精简，将两个版本映射到同一应用用例，不把领域逻辑复制到每个版本中。
• 为每个受支持的版本添加契约测试；若使用媒体类型，还需验证内容协商（content negotiation）。

使用方式

技能给出的示例采用 URL 路径段策略：

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

整体使用思路是：先选定一种版本来源（URL、请求头或媒体类型），保持单一事实来源；在 Web 适配器边界完成版本分支，而不是在业务服务中；为每个版本维护独立的 DTO 与控制器，但共享同一应用用例；集中管理弃用相关响应头；并为每个受支持版本维护 OpenAPI 文档与契约测试。

适用场景

• 需要为 Spring Boot 3 / Spring Framework 6 的 Spring MVC 或 WebFlux API 设计版本管理方案。
• 公开 API 需要清晰、可测试的版本契约。
• URL 需要保持稳定，希望通过请求头进行版本路由。
• 需要为 API 版本制定弃用与移除策略，并统一返回弃用相关响应头。
• 需要在多版本并存时避免领域逻辑重复、保持迁移边界清晰。

限制与注意事项

技能明确列出若干常见陷阱：

• 在 Boot 3 上使用 Boot 4 的版本属性——该属性不可用，必须选择显式的路由策略。
• 混用 URL、请求头和媒体类型解析——应只选一个事实来源。
• 把版本分支放进服务层——兼容性应保持在 Web 适配器边界。
• 未做版本管理就修改响应字段——应保留旧契约或发布新版本。
• 在每个控制器中各自发明弃用响应头——应集中到通知或过滤器中。
• 只记录最新版本——应为每个受支持版本维护 OpenAPI 与契约测试。

关于该技能的具体安装命令、支持的平台范围、收费方式或价格等信息，资料中暂未提供。