本文介绍如何在 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 项目推荐的标准化实践。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！