1. 为什么需要统一路由前缀在SpringBoot项目中随着业务模块不断增加Controller数量会快速膨胀。想象一下电商系统里同时存在用户模块、商品模块、订单模块的接口如果所有接口都直接暴露在根路径下不仅难以管理还容易产生路径冲突。我去年接手过一个老项目就因为路径命名不规范导致/user/info接口同时被用户基础信息和用户权限两个模块使用引发了一系列线上问题。统一路由前缀能带来三个核心价值模块化隔离比如所有用户相关接口用/api/user开头商品相关用/api/product开头版本控制通过/v1/api和/v2/api区分不同版本的接口权限过滤网关层可以通过前缀批量配置鉴权规则比如/admin开头的接口需要管理员权限2. 全局配置方案最粗暴的解决方案2.1 基础配置在application.yml中添加server: servlet: context-path: /api这样所有接口都会自动带上/api前缀比如原来的/user/login会变成/api/user/login。2.2 实战踩坑记录我在微服务项目中实际使用时发现几个关键问题静态资源也被加前缀导致前端访问/static/js/main.js需要改成/api/static/js/main.jsSwagger文档路径错乱需要额外配置springfox.documentation.swagger.use-model-v3false健康检查失效/actuator/health变成/api/actuator/health需要调整监控系统配置2.3 适用场景建议老项目迁移时保持URL兼容性需要为整个应用包括静态资源添加统一前缀简单的前后端分离项目3. 自定义注解方案优雅的模块化控制3.1 完整实现步骤创建自定义注解Target(ElementType.TYPE) Retention(RetentionPolicy.RUNTIME) Documented RestController public interface AdminApi { AliasFor(annotation RequestMapping.class) String value() default ; }配置路径匹配规则Configuration public class WebConfig implements WebMvcConfigurer { Override public void configurePathMatch(PathMatchConfigurer configurer) { configurer.addPathPrefix(/admin, c - c.isAnnotationPresent(AdminApi.class)); } }在Controller上使用AdminApi public class UserController { GetMapping(/users) public ListUser list() { //... } }3.2 实际项目中的增强技巧我通常会结合Spring Security做权限控制configurer.addPathPrefix(/admin, c - c.isAnnotationPresent(AdminApi.class) || c.isAnnotationPresent(RequiresAdmin.class));3.3 方案优势分析精准控制只对特定Controller生效可组合使用可以和类级别的RequestMapping叠加语义明确注解本身就能表达业务含义4. 包路径映射方案约定优于配置4.1 新版SpringBoot实现方案public class PackagePrefixHandlerMapping extends RequestMappingHandlerMapping { Value(${api.prefix-package}) private String prefixPackage; Override protected RequestMappingInfo getMappingForMethod(Method method, Class? handlerType) { RequestMappingInfo info super.getMappingForMethod(method, handlerType); if (info ! null) { String packageName handlerType.getPackageName(); if (packageName.startsWith(prefixPackage)) { String prefix packageName.substring(prefixPackage.length()) .replace(., /); return RequestMappingInfo .paths(prefix) .build() .combine(info); } } return info; } }4.2 目录结构示例com.example.demo └── controller ├── v1 │ └── UserController.java # 路径自动带/v1 └── v2 └── UserController.java # 路径自动带/v24.3 特别注意事项包名规范避免使用特殊字符如中划线性能影响每个请求都会执行包名解析IDE支持部分IDE可能无法正确识别自动生成的路由5. 类注解组合方案灵活度最高的选择5.1 继承式配置RestController RequestMapping(/api/v1) public abstract class BaseV1Controller {} Controller public class UserController extends BaseV1Controller { GetMapping(/users) // 实际路径为/api/v1/users }5.2 组合式配置Target(ElementType.TYPE) Retention(RetentionPolicy.RUNTIME) Documented RequestMapping(/api/v2) RestController public interface V2Api {} V2Api public class ProductController { GetMapping(/products) // 实际路径为/api/v2/products }5.3 方案对比特性继承方案组合方案多路径支持❌✅类多重继承❌✅注解可读性一般优秀6. 技术选型决策指南根据三年微服务架构经验我总结出以下决策矩阵考虑维度项目规模Controller数量版本迭代需求团队协作模式历史包袱情况推荐方案小型项目全局配置最简单中型项目自定义注解平衡灵活度大型项目包路径映射类注解组合最佳扩展性遗留系统改造全局配置自定义注解组合最近在金融项目中我们采用包路径映射方案实现了多版本API并行运行关键配置如下api: prefix-package: com.company.project.controller version-mapping: v1: 2023-01-01 v2: 2023-06-01