API 版本控制到底是“多此一举”，还是你未来凌晨三点的救命稻草？

🏆本文收录于《滚雪球学SpringBoot 3》:https://blog.csdn.net/weixin_43970743/category_12795608.html，专门攻坚指数提升，本年度国内最系统+最专业+最详细（永久更新）。
  
本专栏致力打造最硬核 SpringBoot3 从零基础到进阶系列学习内容，🚀均为全网独家首发，打造精品专栏，专栏持续更新中…欢迎大家订阅持续学习。 如果想快速定位学习，可以看这篇【SpringBoot3教程导航帖】https://blog.csdn.net/weixin_43970743/article/details/151115907，你想学习的都被收集在内，快速投入学习！！两不误。
  
若还想学习更多，可直接前往《滚雪球学SpringBoot(全版本合集)》:https://blog.csdn.net/weixin_43970743/category_11599389.html，涵盖SpringBoot所有版本教学文章。

演示环境说明：

• 开发工具：IDEA 2021.3
• JDK版本： JDK 17（推荐使用 JDK 17 或更高版本，因为 Spring Boot 3.x 系列要求 Java 17，Spring Boot 3.5.4 基于 Spring Framework 6.x 和 Jakarta EE 9，它们都要求至少 JDK 17。）
• Spring Boot版本：3.5.4（于25年7月24日发布）
• Maven版本：3.8.2 （或更高）
• Gradle：（如果使用 Gradle 构建工具的话）：推荐使用 Gradle 7.5 或更高版本，确保与 JDK 17 兼容。
• 操作系统：Windows 11

前言

我跟你讲，API 版本控制这事儿最魔幻的地方在于：项目刚起步时，大家都觉得“先别整版本，太重了”；等上线半年后，改一个字段就像在拆炸弹——你手在抖，老板在催，客户端在骂🙂。

所以这篇我就按你给的大纲，把三种主流策略掰开揉碎讲：URI 版本、Header 版本、Media Type（内容协商）版本，再落到 Spring Boot 3 / Spring Framework 6 的“优雅多版本共存”实现上（不是那种 if-else 堆成千层饼的写法）。

0）先把“版本控制”的边界说清楚（不然后面容易吵起来）

API 版本控制的核心目标不是“显得专业”，而是两件事：

1. 在不破坏旧客户端的前提下演进契约（字段、结构、语义、行为）。
2. 让服务端可以同时服务多个契约（至少在迁移窗口期）。

Spring MVC 的请求映射本质上就是一套“匹配条件”系统：路径、HTTP 方法、参数、Header、媒体类型（consumes/produces）都能参与匹配。官方文档明确说了 @RequestMapping 可以按 URL、method、params、headers、media types 来匹配请求。

1）URI 版本控制：/v1/users（简单粗暴，但真的好用）

1.1 优点（它为什么这么流行？）

• 可见性强：URL 一眼就能看出版本，排查问题时非常“人类友好”。
• 缓存/CDN 友好：版本在路径里，天然形成不同资源键，缓存策略好设计。
• 文档与网关配置直观：API 网关路由、监控分组、日志过滤都很好写。

1.2 缺点（它哪里让人别扭？）

• 从 REST 纯粹主义角度不优雅：URL 应该标识资源，而不是资源的“版本”。（但工程里……说实话，很多时候我宁愿“好维护”😅）
• 容易膨胀：当 v1、v2、v3 都在线，你的路径空间会越来越“热闹”。

1.3 Spring Boot 3 实现（推荐的“干净”写法）

写法 A：用不同 Controller 分包/分组（最清爽，适合中大型团队）

// package com.myapp.api.v1;

@RestController
@RequestMapping("/v1/users")
class UserControllerV1 {

  @GetMapping
  public List<String> list() {
    return List.of("Alice(v1)", "Bob(v1)");
  }
}

// package com.myapp.api.v2;

@RestController
@RequestMapping("/v2/users")
class UserControllerV2 {

