【Kotlin Spring Boot 4 从零到架构师】第 27 篇拦截器与过滤器本系列定位零基础入门从 Kotlin 语法一路到 Spring Boot 4 高级架构DDD Modulith适合 Java 开发者转型也适合纯新手系统学习。本篇你将学到Filter过滤器与 Interceptor拦截器的区别HandlerInterceptor的三个生命周期方法OncePerRequestFilter的使用执行顺序与使用场景学完本篇你将能为 mini-shop 添加请求日志、耗时统计、访问控制等横切功能。一、Filter vs Interceptor1.1 执行位置Spring MVC层Servlet容器层客户端请求Filter (doFilter)DispatcherServletInterceptor (preHandle)ControllerInterceptor (postHandle)Interceptor (afterCompletion)响应返回客户端1.2 核心区别维度FilterInterceptor所属Servlet 容器TomcatSpring MVC执行时机DispatcherServlet 前后Controller 前后能否访问 Controller不能能知道要执行哪个 Controller 方法能否访问 Spring Bean需要手动获取可以直接注入使用场景编码、CORS、日志、安全权限校验、日志、性能监控注册方式FilterRegistrationBeanWebMvcConfigurer二、HandlerInterceptor2.1 三个生命周期方法interfaceHandlerInterceptor{// Controller 执行前funpreHandle(request,response,handler):Boolean// Controller 执行后、视图渲染前funpostHandle(request,response,handler,modelAndView)// 请求完成后无论成功失败funafterCompletion(request,response,handler,ex)}方法执行时机返回值典型用途preHandleController 之前true继续false中断权限校验、限流postHandleController 之后void修改 Model、添加 HeaderafterCompletion全部完成后void清理资源、记录日志2.2 实战示例请求日志 耗时统计packagecom.example.minishop.interceptorimportjakarta.servlet.http.HttpServletRequestimportjakarta.servlet.http.HttpServletResponseimportorg.slf4j.LoggerFactoryimportorg.springframework.stereotype.Componentimportorg.springframework.web.servlet.HandlerInterceptorComponentclassRequestLoggingInterceptor:HandlerInterceptor{privatevallogLoggerFactory.getLogger(RequestLoggingInterceptor::class.java)privatevalstartTimeAttributerequestStartTimeoverridefunpreHandle(request:HttpServletRequest,response:HttpServletResponse,handler:Any):Boolean{valstartTimeSystem.currentTimeMillis()request.setAttribute(startTimeAttribute,startTime)log.info(→${request.method}${request.requestURI}from${request.remoteAddr})returntrue// 继续}overridefunafterCompletion(request:HttpServletRequest,response:HttpServletResponse,handler:Any,ex:Exception?){valstartTimerequest.getAttribute(startTimeAttribute)asLongvaldurationSystem.currentTimeMillis()-startTimevalstatusresponse.statusvalexceptionInfoif(ex!null) exception${ex.message}elselog.info(←${request.method}${request.requestURI}$status${duration}ms$exceptionInfo)}}2.3 注册拦截器packagecom.example.minishop.configimportcom.example.minishop.interceptor.RequestLoggingInterceptorimportorg.springframework.context.annotation.Configurationimportorg.springframework.web.servlet.config.annotation.InterceptorRegistryimportorg.springframework.web.servlet.config.annotation.WebMvcConfigurerConfigurationclassWebConfig(privatevalrequestLoggingInterceptor:RequestLoggingInterceptor):WebMvcConfigurer{overridefunaddInterceptors(registry:InterceptorRegistry){registry.addInterceptor(requestLoggingInterceptor).addPathPatterns(/api/**) // 拦截 /api/ 下所有请求 .excludePathPatterns(/api/health) // 排除健康检查端点 } }2.4 实战示例简单权限校验ComponentclassAuthInterceptor(// 拦截器可以注入 Spring BeanprivatevalauthService:AuthService):HandlerInterceptor{overridefunpreHandle(request:HttpServletRequest,response:HttpServletResponse,handler:Any):Boolean{valtokenrequest.getHeader(Authorization)if(token.isNullOrBlank()){response.contentTypeapplication/json;charsetUTF-8response.statusHttpServletResponse.SC_UNAUTHORIZED response.writer.write({code:401,message:未提供认证 Token})returnfalse// 中断请求}valisValidauthService.validateToken(token)if(!isValid){response.contentTypeapplication/json;charsetUTF-8response.statusHttpServletResponse.SC_UNAUTHORIZED response.writer.write({code:401,message:Token 无效或已过期})returnfalse}returntrue// 放行}}注册时指定拦截路径overridefunaddInterceptors(registry:InterceptorRegistry){registry.addInterceptor(authInterceptor).addPathPatterns(/api/**) .excludePathPatterns( /api/auth/login, // 登录接口不拦截 /api/auth/register, // 注册接口不拦截 /api/health, // 健康检查不拦截 /api/products/** // 商品浏览不拦截公开接口 ) }三、Filter3.1 OncePerRequestFilterSpring 提供了OncePerRequestFilter确保每个请求只执行一次避免请求转发时重复执行packagecom.example.minishop.filterimportjakarta.servlet.FilterChainimportjakarta.servlet.http.HttpServletRequestimportjakarta.servlet.http.HttpServletResponseimportorg.slf4j.LoggerFactoryimportorg.springframework.stereotype.Componentimportorg.springframework.web.filter.OncePerRequestFilterComponentclassRequestIdFilter:OncePerRequestFilter(){privatevallogLoggerFactory.getLogger(RequestIdFilter::class.java)overridefundoFilterInternal(request:HttpServletRequest,response:HttpServletResponse,filterChain:FilterChain){// 1. 从请求头获取或生成请求 IDvalrequestIdrequest.getHeader(X-Request-Id)?:generateRequestId()// 2. 设置到响应头中方便客户端排查response.setHeader(X-Request-Id,requestId)// 3. 存入请求属性供后续 Interceptor / Controller 使用request.setAttribute(requestId,requestId)try{// 4. 继续过滤器链filterChain.doFilter(request,response)}finally{log.debug(请求处理完成requestId$requestId)}}privatefungenerateRequestId():String{returnjava.util.UUID.randomUUID().toString().take(8)}}3.2 Filter 的注册Spring Boot 会自动注册带有Component的 Filter。如果需要自定义 URL 匹配ConfigurationclassFilterConfig{BeanfunrequestIdFilterRegistration(filter:RequestIdFilter):FilterRegistrationBeanRequestIdFilter{valregistrationFilterRegistrationBean(filter)registration.addUrlPatterns(/api/*) // 只拦截 /api/ 路径 registration.order 1 // 执行顺序数字越小越先执行 return registration } }四、执行顺序总结响应处理请求处理请求Filter (按order升序)Interceptor.preHandleControllerInterceptor.postHandleInterceptor.afterCompletionFilter (逆序)响应多过滤器场景请求Filter A (order1)Filter B (order2)Interceptor.preHandleControllerInterceptor.postHandleInterceptor.afterCompletionFilter B (逆序)Filter A (逆序)响应五、选择指南需求选择原因CORS 处理Filter在最外层处理不进入 Spring MVC字符编码设置Filter最早的时机设置编码请求日志Interceptor能拿到 Controller 信息耗时统计Interceptor精确到 Controller 执行时间权限/角色校验Interceptor能获取 Handler 信息请求 ID 追踪Filter最外层生成全链路可用限流Filter 或 Interceptor都可以看是否需要 Spring 上下文本篇小结知识点核心内容FilterServlet 层DispatcherServlet 之前/之后InterceptorSpring MVC 层Controller 之前/之后preHandle返回 false 中断请求postHandleController 之后可修改 ModelafterCompletion最终清理无论成功失败OncePerRequestFilter确保每个请求只过滤一次WebMvcConfigurer注册拦截器 配置路径执行顺序Filter → Interceptor → Controller下篇预告第 28 篇CORS 与文件上传前端跨域请求被拦截怎么办商品图片怎么上传到服务器下一篇解决这两个常见的 Web 开发问题。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。
【Kotlin Spring Boot 4 从零到架构师】第 27 篇拦截器与过滤器本系列定位零基础入门从 Kotlin 语法一路到 Spring Boot 4 高级架构DDD Modulith适合 Java 开发者转型也适合纯新手系统学习。本篇你将学到Filter过滤器与 Interceptor拦截器的区别HandlerInterceptor的三个生命周期方法OncePerRequestFilter的使用执行顺序与使用场景学完本篇你将能为 mini-shop 添加请求日志、耗时统计、访问控制等横切功能。一、Filter vs Interceptor1.1 执行位置Spring MVC层Servlet容器层客户端请求Filter (doFilter)DispatcherServletInterceptor (preHandle)ControllerInterceptor (postHandle)Interceptor (afterCompletion)响应返回客户端1.2 核心区别维度FilterInterceptor所属Servlet 容器TomcatSpring MVC执行时机DispatcherServlet 前后Controller 前后能否访问 Controller不能能知道要执行哪个 Controller 方法能否访问 Spring Bean需要手动获取可以直接注入使用场景编码、CORS、日志、安全权限校验、日志、性能监控注册方式FilterRegistrationBeanWebMvcConfigurer二、HandlerInterceptor2.1 三个生命周期方法interfaceHandlerInterceptor{// Controller 执行前funpreHandle(request,response,handler):Boolean// Controller 执行后、视图渲染前funpostHandle(request,response,handler,modelAndView)// 请求完成后无论成功失败funafterCompletion(request,response,handler,ex)}方法执行时机返回值典型用途preHandleController 之前true继续false中断权限校验、限流postHandleController 之后void修改 Model、添加 HeaderafterCompletion全部完成后void清理资源、记录日志2.2 实战示例请求日志 耗时统计packagecom.example.minishop.interceptorimportjakarta.servlet.http.HttpServletRequestimportjakarta.servlet.http.HttpServletResponseimportorg.slf4j.LoggerFactoryimportorg.springframework.stereotype.Componentimportorg.springframework.web.servlet.HandlerInterceptorComponentclassRequestLoggingInterceptor:HandlerInterceptor{privatevallogLoggerFactory.getLogger(RequestLoggingInterceptor::class.java)privatevalstartTimeAttributerequestStartTimeoverridefunpreHandle(request:HttpServletRequest,response:HttpServletResponse,handler:Any):Boolean{valstartTimeSystem.currentTimeMillis()request.setAttribute(startTimeAttribute,startTime)log.info(→${request.method}${request.requestURI}from${request.remoteAddr})returntrue// 继续}overridefunafterCompletion(request:HttpServletRequest,response:HttpServletResponse,handler:Any,ex:Exception?){valstartTimerequest.getAttribute(startTimeAttribute)asLongvaldurationSystem.currentTimeMillis()-startTimevalstatusresponse.statusvalexceptionInfoif(ex!null) exception${ex.message}elselog.info(←${request.method}${request.requestURI}$status${duration}ms$exceptionInfo)}}2.3 注册拦截器packagecom.example.minishop.configimportcom.example.minishop.interceptor.RequestLoggingInterceptorimportorg.springframework.context.annotation.Configurationimportorg.springframework.web.servlet.config.annotation.InterceptorRegistryimportorg.springframework.web.servlet.config.annotation.WebMvcConfigurerConfigurationclassWebConfig(privatevalrequestLoggingInterceptor:RequestLoggingInterceptor):WebMvcConfigurer{overridefunaddInterceptors(registry:InterceptorRegistry){registry.addInterceptor(requestLoggingInterceptor).addPathPatterns(/api/**) // 拦截 /api/ 下所有请求 .excludePathPatterns(/api/health) // 排除健康检查端点 } }2.4 实战示例简单权限校验ComponentclassAuthInterceptor(// 拦截器可以注入 Spring BeanprivatevalauthService:AuthService):HandlerInterceptor{overridefunpreHandle(request:HttpServletRequest,response:HttpServletResponse,handler:Any):Boolean{valtokenrequest.getHeader(Authorization)if(token.isNullOrBlank()){response.contentTypeapplication/json;charsetUTF-8response.statusHttpServletResponse.SC_UNAUTHORIZED response.writer.write({code:401,message:未提供认证 Token})returnfalse// 中断请求}valisValidauthService.validateToken(token)if(!isValid){response.contentTypeapplication/json;charsetUTF-8response.statusHttpServletResponse.SC_UNAUTHORIZED response.writer.write({code:401,message:Token 无效或已过期})returnfalse}returntrue// 放行}}注册时指定拦截路径overridefunaddInterceptors(registry:InterceptorRegistry){registry.addInterceptor(authInterceptor).addPathPatterns(/api/**) .excludePathPatterns( /api/auth/login, // 登录接口不拦截 /api/auth/register, // 注册接口不拦截 /api/health, // 健康检查不拦截 /api/products/** // 商品浏览不拦截公开接口 ) }三、Filter3.1 OncePerRequestFilterSpring 提供了OncePerRequestFilter确保每个请求只执行一次避免请求转发时重复执行packagecom.example.minishop.filterimportjakarta.servlet.FilterChainimportjakarta.servlet.http.HttpServletRequestimportjakarta.servlet.http.HttpServletResponseimportorg.slf4j.LoggerFactoryimportorg.springframework.stereotype.Componentimportorg.springframework.web.filter.OncePerRequestFilterComponentclassRequestIdFilter:OncePerRequestFilter(){privatevallogLoggerFactory.getLogger(RequestIdFilter::class.java)overridefundoFilterInternal(request:HttpServletRequest,response:HttpServletResponse,filterChain:FilterChain){// 1. 从请求头获取或生成请求 IDvalrequestIdrequest.getHeader(X-Request-Id)?:generateRequestId()// 2. 设置到响应头中方便客户端排查response.setHeader(X-Request-Id,requestId)// 3. 存入请求属性供后续 Interceptor / Controller 使用request.setAttribute(requestId,requestId)try{// 4. 继续过滤器链filterChain.doFilter(request,response)}finally{log.debug(请求处理完成requestId$requestId)}}privatefungenerateRequestId():String{returnjava.util.UUID.randomUUID().toString().take(8)}}3.2 Filter 的注册Spring Boot 会自动注册带有Component的 Filter。如果需要自定义 URL 匹配ConfigurationclassFilterConfig{BeanfunrequestIdFilterRegistration(filter:RequestIdFilter):FilterRegistrationBeanRequestIdFilter{valregistrationFilterRegistrationBean(filter)registration.addUrlPatterns(/api/*) // 只拦截 /api/ 路径 registration.order 1 // 执行顺序数字越小越先执行 return registration } }四、执行顺序总结响应处理请求处理请求Filter (按order升序)Interceptor.preHandleControllerInterceptor.postHandleInterceptor.afterCompletionFilter (逆序)响应多过滤器场景请求Filter A (order1)Filter B (order2)Interceptor.preHandleControllerInterceptor.postHandleInterceptor.afterCompletionFilter B (逆序)Filter A (逆序)响应五、选择指南需求选择原因CORS 处理Filter在最外层处理不进入 Spring MVC字符编码设置Filter最早的时机设置编码请求日志Interceptor能拿到 Controller 信息耗时统计Interceptor精确到 Controller 执行时间权限/角色校验Interceptor能获取 Handler 信息请求 ID 追踪Filter最外层生成全链路可用限流Filter 或 Interceptor都可以看是否需要 Spring 上下文本篇小结知识点核心内容FilterServlet 层DispatcherServlet 之前/之后InterceptorSpring MVC 层Controller 之前/之后preHandle返回 false 中断请求postHandleController 之后可修改 ModelafterCompletion最终清理无论成功失败OncePerRequestFilter确保每个请求只过滤一次WebMvcConfigurer注册拦截器 配置路径执行顺序Filter → Interceptor → Controller下篇预告第 28 篇CORS 与文件上传前端跨域请求被拦截怎么办商品图片怎么上传到服务器下一篇解决这两个常见的 Web 开发问题。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。
