本文介绍如何在 Spring Boot 2（Java 11）中通过自定义 @APIv1 等注解，结合 WebMvcConfigurer 动态注入路径前缀（如 /api/v1），使控制器类自动继承版本化基础路径，避免在每个 @GetMapping 中重复书写前缀。
本文介绍如何在 spring boot 2（java 11）中通过自定义 `@apiv1` 等注解，结合 `webmvcconfigurer` 动态注入路径前缀（如 `/api/v1`），使控制器类自动继承版本化基础路径，避免在每个 `@getmapping` 中重复书写前缀。
在构建多版本 RESTful API 时，为不同版本（如 /api/v1/, /api/v2/）统一管理路径前缀是常见需求。理想情况下，我们希望用一个简洁的注解（如 @APIv1("/users")）声明控制器的业务路径片段，并由框架自动将其与版本前缀拼接为完整路径（如 /api/v1/users/info）。Spring 原生 @RequestMapping 不支持动态组合式前缀注入，但可通过 自定义注解 + WebMvcConfigurer#configurePathMatch 实现优雅解耦。
✅ 核心设计思路
- 定义轻量级元注解 @PrefixMapping，仅用于标记「路径前缀」；
- 创建语义化注解（如 @APIv1），本身不直接处理路径，而是：
- 继承 @RestController 和 @RequestMapping（保留 Spring MVC 行为）；
- 通过 @PrefixMapping 声明其专属版本前缀（如 /api/v1）；
- 在 WebMvcConfigurer 中扫描所有带 @PrefixMapping 的注解类，利用 addPathPrefix() 将前缀绑定到使用该注解的控制器类上。
? 步骤详解
1. 定义通用前缀标记注解（@PrefixMapping）
// com.example.myannotations.PrefixMapping.java
package com.example.myannotations;
import java.lang.annotation.*;
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PrefixMapping {
/**
* 要前置拼接到所有映射路径的公共前缀（如 "/api/v1"）
*/
String value() default "";
}✅ 该注解仅作元数据标记，不参与运行时逻辑，因此无需 @Retention(RUNTIME) 以外的元注解。
2. 创建语义化版本注解（如 @APIv1）
// com.example.myannotations.APIv1.java
package com.example.myannotations;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.lang.annotation.*;
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RestController
@RequestMapping // 注意：此处不设默认值，交由 WebMvcConfigurer 注入
@PrefixMapping("/api/v1") // 指定此注解对应的全局前缀
public @interface APIv1 {
/**
* 别名映射至 {@link RequestMapping#value}，支持显式覆盖（如 @APIv1("/admin")）
*/
@AliasFor(annotation = RequestMapping.class, attribute = "value")
String value() default "";
}⚠️ 关键点：@RequestMapping 无默认值，确保其路径完全由后续 addPathPrefix 控制；@AliasFor 允许用户在使用 @APIv1("/admin") 时覆盖类级路径片段（如 /admin/users → /api/v1/admin/users）。
3. 实现 WebMvcConfigurer 动态注册路径前缀
// com.example.config.WebConfig.java
package com.example.config;
import com.example.myannotations.PrefixMapping;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.type.filter.AnnotationTypeFilter;
import org.springframework.util.ClassUtils;
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.handler.HandlerTypePredicate;
import java.util.Arrays;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
// 扫描自定义注解所在包（需替换为实际包名）
String basePackage = "com.example.myannotations";
var provider = new ClassPathScanningCandidateComponentProvider(false) {
@Override
protected boolean isCandidateComponent(AnnotatedBeanDefinition beanDefinition) {
return true; // 强制识别所有注解类
}
};
provider.addIncludeFilter(new AnnotationTypeFilter(PrefixMapping.class));
provider.findCandidateComponents(basePackage).forEach(bean -> {
try {
String className = bean.getBeanClassName();
Class<? extends Annotation> annClass = (Class<? extends Annotation>) Class.forName(className);
// 提取 @PrefixMapping 中定义的前缀
PrefixMapping prefixAnn = annClass.getDeclaredAnnotation(PrefixMapping.class);
if (prefixAnn != null) {
String prefix = prefixAnn.value();
// 将前缀绑定到所有使用该注解的 Controller 类
configurer.addPathPrefix(prefix, HandlerTypePredicate.forAnnotation(annClass));
}
} catch (ClassNotFoundException e) {
throw new RuntimeException("Failed to load custom annotation: " + bean.getBeanClassName(), e);
}
});
}
}✅ HandlerTypePredicate.forAnnotation(annClass) 是关键：它告诉 Spring —— 凡是被 @APIv1（或任意同类注解）标注的 Controller，其所有 @RequestMapping 子路径均应自动添加对应前缀。
4. 在 Controller 中使用
// com.example.controller.UserController.java
package com.example.controller;
import com.example.myannotations.APIv1;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@APIv1("/users") // → 实际生效路径前缀为 "/api/v1/users"
@RestController
public class UserController {
@GetMapping("/info")
public String info() {
return "This should be returned at /api/v1/users/info";
// ✅ 自动解析为 GET /api/v1/users/info
}
@GetMapping("/list")
public String list() {
return "GET /api/v1/users/list";
}
}? 注意事项与最佳实践
包扫描范围精准性：ClassPathScanningCandidateComponentProvider 的 basePackage 必须严格指向存放自定义注解的包（如 com.example.myannotations），不可过大（影响启动性能）或过小（导致漏扫）。
注解继承限制：Spring 不支持注解的「继承链式前缀叠加」（如 @APIv2 继承 @APIv1 并修改前缀），每个版本注解需独立定义并单独扫描。
方法级 @RequestMapping 优先级：若控制器类使用 @APIv1("/users")，而某方法写 @GetMapping("/api/v1/admin/info")，则绝对路径会绕过前缀机制——这是 Spring 设计使然，建议始终使用相对路径（如 /info）。
兼容性保障：该方案基于 Spring Framework 5.3+ 的 HandlerTypePredicate，完全兼容 Spring Boot 2.4+ 及 3.x（需调整 Jakarta EE 包名）。
-
扩展多版本支持：只需新增类似注解即可，例如：
@PrefixMapping("/api/v2") public @interface APIv2 { /* ... */ }无需修改 WebConfig —— 扫描逻辑自动适配。
✅ 总结
通过分离「前缀声明」（@PrefixMapping）与「语义注解」（@APIv1），再借助 WebMvcConfigurer#addPathPrefix 的类型级路径增强能力，我们实现了零侵入、高可维护的 API 版本路径管理。相比硬编码 @RequestMapping("/api/v1/users") 或重复书写 @GetMapping("/api/v1/users/info")，该方案显著提升代码复用性与可读性，且天然支持横向扩展（v2/v3…），是企业级 Spring Boot 项目推荐的标准化实践。
