Spring Boot配置拦截器需两步：先实现HandlerInterceptor接口重写preHandle等方法，再通过WebMvcConfigurer的addInterceptors注册并配置路径；它仅拦截Controller请求，不处理静态资源、JSP或Servlet。
Spring Boot 配置拦截器来过滤请求，核心是两步：写一个实现 HandlerInterceptor 的类，再通过 WebMvcConfigurer 把它注册进 MVC 请求链。它不拦截静态资源、JSP 或 Servlet，只作用于 Spring MVC 管理的 Controller 请求。
1. 编写拦截器类
创建一个类，实现 HandlerInterceptor 接口，重点重写 preHandle 方法做权限或校验逻辑：
-
preHandle：请求到达 Controller 前执行，返回
false可直接中断请求（比如 token 失效时返回 401） -
postHandle：Controller 执行完、视图渲染前，适合修改
ModelAndView - afterCompletion：整个请求结束后调用，适合清理资源或记录耗时
示例（简单登录校验）：
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {
String token = request.getHeader("Authorization");
if (token == null || !token.startsWith("Bearer ")) {
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Missing token");
return false;
}
// 这里可解析 token、查用户、存入 request 或 ThreadLocal
return true;
}
}
2. 注册拦截器并配置路径
新建一个配置类，实现 WebMvcConfigurer，在 addInterceptors 中添加拦截器实例，并指定拦截/排除路径：
- 用
addPathPatterns("/**")拦截全部请求 - 用
excludePathPatterns("/login", "/api/public/**", "/static/**")放行免鉴权路径 - 多个拦截器按添加顺序执行，先加的先运行
示例：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new AuthInterceptor())
.addPathPatterns("/**")
.excludePathPatterns("/login", "/error", "/static/**", "/swagger-ui/**");
}
}
3. 注意事项与常见问题
拦截器不是万能的，要注意它的边界和限制：
- 它无法拦截静态资源（如
/css/app.css）、错误页（/error）、Actuator 端点（除非显式配置路径匹配） - 若需拦截所有 HTTP 流量（包括静态文件、健康检查等），应改用
Filter，它由 Servlet 容器管理，更底层 - 拦截器内可直接注入
@Service、@Repository等 Spring Bean；而 Filter 不能直接依赖注入，需手动从 ApplicationContext 获取 - 如果项目用了 Spring Security，通常优先用其
SecurityFilterChain做认证授权，拦截器更适合业务级增强（如日志、参数预处理）
4. 替代方案：什么时候该用 Filter？
当你要处理以下场景时，Filter 更合适：
- 统一设置请求/响应编码（
request.setCharacterEncoding("UTF-8")） - 跨域头（
CorsFilter）或敏感信息脱敏（如隐藏手机号中间四位） - 全链路 TraceId 注入、请求体解密、GZIP 压缩
- 需要对
/favicon.ico、/actuator/health等非 Controller 资源生效
Filter 配置方式有两种：@WebFilter 注解 + @ServletComponentScan，或 FilterRegistrationBean 方式注册 Bean —— 后者更推荐，便于控制顺序和条件化启用。