  @GetMapping
  public List<String> list() {
    return List.of("Alice(v2)", "Bob(v2)", "Carol(v2)");
  }
}

写法 B：类级别版本前缀 + 方法级别资源路径（适合接口多但结构一致）

@RestController
@RequestMapping("/v1")
class V1UsersController {
  @GetMapping("/users")
  public List<String> users() { return List.of("v1"); }
}

小吐槽：URI 版本的缺点常被夸大。真实生产里，它的“稳定、可读、好排查”经常能救命。

2）Request Header 版本控制：X-API-VERSION: 2（更“干净”，也更容易踩坑）

Header 版本控制的思路是：路径不变，请求通过某个 Header 表达“我要哪个契约”。

2.1 优点

• URL 更像资源：/users 永远是 users，只是表现形式由 header 决定。
• 可渐进发布：同一个路径可按客户端能力/灰度策略选择版本。

2.2 缺点（重点来了）

• 可发现性差：排查时你只看 URL 看不出来版本，得翻请求头或日志。
• 缓存复杂：缓存键需要把 Header 纳入 vary（比如 Vary: X-API-VERSION），否则容易串数据。内容协商/缓存相关机制在 HTTP 语义与内容协商规范里有说明（Accept 等协商机制是标准的一部分）。
• 客户端工具/浏览器直测不舒服：你得手动加 Header，不然永远打到默认版本。

2.3 Spring Boot 3 两种落地方式

方式 A：用 @RequestMapping(headers=...) 直接让 Spring 做“映射级别分流”

Spring 官方明确 @RequestMapping 支持按 headers 参与匹配。

@RestController
@RequestMapping("/users")
class UsersHeaderVersionController {

  @GetMapping(headers = "X-API-VERSION=1")
  public List<String> v1() {
    return List.of("users v1");
  }

  @GetMapping(headers = "X-API-VERSION=2")
  public List<String> v2() {
    return List.of("users v2", "new field...");
  }
}

这个写法的优点是：干净、声明式、没有 if-else。
缺点是：版本多了以后，一个 Controller 里方法会变多（但比起 if-else 地狱，好太多了）。

方式 B：用拦截器统一校验/默认版本（注意：拦截器别拿来做路由选择）

Spring 的拦截器机制适合做 校验、记录、注入上下文，官方文档也提醒：拦截器并不适合作为安全层，而且它更适合在请求处理链中“增强”，而不是替代更早的过滤器链/安全机制。

你可以这样做：

• 拦截器读取 X-API-VERSION
• 做合法性校验/默认值
• 放到 request attribute 里，给后续业务逻辑使用（例如日志、埋点、返回头）

@Component
class ApiVersionInterceptor implements HandlerInterceptor {

  @Override
  public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String v = request.getHeader("X-API-VERSION");
    if (v == null || v.isBlank()) v = "1"; // 默认版本
    if (!v.equals("1") && !v.equals("2")) {
      response.setStatus(400);
      return false;
    }
    request.setAttribute("apiVersion", v);
    return true;
  }
}

@Configuration
class WebConfig implements WebMvcConfigurer {

  private final ApiVersionInterceptor interceptor;

  WebConfig(ApiVersionInterceptor interceptor) { this.interceptor = interceptor; }

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(interceptor).addPathPatterns("/users/**");
  }
}

关键提醒：拦截器执行时，Controller 映射通常已经选定了。所以“用拦截器决定走 v1 还是 v2 Controller”这条路，很多时候走着走着就撞墙（你会开始怀疑人生🙂）。拦截器更适合做：校验、默认版本、统计、响应头补充。

3）Media Type 版本控制：Content Negotiation（高级、优雅、也最容易让团队吵翻天）

这一派的核心是：版本是表现层的一部分，通过 Accept（或 Content-Type）协商——这属于 HTTP 内容协商机制的典型用途。

常见两种写法：

