SpringBoot自定义Spring MVC配置实战指南

1. SpringBoot中自定义Spring MVC配置的核心价值

在基于SpringBoot的Web应用开发中，Spring MVC作为核心模块承担着请求处理、视图解析等关键职责。默认情况下，SpringBoot通过自动配置为我们提供了合理的默认MVC配置，但实际业务中往往需要定制化调整。这正是WebMvcConfigurer接口大显身手的地方——它允许我们在保留自动配置优势的同时，精准覆盖特定配置项。

我经历过多个从单体到微服务的SpringBoot项目，发现90%的中大型项目都需要至少以下一种自定义配置：

• 添加拦截器实现鉴权/日志等横切关注点
• 格式化器处理特定类型的数据转换
• 跨域配置支持前后端分离架构
• 静态资源映射适配特殊部署环境
• 视图解析器定制多模板引擎混用

2. 自定义配置的三种实现方式

2.1 基础版：实现WebMvcConfigurer接口

这是最推荐的方式，不会破坏SpringBoot的自动配置：

java复制@Configuration
public class MyMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new AuthInterceptor())
               .addPathPatterns("/api/**")
               .excludePathPatterns("/api/public/**");
    }
    
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(0, new FastJsonHttpMessageConverter());
    }
}

关键经验：接口中的default方法让我们可以只覆盖需要定制的方法，其他配置仍保持自动配置的合理性

2.2 进阶版：@EnableWebMvc + 配置类

这种方式会完全接管MVC配置，慎用：

java复制@Configuration
@EnableWebMvc  // 禁用自动配置
public class FullMvcConfig implements WebMvcConfigurer {
    // 需要手动配置所有MVC组件
}

2.3 快捷版：配置属性文件

简单配置可通过application.yml实现：

yaml复制spring:
  mvc:
    static-path-pattern: /static/**
    format:
      date: yyyy-MM-dd

3. 高频自定义场景实战

3.1 拦截器深度配置

以API耗时监控拦截器为例：

java复制public class TimeCostInterceptor implements HandlerInterceptor {
    private static final ThreadLocal<Long> timeHolder = new ThreadLocal<>();

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        timeHolder.set(System.currentTimeMillis());
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        long cost = System.currentTimeMillis() - timeHolder.get();
        LogUtils.info("{} 耗时 {}ms", request.getRequestURI(), cost);
        timeHolder.remove();
    }
}

注册时注意顺序控制：

java复制@Override
public void addInterceptors(InterceptorRegistry registry) {
    // 先添加的先执行
    registry.addInterceptor(new AuthInterceptor()).order(1);
    registry.addInterceptor(new TimeCostInterceptor()).order(2);
}

3.2 跨域配置的三种姿势

方式1：全局配置类

java复制@Override
public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/api/**")
            .allowedOrigins("https://domain.com")
            .allowedMethods("GET", "POST")
            .maxAge(3600);
}

方式2：注解驱动

java复制@RestController
@RequestMapping("/api")
@CrossOrigin(origins = "https://domain.com", maxAge = 3600)
public class ApiController {
    // ...
}

方式3：Filter方案

java复制@Bean
public FilterRegistrationBean<CorsFilter> corsFilter() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration config = new CorsConfiguration();
    config.addAllowedOrigin("*");
    config.addAllowedHeader("*");
    source.registerCorsConfiguration("/**", config);
    return new FilterRegistrationBean<>(new CorsFilter(source));
}

3.3 静态资源映射黑科技

特殊场景下可能需要自定义资源映射：

java复制@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 映射本地文件系统
    registry.addResourceHandler("/files/**")
            .addResourceLocations("file:/opt/uploads/")
            .setCacheControl(CacheControl.maxAge(7, TimeUnit.DAYS));
    
    // 覆盖默认静态路径
    registry.addResourceHandler("/static/**")
            .addResourceLocations("classpath:/custom-static/");
}

4. 高阶配置技巧

4.1 格式化器与转换器

处理特殊类型转换：

java复制@Override
public void addFormatters(FormatterRegistry registry) {
    // 日期格式化
    registry.addFormatter(new DateFormatter("yyyy-MM-dd HH:mm"));
    
    // 自定义类型转换
    registry.addConverter(new StringToEnumConverter());
}

public class StringToEnumConverter implements Converter<String, StatusEnum> {
    @Override
    public StatusEnum convert(String source) {
        return StatusEnum.fromCode(source);
    }
}

4.2 异步请求配置

优化异步处理性能：

java复制@Override
public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
    configurer.setDefaultTimeout(30000)
             .setTaskExecutor(new ThreadPoolTaskExecutor());
}

4.3 视图控制器捷径

快速映射无需逻辑的路径：

java复制@Override
public void addViewControllers(ViewControllerRegistry registry) {
    registry.addViewController("/login").setViewName("login");
    registry.addRedirectViewController("/docs", "/swagger-ui.html");
}

5. 避坑指南

5.1 配置失效常见原因

1. 配置类未加载

   • 确保主启动类能扫描到配置类
   • 检查是否有@ComponentScan自定义扫描路径

2. 顺序问题

   • 使用@Order注解控制配置类加载顺序
   • 拦截器order()方法控制执行顺序

3. 冲突配置

   • 避免同时使用@EnableWebMvc和WebMvcConfigurer
   • 属性配置与Java配置不要重复

5.2 性能优化要点

1. 拦截器链不宜过长（建议≤5个）
2. 资源映射的缓存配置要合理
3. 消息转换器按使用频率排序
4. 异步超时时间根据业务设置

5.3 最佳实践

1. 生产环境推荐组合：

   java复制@Configuration
   @EnableWebMvc
   @ComponentScan
   public class MvcConfig implements WebMvcConfigurer, AsyncConfigurer {
       // 统一管理所有web相关配置
   }
   

2. 开发环境快速验证：

   properties复制# application-dev.properties
   spring.mvc.throw-exception-if-no-handler-found=true
   spring.resources.add-mappings=false
   

3. 配置分离技巧：

   java复制@Configuration
   public class MvcConfig {
       @Bean
       public WebMvcConfigurer corsConfigurer() {
           return new WebMvcConfigurer() {
               @Override
               public void addCorsMappings(CorsRegistry registry) {
                   registry.addMapping("/api/**");
               }
           };
       }
   }
   

在实际项目中，我习惯将MVC配置按功能拆分为多个内部类：

java复制@Configuration
public class WebConfig {
    
    @Configuration
    @Order(1)
    static class SecurityConfig implements WebMvcConfigurer {
        // 安全相关配置
    }
    
    @Configuration
    @Order(2)
    static class ResourceConfig implements WebMvcConfigurer {
        // 资源处理配置
    }
}

这种模块化配置方式既保持了灵活性，又避免了单个配置类过于臃肿的问题。特别是在微服务架构下，不同服务可以复用这些配置模块，大幅提升开发效率。