在 Spring Boot 项目里加拦截器，最容易卡住的地方通常不是代码怎么写，而是“为什么写了却不生效”或者“为什么一加配置就把默认 MVC 行为搞没了”。这篇文章按官方推荐方式，把拦截器定义、注册方法和日志验证过程串起来讲清楚，读完你可以判断自己该保留 Spring Boot 自动配置，还是需要进一步接管 Spring MVC。

为什么拦截器不能直接写进配置文件

拦截器和普通开关型配置不一样，它本质上是一个 Java 类，需要参与 Spring MVC 的处理链。因此在 Spring Boot 里，通常不是在 application.properties 中“声明一个拦截器”，而是通过 Java Config 的方式把它注册进 MVC 配置。

Spring Boot 官方文档对这件事说得很明确：

If you want to keep Spring Boot MVC features and you want to add additional MVC configuration (interceptors, formatters, view controllers, and other features), you can add your own @Configuration class of type WebMvcConfigurer but without @EnableWebMvc. If you wish to provide custom instances of RequestMappingHandlerMapping, RequestMappingHandlerAdapter, or ExceptionHandlerExceptionResolver, you can declare a WebMvcRegistrationsAdapter instance to provide such components.

If you want to take complete control of Spring MVC, you can add your own @Configuration annotated with @EnableWebMvc.

这段话可以归纳为三个判断：

• 如果你想保留 Spring Boot 默认的 MVC 能力，同时补充拦截器、格式化器、视图控制器等配置，就实现 WebMvcConfigurer，并加上 @Configuration。
• 这种场景下，不要加 @EnableWebMvc。
• 只有在你准备完全接管 Spring MVC 时，才需要使用 @EnableWebMvc。

先写一个自定义拦截器

第一步是定义拦截器类。最常见的做法是实现 HandlerInterceptor 接口，然后按需覆写请求前、请求后和完成后的三个生命周期方法。

@Component
//继承HandlerInterceptor
public class MyInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        System.out.println("preHandle method is running!");
        return true;
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        System.out.println("postHandle method is running!");
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        System.out.println("afterCompletion method is running!");
    }
}

这三个方法分别对应不同阶段：

preHandle：进入 Controller 之前执行

preHandle 会在请求真正进入处理器之前触发。示例里返回 true，表示继续向后执行；如果返回 false，请求链会被中断。

postHandle：Controller 执行之后、视图渲染之前

postHandle 适合做一些结果补充处理，例如往模型里塞公共数据，或者记录中间状态。

afterCompletion：整个请求结束之后

afterCompletion 会在整个请求完成后执行，适合清理资源、记录最终日志、统计耗时等场景。本文示例里只打印日志，主要用于验证拦截器是否已经接入成功。

通过 WebMvcConfigurer 注册拦截器

拦截器类写完后，还需要把它挂到 Spring MVC 的拦截器链中，否则项目启动了也不会生效。

@Configuration
//实现`WebMvcConfigurer`，并且添加`@Configuration`注解
public class MvcConfiguration implements WebMvcConfigurer {

    //注入定义的拦截器
    @Autowired
    private HandlerInterceptor myInterceptor;

    /**
     * 重写接口中的addInterceptors方法，添加自定义拦截器
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
/*拦截路径*/        registry.addInterceptor(myInterceptor).addPathPatterns("/**");
    }
}

这里有几个关键点要同时满足：

• 配置类要实现 WebMvcConfigurer。
• 配置类本身要加 @Configuration。
• 在 addInterceptors 方法里通过 registry.addInterceptor(...) 注册拦截器。
• addPathPatterns("/**") 表示拦截所有请求。

为什么这里不能加 @EnableWebMvc

这是很多人第一次配置拦截器时最容易踩的坑。当前场景的目标只是“在 Spring Boot 默认 MVC 能力上追加配置”，并不是自己完全重建一套 Spring MVC 配置。因此一旦加上 @EnableWebMvc，就可能关闭 Spring Boot 已经帮你准备好的自动配置，带来额外问题。

简单记住一句话就够了：想扩展，用 WebMvcConfigurer；想完全接管，才考虑 @EnableWebMvc。

怎么验证拦截器已经生效

项目启动后，访问任意一个接口，如果拦截器已经注册成功，控制台会输出下面三行：

preHandle method is running!

postHandle method is running!

afterCompletion method is running!

这说明请求已经完整经过了拦截器的三个典型阶段。

只看到三行日志，还想看更多 Spring MVC 细节怎么办

如果你发现控制台里只有这三条打印，而没有更多 Spring MVC 内部日志，通常不是拦截器有问题，而是日志级别默认不够高。Spring MVC 相关日志很多是 debug 级别，而 Spring Boot 默认一般只输出 info 及以上内容。

可以在 application.properties 或 application.yml 里补上这一行：

# 设置org.springframework包的日志级别为debug
logging.level.org.springframework=debug

重新运行后，就能看到更完整的 Spring MVC 调试日志，排查请求链问题会轻松很多。

配置要点总结

Spring Boot 配置拦截器，核心就两步：先实现一个 HandlerInterceptor，再在 WebMvcConfigurer 中注册它。真正影响结果的关键，不是代码量，而是有没有守住那条边界：保留 Spring Boot 默认 MVC 配置时，不要加 @EnableWebMvc。

如果只是做登录校验、权限判断、请求日志、通用埋点，这套方式已经足够。再配合 logging.level.org.springframework=debug，基本就能把“有没有进拦截器、在哪一步出了问题”看得比较清楚。