一、引言
拦截器的基本概念
在现代 Java Web 开发中，拦截器（Interceptor）是一种用于在请求处理前后插入自定义逻辑的机制。简单来说，它是一种“横切逻辑处理器”，可以用来对请求进行预处理、后处理，甚至终止请求的继续执行。
它通常用于对控制器（Controller）方法进行增强，而不需要修改控制器本身的代码，实现逻辑与业务的解耦。
类似于门卫，它能在用户请求进入“房间”（Controller）之前或之后，进行安检、打卡或记录日志等操作。
拦截器的应用场景
拦截器在实际开发中的应用非常广泛，尤其在Spring MVC项目中几乎是标配工具，常见使用场景包括：
权限校验：验证用户是否已登录，是否有访问某接口的权限。
日志记录：记录请求的路径、方法、参数和响应信息，便于后续问题排查。
性能监控：计算接口的执行耗时，帮助开发者发现性能瓶颈。
请求预处理：如统一设置编码、参数转换、接口签名校验等。
响应后处理：如在响应返回前追加通用信息或处理返回结构。
与过滤器（Filter）和 AOP 的对比
特性Filter（过滤器）Interceptor（拦截器）AOP（面向切面编程）所属层级Servlet 规范Spring MVCSpring AOP拦截范围所有请求（包括静态资源）控制器请求（Handler）任意方法（基于切点）使用场景通用处理，如编码设置、日志权限、登录校验等业务层处理日志、事务、缓存、异常捕捉等配置方式web.xml 或注解Spring 配置类中注册注解（@Aspect）、配置切面拦截粒度粒度较粗，Servlet 前粒度适中，Handler 层粒度最细，可作用于任意方法
简而言之：
Filter 更底层，作用于整个请求生命周期；
Interceptor 更贴近业务逻辑，专注于控制器调用；
AOP 最灵活，适用于各种“横切关注点”逻辑处理。
二、Java 中拦截器的常见实现方式 🛠️
Java 中的拦截器可以通过多种方式实现，不同技术栈和场景有不同的最佳实践。以下是三种最常见的实现方式：
1️⃣ Servlet 拦截器（Filter）
⚙️ 工作原理
Filter 是 Servlet 规范定义的一种机制，属于 Java EE 标准，在请求进入 Servlet 前或响应返回客户端前进行拦截。它通常用在 Web 层处理一些通用逻辑，如设置编码、日志记录、安全控制等。
🔄 生命周期
Filter 生命周期如下：
初始化：容器启动时调用 init()；
请求处理：每次请求通过时执行 doFilter()；
销毁：容器关闭时调用 destroy()。
💡 示例代码：记录请求日志
@WebFilter(urlPatterns = "/*")
public class LogFilter implements Filter {
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
HttpServletRequest req = (HttpServletRequest) request;
System.out.println("请求路径: " + req.getRequestURI());
chain.doFilter(request, response);
}
}
📌 适合用于：编码统一、访问统计、跨域处理等通用任务。
2️⃣ Spring MVC 拦截器（HandlerInterceptor）
📑 接口简介
Spring MVC 提供了 HandlerInterceptor 接口，以及一个简化实现类 HandlerInterceptorAdapter（从 Spring 5.3 起已废弃，推荐直接实现接口）。
🔍 方法解析
preHandle()：控制器方法调用前执行，可用于权限校验（返回 false 则请求中断）；
postHandle()：控制器执行后、视图渲染前调用；
afterCompletion()：整个请求完成后调用（如资源清理、异常处理等）。
🔐 示例代码：权限校验
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
throws Exception {
Object user = request.getSession().getAttribute("user");
if (user == null) {
response.sendRedirect("/login");
return false;
}
return true;
}
}
🔧 注册拦截器：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new AuthInterceptor())
.addPathPatterns("/**")
.excludePathPatterns("/login", "/static/**");
}
}
📌 适合用于：登录校验、权限控制、接口限流等业务逻辑相关场景。
3️⃣ AOP（面向切面编程）方式的拦截
🧵 基于注解的切面拦截（@Aspect）
AOP 是 Spring 提供的一种强大机制，用于将“横切逻辑”（如日志、事务、缓存）与业务代码彻底解耦。只要是 Spring 管理的 Bean 方法，都可以通过 AOP 拦截。
🎯 Pointcut 表达式简介
@Pointcut("execution(* com.example.service..*(..))")：拦截 service 包及子包中所有方法；
@Before / @After / @Around：分别在方法执行前、后或整个过程中插入逻辑。
📝 示例代码：统一日志处理
@Aspect
@Component
public class LogAspect {
@Pointcut("execution(* com.example.controller..*(..))")
public void controllerMethods() {}
@Before("controllerMethods()")
public void logBefore(JoinPoint joinPoint) {
System.out.println("访问方法: " + joinPoint.getSignature().toShortString());
System.out.println("参数: " + Arrays.toString(joinPoint.getArgs()));
}
}
📌 适合用于：日志、事务、异常处理、性能监控等通用横切需求。
三、自定义拦截器 ✍️
在实际项目中，默认提供的拦截器功能可能无法完全满足特定需求，这时我们就需要自定义拦截器来处理特定的业务逻辑，比如登录校验、接口签名验证、敏感操作审计等。
下面我们一步一步来实现一个自定义拦截器 👇
1️⃣ 如何编写自己的拦截器类
在 Spring MVC 中，自定义拦截器只需要实现 HandlerInterceptor 接口，并重写其中的方法即可。
public class CustomInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
System.out.println("🚦 请求开始 - URL: " + request.getRequestURI());
return true; // 返回 false 则中断请求
}
@Override
public void postHandle(HttpServletRequest request, HttpServletResponse response,
Object handler, ModelAndView modelAndView) throws Exception {
System.out.println("📦 控制器处理完成");
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) throws Exception {
System.out.println("✅ 请求完成");
}
}
📌 Tip：你可以只实现 preHandle()，其他两个方法不实现也没问题。
2️⃣ 如何注册拦截器
要让 Spring 识别并使用我们自定义的拦截器，需要通过实现 WebMvcConfigurer 接口中的 addInterceptors() 方法进行注册。
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new CustomInterceptor())
.addPathPatterns("/**") // 拦截所有请求
.excludePathPatterns("/login", "/error"); // 排除登录和错误页面
}
}
3️⃣ 配置拦截路径（include / exclude）
Spring 提供了灵活的路径匹配方式：
addPathPatterns()：指定要拦截的路径（支持 /**、/api/** 等通配符）；
excludePathPatterns()：指定不拦截的路径，如静态资源、登录页面等。
✅ 示例配置：
registry.addInterceptor(new AuthInterceptor())
.addPathPatterns("/admin/**", "/user/**") // 只拦截 /admin 和 /user 开头的请求
.excludePathPatterns("/user/login", "/static/**"); // 登录接口和静态资源不拦截
这让你可以精确控制哪些接口需要“守门”，哪些接口可以直接放行。
📌 小结：
自定义拦截器灵活强大，能精准控制请求流程；
注册时配置好路径规则，避免误拦（如静态资源、登录页）；
通常与登录校验、行为日志、安全审计等结合使用，提升系统健壮性。
四、拦截器执行顺序与链式调用 🔗
在实际开发中，一个项目往往不止一个拦截器。比如，你可能同时使用了登录拦截器、日志拦截器、接口限流拦截器等。**这些拦截器是如何协同工作的？它们的执行顺序如何确定？中途终止又会发生什么？**下面我们来逐一讲解 👇
1️⃣ 多个拦截器的执行顺序
Spring MVC 中的拦截器是按注册顺序组成拦截链的。假设你注册了三个拦截器：
registry.addInterceptor(new AInterceptor());
registry.addInterceptor(new BInterceptor());
registry.addInterceptor(new CInterceptor());
执行顺序如下：
preHandle()：A → B → C
postHandle()：C → B → A
afterCompletion()：C → B → A
🧠 记忆小技巧：
preHandle 正序入场，postHandle 和 afterCompletion 倒序退场，就像调用栈的压栈和出栈操作。
2️⃣ 如何控制执行顺序 🧭
有两种主要方式可以控制拦截器的执行顺序：
✅ 方式一：注册顺序决定先后
Spring MVC 默认按照 addInterceptor() 的顺序执行拦截器链。这是最常用也最直观的方法。
🏷️ 方式二：使用 @Order 注解（对 Bean 注册时生效）
如果你通过 Spring 的方式将拦截器注入（比如 @Bean 或 @Component），可以使用 @Order 指定优先级：
@Component
@Order(1)
public class FirstInterceptor implements HandlerInterceptor {
// 优先执行
}
值越小，优先级越高。注意，@Order 只在 Bean 自动注入时生效，手动 new 的方式无效。
3️⃣ 拦截器链中断的处理逻辑 🛑
每个 preHandle() 方法都返回一个 boolean 值：
返回 true：继续执行下一个拦截器或控制器方法；
返回 false：拦截链立即中断，后续拦截器不会被执行，控制器方法也不会被调用。
例如：
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
if (!isAuthorized(request)) {
response.sendRedirect("/unauthorized");
return false; // 中断链路
}
return true;
}
🔔 注意事项：
中断后，只有当前拦截器的 afterCompletion() 会执行，其他已注册但未执行的拦截器方法将被跳过。
可以通过 response 返回错误提示或重定向，防止继续请求控制器。
📌 小结：
拦截器执行顺序 = 注册顺序；
可通过 @Order 控制优先级（仅限 Bean 注册）；
一旦有拦截器返回 false，链路即刻中断，防止后续逻辑执行。
五、拦截器实战案例 🧪
这一部分，我们围绕几个典型的业务需求，手把手展示拦截器的实际用法。这些场景非常常见，99% 的项目都能用得上！
1️⃣ 登录鉴权拦截器 🔐
目的：判断用户是否已登录，未登录则重定向至登录页。
public class LoginInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
throws Exception {
Object user = request.getSession().getAttribute("loginUser");
if (user == null) {
response.sendRedirect("/login");
return false; // 阻止未登录请求继续向下执行
}
return true;
}
}
📌 常配合 Session、Token 或 Spring Security 使用。
2️⃣ 接口防刷（限流）拦截器 🚦
目的：防止接口被频繁调用（比如验证码接口、短信发送等）。
public class RateLimitInterceptor implements HandlerInterceptor {
private Map
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
String ip = request.getRemoteAddr();
long now = System.currentTimeMillis();
Long lastVisit = visitMap.get(ip);
if (lastVisit != null && now - lastVisit < 2000) {
response.setStatus(429); // Too Many Requests
return false;
}
visitMap.put(ip, now);
return true;
}
}
📌 建议结合 Redis 做分布式限流，高并发更稳！
3️⃣ 日志跟踪（Trace ID）拦截器 🧾
目的：为每个请求生成唯一标识 TraceId，便于链路追踪和日志排查。
public class TraceInterceptor implements HandlerInterceptor {
private static final ThreadLocal
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
String traceId = UUID.randomUUID().toString();
TRACE_ID_HOLDER.set(traceId);
MDC.put("traceId", traceId); // 与日志框架整合
System.out.println("Trace ID: " + traceId);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) {
TRACE_ID_HOLDER.remove();
MDC.remove("traceId");
}
}
📌 搭配 Logback、ELK 可实现完整请求链路分析。
4️⃣ 参数解密 / 加密拦截器 🕵️♂️
目的：对敏感参数进行解密处理，避免暴露明文。
public class DecryptInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
throws Exception {
String encrypted = request.getParameter("data");
if (encrypted != null) {
String decrypted = AESUtil.decrypt(encrypted);
request.setAttribute("decryptedData", decrypted);
}
return true;
}
}
📌 更严谨的做法是配合 HttpServletRequestWrapper 改写参数，或使用 AOP 切面做解密处理。
✅ 总结
拦截器名称应用场景核心方法登录鉴权登录校验、权限控制preHandle()接口限流防止刷接口、重复请求preHandle()日志跟踪日志链路追踪preHandle()、afterCompletion()参数加解密保护敏感数据传输preHandle()
你可以组合使用多个拦截器构建完整的“请求防火墙”，让系统更安全、更健壮、更易维护 🚀
六、注意事项与最佳实践 📌
拦截器虽然好用，但也不是“万能胶水”，用不好不仅效率低，还容易埋下“隐形炸弹”。下面是开发中总结出的几个关键建议，助你避坑+提效 ✅
1️⃣ 避免拦截器滥用 🚫
拦截器适合处理横切关注点，不宜塞入业务逻辑！
❌ 不要在拦截器中调用数据库或远程接口做复杂业务判断；
❌ 不要在拦截器中写 if-else 处理业务流程分支；
✅ 应该专注做认证、日志、限流、数据预处理等通用任务。
📌 把拦截器当作“守门员”而不是“中场指挥官”！
2️⃣ 拦截器中不要执行耗时操作 🐢
拦截器运行在请求链最前面，一旦卡住，就等于所有请求都被堵住了！
❌ 不建议做复杂计算、大数据遍历、延时操作；
✅ 把耗时任务丢到 MQ、线程池或异步逻辑中处理；
✅ 如必须处理，建议加缓存或设定超时时间 ⏱️。
3️⃣ 异常处理与容错设计 🧯
如果拦截器抛出异常，整个请求就直接挂了……
建议处理方式：
✅ 用 try-catch 包裹敏感逻辑，避免错误传递到 Controller；
✅ 配合 afterCompletion() 做清理工作；
✅ 出错时设置 HTTP 状态码或返回友好提示信息；
try {
// some logic
} catch (Exception e) {
response.setStatus(500);
response.getWriter().write("系统内部错误，请稍后再试");
return false;
}
4️⃣ 拦截器的可测试性与可维护性 🧪
别让拦截器变成“不可单测的黑盒”：
✅ 尽量将逻辑抽出为独立的工具类或 Service，便于测试；
✅ 避免直接在拦截器中写大量逻辑判断；
✅ 为拦截器添加日志或 Trace ID，方便排查问题；
示例：
if (!authService.checkPermission(user, request.getRequestURI())) {
log.warn("无权限访问: {}", request.getRequestURI());
response.sendRedirect("/403");
return false;
}
✅ 总结一句话：
拦截器越轻巧越好，越专注越安全，越解耦越持久。
七、总结 🧭
走到这里，我们已经把 Java 拦截器的前世今生都聊透了。从基本原理，到实战场景，再到注意事项和最佳实践，最后我们来为这篇文章画个圆满的句号 ✅
✅ 拦截器的优势与不足 ⚖️
优势 💪不足 ⚠️统一处理横切关注点（如登录、日志）粒度有限，基于请求级别实现简单，集成方便（尤其在 Spring MVC 中）不适合复杂业务逻辑不依赖注解或代理，适合非 Spring 控制层拓展性、灵活性略低于 AOP可以实现路径级别的精细控制不适用于方法内部逻辑处理
🤔 何时用拦截器，何时用 AOP？
拦截器 vs AOP，不是“谁好谁坏”，而是“谁更适合”：
使用场景推荐方案登录校验、权限控制、日志追踪、请求预处理✅ 拦截器方法级别的日志、事务、缓存、异常处理✅ AOP（@Aspect）非 Spring 项目或与 Servlet 相关的过滤逻辑✅ Filter对所有请求进行统一拦截拦截器 or Filter
🎯 简单记：
“面向请求” → 拦截器，
“面向方法” → AOP，
“低层控制” → Filter。
🧱 拦截器能让系统更“可插拔”吗？
答案是 ✅ 可以！
将公共逻辑提取成拦截器，使控制器保持“干净”；
所有新增功能（限流、审计、追踪）都可以通过新建拦截器实现，无需侵入原有业务代码；
拦截器组合 + 精准路径配置，构建“模块化的请求处理流程”；
这是一种“像拼乐高一样搭系统”的思路，非常适合构建高扩展性、高可维护性的后端架构 🧩
📌 最后的最后，一句话送给你：
“让拦截器做它擅长的事，让系统更清晰、更健壮。”
好的！来一份精炼到位、适合打印/收藏/贴墙的 ✅Java 拦截器速查表（Cheat Sheet），帮你查阅不迷路，一页吃透精华内容 🚀💡
🧾附录：Java 拦截器速查表 Cheat Sheet
✅ 拦截器三大主角
类型场景特点Filter（Servlet）请求预处理、资源过滤最底层，独立于 Spring，可拦截所有请求HandlerInterceptor（Spring MVC）登录校验、日志、限流控制器执行前后切入，路径可控，最常用AOP（@Aspect）方法级别日志、事务、缓存基于注解/切面，粒度更细，适合业务逻辑处理
🚦 拦截器核心方法（Spring）
方法名作用描述执行时机preHandle()请求前处理，返回 false 拦截请求Controller 前postHandle()请求处理后，但尚未渲染视图Controller 后afterCompletion()请求完全结束，用于资源清理渲染视图后（无论成功/失败）
💡 常见用途实战场景
用途描述推荐方案登录拦截未登录用户重定向至登录页拦截器 + Session权限控制判断用户权限是否足够拦截器 + 注解/AOP接口限流控制访问频率，防刷防爆拦截器 + Redis日志追踪给每个请求生成 traceId拦截器 + MDC 日志参数解密请求参数加密传输，后端解密拦截器 + Wrapper
⚙️ 控制顺序 & 注册技巧
执行顺序：preHandle() 正序 → postHandle() & afterCompletion() 逆序
注册顺序：决定执行顺序（优先注册优先执行）
@Order 注解：Bean 注入方式时可设置优先级（数值越小越先执行）
🚫 拦截器开发注意事项
建议原因✅ 保持职责单一避免逻辑混乱，易维护❌ 避免耗时操作拦截器在请求入口，影响整体性能✅ 处理异常 & 清理资源保证服务健壮性 & 防止内存泄露✅ 可测试性好将逻辑抽出为 Service，方便单元测试✅ 拦截路径精准配置（include/exclude）防止不必要的拦截，提高效率
🎯 拦截器 vs AOP 使用建议
使用场景推荐方式请求路径级别、认证限流等拦截器业务方法级别、事务/日志等AOP（@Aspect）静态资源过滤、低层处理Filter
🧩 一图胜千言（推荐搭配架构图使用）
Filter → Interceptor → Controller → AOP → Service
✅ 从粗到细，层层递进，职责明确！
🔚 结语
拦截器虽小，却是构建高质量 Java Web 应用不可或缺的一环。它不仅能提升系统的安全性与可维护性，更为我们提供了模块化扩展的灵活能力。
希望这篇文章能帮你全面理解拦截器的设计理念与实践方式，从 Filter 到 Spring Interceptor，再到 AOP 的结合应用，搭建出一套稳健、可控、可持续演进的后端架构。
技术是工具，架构是思维，落地才是王道。
如果你觉得这篇文章对你有帮助，欢迎 👍 点赞收藏，或转发给有需要的同事朋友。后续我也会继续分享更多 Java & Spring 实战干货，咱们下篇见！👋😄