3.1 Vendor Media Type：application/vnd.myapp.user-v1+json

例子（客户端）：

Accept: application/vnd.myapp.user-v1+json

服务端（Spring MVC）可以通过 produces 精确匹配媒体类型。Spring 官方文档中 @RequestMapping 支持用媒体类型作为映射条件。

@RestController
@RequestMapping("/users")
class UsersMediaTypeController {

  @GetMapping(produces = "application/vnd.myapp.user-v1+json")
  public Map<String, Object> v1() {
    return Map.of("version", "v1", "data", List.of("Alice"));
  }

  @GetMapping(produces = "application/vnd.myapp.user-v2+json")
  public Map<String, Object> v2() {
    return Map.of("version", "v2", "data", List.of("Alice"), "extra", "new-field");
  }
}

优点：URL 干净，版本完全在“表示层”里；对 REST/HTTP 理论派更友好。
缺点：客户端需要更懂 HTTP；测试与排查成本更高；缓存也需要正确处理 Vary: Accept。

3.2 Media Type Parameter：application/json;v=2（更像“谈判”，也更折腾）

客户端：

Accept: application/json;v=2

服务端：仍然可以通过 produces 做匹配（注意写法要跟 Spring 的解析一致，团队要统一规范）。

@GetMapping(produces = "application/json;v=1")
public Map<String, Object> v1() { ... }

@GetMapping(produces = "application/json;v=2")
public Map<String, Object> v2() { ... }

如果你想更系统地控制“如何解析媒体类型”，Spring MVC 提供了内容协商配置点：默认只检查 Accept，也可以配置其他策略（参数、扩展名等）。

4）Spring Boot 3：多版本共存的“优雅姿势”到底是什么？

我给你三种从“简单到强”的落地方案，你按团队规模和复杂度选，不用硬上最高级（真没必要把自己整成 API 版本控制学术委员会成员😂）。

4.1 方案一：路径版本（最省心）

• v1、v2 分包 + 分 Controller
• 网关/文档/监控都容易
• 迁移窗口期管理最简单

适合：公共 API、开放平台、客户端类型很多的系统

4.2 方案二：Header/MediaType 版本 + @RequestMapping 条件匹配（声明式分流）

• 使用 headers = "X-API-VERSION=2" 或 produces=...
• 同一 URL 下按条件分流
• 不需要写自定义框架代码

适合：内部 API、BFF、客户端可控（比如你们自己的 App/Web）

4.3 方案三（进阶但很“正统”）：自定义 @ApiVersion + RequestCondition + RequestMappingHandlerMapping

Spring 官方文档明确给了扩展点：

你可以继承 RequestMappingHandlerMapping 并重写 getCustomMethodCondition，返回自定义 RequestCondition 来参与请求匹配。

这就意味着：你可以做一个像“框架能力”一样的版本系统，而不是散落在一堆 headers/produces 字符串里。

Step 1：定义注解

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
  int value();
}

Step 2：实现 RequestCondition（用 Header 举例）

public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {

  private final int version;

  public ApiVersionCondition(int version) {
    this.version = version;
  }

  @Override
  public ApiVersionCondition combine(ApiVersionCondition other) {
    // 方法级别优先于类级别
    return new ApiVersionCondition(other.version);
  }

  @Override
  public ApiVersionCondition getMatchingCondition(HttpServletRequest request) {
    String v = request.getHeader("X-API-VERSION");
    int reqVersion = (v == null || v.isBlank()) ? 1 : Integer.parseInt(v);
    return (reqVersion == this.version) ? this : null;
  }

  @Override
  public int compareTo(ApiVersionCondition other, HttpServletRequest request) {
    // 匹配时选更“具体/更高优先级”的。这里简单按 version 大小比较
    return Integer.compare(other.version, this.version);
  }
}

Step 3：自定义 HandlerMapping，把注解翻译成 Condition

public class VersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {

