Spring Framework 7声明式 API 版本别再只靠手写 /v1Boot 4 / Framework 7 用 ApiVersionConfigurer mapping version 属性统一解析与匹配替代散落的路径前缀。一、痛点版本散落在路径里弃用与匹配全靠约定对外 REST 一多版本最常见的做法是控制器上再叠一层/v1、/v2。短期能跑长期会出现三类摩擦解析不统一有人用路径有人用 Header有人用Accept参数过滤器与网关各写一套匹配规则靠人脑基线版本「1.2 及以上走新实现」只能手写if容易和文档对不上弃用信号缺失Deprecation / Sunset 头要自己拼客户端很难按 RFC 做平滑迁移。更麻烦的是「同一资源、多种兼容面」老客户端仍打无版本 URL新客户端要带版本灰度客户端要试基线版本。全靠字符串前缀的话控制器类数量和路径常量会跟着版本数线性膨胀。Code Review 时也很难一眼看出「请求 1.3 究竟落到哪个方法」。Spring Framework7.0配合 Spring Boot4在 MVC 配置里补上了声明式 API 版本用ApiVersionConfigurer决定「版本从哪来」用RequestMapping/GetMapping的version属性决定「落到哪个处理器」。下面按官方 Web MVC 文档和ApiVersionConfigurerJavadoc 来讲只谈四件事服务端启用、映射语义、弃用头、客户端单独配置。先说清边界不假设 Boot 3.x 已有这套 mapping 版本属性也不去发明未核实的spring.mvc.api-version.*开关名启用方式以 Java 配置为准。二、启用WebMvcConfigurer ApiVersionConfigurer启用入口是WebMvcConfigurer.configureApiVersioning。至少挂一个解析器后框架才会建立ApiVersionStrategy并参与请求映射Configurationpublic class WebConfiguration implements WebMvcConfigurer {Override public void configureApiVersioning(ApiVersionConfigurer configurer) { configurer.useRequestHeader(API-Version) .setDefaultVersion(1.0) .addSupportedVersions(1.0, 1.1, 1.2); }}内置解析方式可组合也可用自定义ApiVersionResolver方式配置方法典型场景Request HeaderuseRequestHeader(API-Version)对内服务、网关转发URL 保持稳定Query ParamuseQueryParam(version)调试或兼容旧网关Path SegmentusePathSegment(index)对外公开 API路径里要有 URI 变量如/{version}Media Type 参数useMediaTypeParameter(mediaType, param)内容协商风格路径段解析要注意索引/{version}/...用0/api/{version}/...用1。官方还提醒若版本总在路径最前可配合 Path Matching 的公共前缀配置避免每个控制器重复声明。usePathSegment还有一个带Predicate的重载usePathSegment(int, Predicate)可对「这条路径是否带版本」做更细判断。补充几个配置旋钮以 Javadoc 为准setDefaultVersion请求未带版本时赋默认值设置默认后「版本是否必填」会自动变为可不带setVersionRequired强制请求必须带版本时缺省会走MissingApiVersionException400addSupportedVersions/detectSupportedVersions默认会从映射上的 version 自动探测支持列表若只想认显式列表把探测关掉再addSupportedVersionssetDeprecationHandler挂ApiVersionDeprecationHandler标准实现可发 Deprecation / Sunset / Link对应 RFC 9745 / RFC 8594setVersionParser默认语义版本解析SemanticApiVersionParser特殊编号体系可换自定义解析器。不支持的版本会触发InvalidApiVersionException最终400。这比「默默落到错误实现」更安全客户端能立刻发现版本协商失败不会带着半对半错的响应继续往下走。三、映射固定版本、基线版本、空版本优先级启用后在映射上写versionRestControllerRequestMapping(“/account/{id}”)public class AccountController {private final AccountService accounts; public AccountController(AccountService accounts) { this.accounts accounts; } GetMapping public Account getAny() { return accounts.legacy(); } GetMapping(version 1.1) public Account getV11() { return accounts.v11(); } GetMapping(version 1.2) public Account getFrom12() { return accounts.from12(); } GetMapping(version 1.5) public Account getV15() { return accounts.v15(); }}语义官方 Request Mapping「API Version」一节固定1.2只匹配该版本基线1.2匹配该版本及更高的已支持版本空版本匹配任意版本但优先级最低用来兜底「版本化之前的老客户端」。多个方法都「够得着」请求版本时选最高且最接近请求版本的那一个。文档用请求1.3举例空版本方法能匹配但会被1.2盖过固定1.5更高却匹配不上于是最终落到1.2。反过来请求1.5时固定1.5胜出。请求1.6时空版本方法和1.2都能匹配但会被更高的固定1.5盖过而1.5只接受严格相等于是没有方法可选结果是NotAcceptableApiVersionException400。另外请求版本既不在映射里、也没配置为支持版本时会直接被判为无效版本InvalidApiVersionException同样 400。所以写映射时务必对照支持列表把「请求版本 × 方法」推演一遍别只看「有没有一个能模糊对上」。实践建议老接口先留空版本方法保证未升级客户端仍可调用破坏性变更用固定版本避免被基线误伤演进式兼容用基线x.y减少「每个小版本复制一个方法」关键里程碑版本例如首次对外的1.0若暂时还没写在任何 mapping 上记得addSupportedVersions补进支持列表。四、决策何时仍写 /v1何时上声明式 version主建议很简单新项目优先内置 version 属性 统一 Resolver别把/v1当唯一手段。路径前缀并非禁止usePathSegment本身就是一等公民。差别在于「版本」写在映射条件里不再散落在每个RequestMapping的字符串常量里。手写前缀适合这类存量对外文档已经把/v1写进永久契约短期改不了 URL。可一旦还要 Header、弃用头、基线匹配继续只靠前缀会把复杂度推回过滤器层。怎么选解析位置HeaderURL 稳定、适合 BFF / 内网客户端与网关约定API-Version即可Path对外文档友好、可缓存、浏览器地址栏可见记得路径段索引与 URI 变量Query / MediaType兼容层或内容协商存量系统。同一应用也可以组合解析器但要约定优先级与「谁说了算」避免网关改了 Header、客户端又改了 Query两侧各执一词。更稳的做法对内统一 Header对外若必须可见再开 Path并在网关层做一次归一别让每个微服务自己猜。客户端要单独配。服务端 MVC 的configureApiVersioning不会自动套到RestClient/WebClient。官方 REST Clients 文档示例RestClient client RestClient.builder().baseUrl(“https://api.example.com”).defaultVersion(“1.2”).apiVersionInserter(ApiVersionInserter.fromHeader(“API-Version”).build()).build();单次请求还可再覆写版本。评审时把「服务端解析」与「客户端插入」拆成两项打勾一边开了版本另一边忘了ApiVersionInserter联调时最容易出现「服务端老报缺版本 / 不支持版本客户端坚持自己没传错」的拉锯。五、迁移节奏存量 /v1 怎么收若线上已经有一大片/api/v1/...不必第一天就删路径。更稳的节奏是双轨一期保留旧路径控制器同时启用configureApiVersioning新接口只在映射上写version对外文档开始宣传 Header或 Path Segment约定网关归一在边缘把旧/v1改写成统一的版本信号例如补API-Version: 1.0让下游只认一种解析方式避免微服务各自兼容弃用公告对旧固定版本挂上标准弃用头给出 Sunset 时间窗口监控仍打旧版本的流量占比再拆前缀待流量降下去再删除仅用于版本区分的路径段把「版本」彻底交还给映射条件。这样迁业务方法可以逐步合并到「基线版本 少量固定版本」模型不必再维持「每个大版本一个 Controller 包」。评审时把「解析方式」「支持列表」「弃用头」「客户端 Inserter」四项写成同一检查表比只改 URL 更不容易漏。跨团队协作时再补一条约定版本号表示「契约世代」不跟着发版号走。内部每周发版不必涨 API 版本只有响应字段语义、错误码或鉴权方式出现不兼容时才升。声明式版本把「升不升」变成显式的映射决策不用再悄悄新开一个/v3文件夹。六、落地清单与常见坑上线或把存量 API 迁到声明式版本时按下面勾一遍版本基线确认运行在 Framework 7 / Boot 4不要把这里的 API 回写到 Boot 3.x 教程里。先 Resolver 再映射没配置configureApiVersioning就写version1.0映射条件不会按预期生效。支持列表改映射后看一眼自动探测结果关键版本若未出现在任何 mapping 上用addSupportedVersions补上。默认版本与必填对外严格契约可要求必带版本对内渐进迁移可设setDefaultVersion(1.0)但要在文档写清默认语义。弃用路径下线前挂标准弃用处理器让客户端先收到 RFC 级信号别突然给 400。客户端对称RestClient / WebClient Builder 显式apiVersionInserter别指望「服务端开了版本客户端自动带上」。容器边界Boot 4 已移除 Undertow 支持部署与压测按官方仍支持的容器选型勿把旧 Undertow 调优笔记直接搬过来。测试矩阵至少覆盖「无版本 / 默认版本 / 固定命中 / 基线命中 / 不支持版本 400 / 弃用头是否出现」六类用例比只测快乐路径更有用。收个尾版本属于映射条件别让它沦为路径字符串的副作用。用ApiVersionConfigurer统一解析用version/version表达兼容面用标准弃用头管理生命周期手写/v1只留在确实需要「永久可见路径」的窄场景。