Spring MVC 完整配置指南：WebMvcConfigurer 实战全解析

目标：在不接管 @EnableWebMvc 的前提下，通过 WebMvcConfigurer 对 MVC 行为进行精细化定制，实现拦截器、跨域、视图映射、静态资源、消息转换、异步处理、国际化等常见与高级功能。

目录

1. 拦截器（Interceptors）
2. 跨域（CORS）
3. 视图控制器（ViewController）
4. 静态资源处理（ResourceHandlers）
5. 消息转换器（MessageConverters）
6. 参数解析器（ArgumentResolvers）
7. 返回值处理器（ReturnValueHandlers）
8. 路径匹配（PathMatch）
9. 数据格式化（Formatters）
10. 默认 Servlet 处理器（DefaultServletHandling）
11. 异步请求处理（AsyncSupport）
12. 异常处理增强（ExceptionResolvers）
13. 内容协商（ContentNegotiation）
14. 国际化（i18n）
15. 请求内容解码（HttpMessageConverter 扩展）
16. 自定义 PathPattern 配置
17. WebSocket 支持

1 拦截器（Interceptors）

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MyCustomInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/login", "/static/**");
    }
}

• 用途：统一日志记录、认证、权限检查、性能监控

2 跨域（CORS）

@Override
public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/api/**")
            .allowedOrigins("https://domain.com", "http://localhost:8080")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .allowCredentials(true)
            .maxAge(3600);
}

• 用途：解决前后端分离的跨域问题

3 视图控制器（ViewController）

@Override
public void addViewControllers(ViewControllerRegistry registry) {
    registry.addViewController("/home").setViewName("home");
    registry.addViewController("/").setViewName("index");
    registry.addViewController("/login").setViewName("login");
}

• 用途：快速路径到视图映射，无需空 Controller

4 静态资源处理（ResourceHandlers）

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/static/**")
            .addResourceLocations("classpath:/static/")
            .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS));

    registry.addResourceHandler("/uploads/**")
            .addResourceLocations("file:/opt/uploads/");
}

• 用途：映射静态资源路径，支持缓存优化

5 消息转换器（MessageConverters）

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    FastJsonHttpMessageConverter fastJsonConverter = new FastJsonHttpMessageConverter();
    FastJsonConfig config = new FastJsonConfig();
    config.setSerializerFeatures(SerializerFeature.PrettyFormat);
    fastJsonConverter.setFastJsonConfig(config);
    converters.add(0, fastJsonConverter);
}

• 用途：定制 JSON 序列化/反序列化，支持扩展到 XML、二进制等

6 参数解析器（ArgumentResolvers）

@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
    resolvers.add(new CurrentUserMethodArgumentResolver());
}

• 用途：自定义 Controller 方法参数，如自动注入当前用户

7 返回值处理器（ReturnValueHandlers）

@Override
public void addReturnValueHandlers(List<HandlerMethodReturnValueHandler> handlers) {
    handlers.add(new GlobalResponseWrapperHandler());
}

• 用途：统一包装返回结果格式
• 推荐使用 @ControllerAdvice + ResponseBodyAdvice 更简单

8 路径匹配（PathMatch）

@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
    configurer.setUseSuffixPatternMatch(false);
    configurer.setUseTrailingSlashMatch(true);
    configurer.addPathPrefix("/api", c -> c.isAnnotationPresent(RestController.class));
}

• 用途：自定义 URL 匹配规则、尾部斜杠、自动前缀

9 数据格式化（Formatters）

@Override
public void addFormatters(FormatterRegistry registry) {
    registry.addFormatter(new DateFormatter("yyyy-MM-dd"));
}

• 用途：字符串 → 对象类型转换，如日期、枚举

10 默认 Servlet 处理器（DefaultServletHandling）

@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
    configurer.enable();
}

• 用途：使用容器默认 Servlet 处理请求（如静态资源）

11 异步请求处理（AsyncSupport）

@Override
public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
    configurer.setDefaultTimeout(5000);
    configurer.setTaskExecutor(new ConcurrentTaskExecutor(Executors.newFixedThreadPool(10)));
}

• 用途：长耗时接口异步处理，线程池、超时控制

12 异常处理增强（ExceptionResolvers）

@Override
public void configureHandlerExceptionResolvers(List<HandlerExceptionResolver> resolvers) {
    resolvers.add(new MyCustomExceptionResolver());
}

• 用途：全局自定义异常返回格式、日志统一处理

13 内容协商（ContentNegotiation）

@Override
public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    configurer.favorPathExtension(true)
              .favorParameter(true)
              .parameterName("format")
              .defaultContentType(MediaType.APPLICATION_JSON)
              .mediaType("xml", MediaType.APPLICATION_XML)
              .mediaType("json", MediaType.APPLICATION_JSON);
}

• 用途：根据请求返回 JSON / XML / CSV 等不同格式

14 国际化（i18n）

@Bean
public LocaleResolver localeResolver() {
    SessionLocaleResolver slr = new SessionLocaleResolver();
    slr.setDefaultLocale(Locale.ENGLISH);
    return slr;
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
    lci.setParamName("lang");
    registry.addInterceptor(lci);
}

• 用途：根据请求参数或头动态切换语言

15 请求内容扩展（HttpMessageConverter 扩展）

converters.add(new MappingJackson2XmlHttpMessageConverter());
converters.add(new ByteArrayHttpMessageConverter());

• 用途：支持 XML、图片、文件、Protobuf 等多种请求/响应格式

16 自定义 PathPattern 配置

configurer.addPathPrefix("/api", c -> c.isAnnotationPresent(RestController.class));

• 用途：统一添加前缀、支持正则匹配

17 WebSocket 支持

@Override
public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
    registry.addHandler(myWebSocketHandler(), "/ws")
            .setAllowedOrigins("*");
}

• 用途：实时通讯、消息推送

总结表格

最佳实践

1. 模块化配置：按功能拆分多个 @Configuration 类，职责单一。
2. 扩展优先：尽量使用 extendMessageConverters，避免覆盖默认 Spring Boot 配置。
3. 谨慎使用 @EnableWebMvc：Spring Boot 默认自动配置已非常完善。
4. 跨域灵活配置：全局 CORS + Controller 级别注解结合使用。
5. 异步、异常、内容协商等高级场景：适用于复杂项目或微服务架构，增强可扩展性与统一性。