  @Override
  protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
    ApiVersion v = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
    return createCondition(v);
  }

  @Override
  protected RequestCondition<?> getCustomMethodCondition(Method method) {
    ApiVersion v = AnnotationUtils.findAnnotation(method, ApiVersion.class);
    return createCondition(v);
  }

  private RequestCondition<ApiVersionCondition> createCondition(ApiVersion v) {
    return v == null ? null : new ApiVersionCondition(v.value());
  }
}

Step 4：在 Spring Boot 3 注册这个 Mapping（替换默认的）

@Configuration
public class WebMvcVersioningConfig implements WebMvcRegistrations {

  @Override
  public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
    return new VersionRequestMappingHandlerMapping();
  }
}

Step 5：Controller 像写“普通业务”一样写版本

@RestController
@RequestMapping("/users")
class UsersController {

  @ApiVersion(1)
  @GetMapping
  public List<String> v1() { return List.of("v1"); }

  @ApiVersion(2)
  @GetMapping
  public List<String> v2() { return List.of("v2", "new"); }
}

这套方案的气质就是：
“版本控制从此不再是散装逻辑，而是系统级能力。”
缺点也很现实：你要维护这套扩展，团队得有共识（不然有人偷偷写 headers=...，你就开始血压升高😤）。

5）怎么选？给你一份“不装”的决策表（按真实工程来）

• 外部公开 API / 多语言客户端 / SDK 分发：优先 URI 版本（清晰、可见、好沟通）。
• 内部 API / 客户端可控 / 强调 URL 资源纯粹：Header 或 Media Type 都行。
• 版本规则复杂（灰度、默认版本、兼容窗口、废弃策略要统一）：上自定义 RequestCondition，把版本做成框架能力。
• 别用拦截器硬做路由选择：拦截器很适合校验/注入上下文，但不是最理想的“映射决策层”。

6）最后补一刀：版本共存不止是“路由”，还有“退场机制”

你只做“怎么接入 v2”，却不做“怎么让 v1 退场”，那版本会像杂物间一样越堆越满（而且每次排障都要翻箱倒柜🙃）。

建议至少做到：

• 返回响应头提示废弃（例如 Deprecation、Sunset 这类策略，或你们自定义 Header）
• 监控每个版本的调用量（调用量归零才敢下线）
• 文档明确迁移指南（字段差异、行为差异、兼容窗口）

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G PDF编程电子书、简历模板、技术文章Markdown文档等海量资料。

ps：本文涉及所有源代码，均已上传至Gitee：https://gitee.com/bugjun01/SpringBoot-demo 开源，供同学们一对一参考 Gitee传送门https://gitee.com/bugjun01/SpringBoot-demo，同时，原创开源不易，欢迎给个star🌟，想体验下被🌟的感jio，非常感谢❗

🫵 Who am I?

我是 bug菌：

• 热活跃于 CSDN:https://blog.csdn.net/weixin_43970743 | 掘金:https://juejin.cn/user/695333581765240 | InfoQ:https://www.infoq.cn/profile/4F581734D60B28/publish | 51CTO:https://blog.51cto.com/u_15700751 | 华为云:https://bbs.huaweicloud.com/community/usersnew/id_1582617489455371 | 阿里云:https://developer.aliyun.com/profile/uolxikq5k3gke | 腾讯云:https://cloud.tencent.com/developer/user/10216480/articles 等技术社区；
• CSDN 博客之星 Top30、华为云多年度十佳博主&卓越贡献奖、掘金多年度人气作者 Top40；
• 掘金、InfoQ、51CTO 等平台签约及优质作者；
• 全网粉丝累计 30w+。

更多高质量技术内容及成长资料，可查看这个合集入口 👉 点击查看:https://bbs.csdn.net/topics/612438251 👈️
硬核技术公众号 「猿圈奇妙屋」https://bbs.csdn.net/topics/612438251 期待你的加入，一起进阶、一起打怪升级。

- End -