Java接口版本管理核心是新旧共存与平滑过渡，推荐URL路径嵌入整数版号（如/v1/users），辅以Header或Accept头方式；需配套独立文档、兼容策略及明确下线计划。
Java中级项目做接口版本管理，核心是让新旧版本共存、平滑过渡、不破坏已有调用方。不是靠改包名或删旧接口，而是通过清晰的路由控制、语义化标识和分层隔离来实现。
URL路径中嵌入版本号（最常用且直观）
在RESTful API设计中，把版本号放在请求路径最前端，比如 /v1/users、/v2/users。这种做法对客户端友好，便于Nginx或网关层做路由转发，也符合HTTP资源定位习惯。
- 版本号建议用 v1、v2 这种整数形式，避免使用时间戳或小数（如 v1.2），减少语义歧义
- Spring Boot 中可用 @RequestMapping("/v1/users") 或 @GetMapping("/v2/users") 直接区分
- 注意：/v1 和 /v2 应该是完全独立的 Controller 层，不要在同一个类里用 if-else 判断版本
请求头中传递版本信息（适合灰度或内部系统）
用 HTTP Header（如 X-API-Version: v2）标识版本，后端统一拦截解析，再路由到对应逻辑。这种方式对 URL 更干净，适合需要动态切换、A/B测试或兼容性要求极高的场景。
- 需自定义拦截器或过滤器（如 Spring 的 HandlerInterceptor 或 OncePerRequestFilter）提取并设置上下文版本
- 业务逻辑中可通过 ThreadLocal 或 RequestContextHolder 获取当前版本，决定走哪套 DTO、校验规则或服务分支
- 缺点是调试和文档不易呈现，需配合 OpenAPI 规范显式标注支持的版本头
参数或媒体类型（Accept Header）方式（较少推荐）
例如用 Accept: application/vnd.myapp.v2+json，或加 query 参数 ?version=v2。前者更符合 REST 原则，但客户端适配成本高；后者简单但不安全（参数易被缓存、日志泄露、网关忽略）。
立即学习“Java免费学习笔记（深入）”；
- Spring MVC 支持 produces = "application/vnd.myapp.v1+json" 来匹配 Accept 头，但需为每个版本单独配置 @ResponseBody 处理器
- Query 方式仅建议用于临时兼容或管理接口，不作为主版本策略
- 不推荐混合多种方式，会增加维护复杂度和理解门槛
配套机制不能少：文档、兼容性与下线策略
版本管理不只是技术路由，更是协作契约。没有配套，版本只会变成技术债温床。
- 每个版本必须有独立的 OpenAPI（Swagger）文档，标注废弃接口（@Deprecated + @ApiDeprecated）、变更说明和生命周期（如 “v1 已冻结，2025年Q2下线”）
- 新增字段默认兼容旧版（不强制校验、提供默认值），删除字段必须保留兼容层（DTO 转换、空值兜底）
- 下线前至少提前一个大版本通知，并提供迁移指南和自动化脚本（如旧版请求自动重写为新版）
不复杂但容易忽略的是：版本边界要划清——Controller 层分版本，Service 和 DAO 层尽量复用，靠参数或策略模式隔离差异。真正的版本升级，是能力演进，不是代码复制粘贴。
