主题
Web过滤器与统一响应
一句话:所有横切动作都挂在一条显式的过滤器顺序表上(
WebFilterOrderEnum),谁在前谁在后都有理由;异常统一由GlobalExceptionHandler转成CommonResult,HTTP 状态码恒为 200,业务码才是给前端看的。
适用场景:新增一个过滤器要想清楚插在哪;排查「请求体读不到」「XSS 没生效」「401 为什么没有 HTTP 401」;理解统一响应到底包了什么。
不适用场景:接口鉴权逻辑本身(看鉴权与权限点);租户上下文怎么建立(看多租户)。
1. WebFilterOrderEnum:顺序即契约
pmforge-common 的 com.pmforge.framework.common.enums.WebFilterOrderEnum 是一个只放常量的接口,所有 starter 都从这里取 order,避免各写各的数字:
| 常量 | 值 | 作用 | 为什么排在这 |
|---|---|---|---|
CORS_FILTER | Integer.MIN_VALUE(#L12) | 处理跨域 | 必须最先,预检请求要在任何业务逻辑前返回 |
TRACE_FILTER | MIN_VALUE + 1(#L14) | 链路 traceId | 紧跟 CORS,让后续所有日志都带 traceId |
REQUEST_BODY_CACHE_FILTER | MIN_VALUE + 500(#L16) | 缓存请求体,允许重复读 | 必须在加密、日志、XSS 之前 |
API_ENCRYPT_FILTER | REQUEST_BODY_CACHE + 1(#L18) | 请求解密 / 响应加密 | 解密后才能读明文;加密最后写响应 |
(Spring 的 OrderedRequestContextFilter) | -105(#L20 注释) | 请求上下文 | 由 Spring 定义,不要插到它前面去改 |
TENANT_CONTEXT_FILTER | -104(#L22) | 从 Header 取 tenant-id 放进 TTL | 必须在访问日志前,否则日志记不到租户 |
API_ACCESS_LOG_FILTER | -103(#L24) | 访问日志 | 必须在请求体缓存之后(要读 body) |
XSS_FILTER | -102(#L26) | 包装请求做 XSS 过滤 | 在日志之后,日志记原始值 |
| (Spring Security 过滤器链) | -100(#L28 注释) | 认证 | 在租户上下文之后 |
TENANT_SECURITY_FILTER | -99(#L30) | 校验租户合法性 / 租户切换权限 | 必须在 Security 之后(要读 LoginUser) |
FLOWABLE_FILTER | -98(#L32) | 工作流上下文 | 依赖登录态 |
DEMO_FILTER | Integer.MAX_VALUE(#L34) | 演示环境禁止写操作 | 最后,只拦真正要执行的请求 |
记法:越接近 MIN_VALUE 越靠外。请求进来先 CORS、再缓存 body、再解密,然后才是「业务相关」的租户、日志、XSS、安全。
两个注册细节:
- 业务过滤器都继承
ApiRequestFilter,它的shouldNotFilter只放行/admin-api与/app-api前缀(core/filter/ApiRequestFilter.java#L21-L25),所以 actuator、静态资源不会被打扰。 - 统一用
PmforgeWebAutoConfiguration#createFilterBean(#L138-L142)注册FilterRegistrationBean并带上 order,不要用@Order加在 Bean 上——@Order对 Servlet 过滤器不保证顺序。
2. TokenAuthenticationFilter 与 Spring Security 的关系
TokenAuthenticationFilter 不是 WebFilter,它是注入到 Spring Security 过滤器链里的:
java
httpSecurity.addFilterBefore(authenticationTokenFilter, UsernamePasswordAuthenticationFilter.class);见 PmforgeWebSecurityConfigurerAdapter#L151。所以它跑在 WebFilterOrderEnum 的「Security 位置」(-100),而不是某个 -1xx。
它做三件事(TokenAuthenticationFilter.java#L42-L69):
- 取 token(Header 优先、Parameter 兜底,
SecurityFrameworkUtils#L41-L54),调oauth2TokenApi.checkAccessToken换LoginUser; - 有用户就
SecurityFrameworkUtils.setLoginUser:写入SecurityContextHolder,同时把 userId/userType 写进 request attribute(#L125-L132,注释说明访问日志在 Security 之前,只能从 request 里拿); - 自身异常不外抛,走
globalExceptionHandler.allExceptionHandler(request, ex)再ServletUtils.writeJSON直接结束响应(#L60-L64)。
认证失败(没 token 或 token 无效)不在这里返回:它交给 ExceptionTranslationFilter → AuthenticationEntryPointImpl#L29-L33 输出 401。鉴权失败由方法级 @PreAuthorize 抛 AccessDeniedException,两条路分别落到 AccessDeniedHandlerImpl#L34-L41 与 GlobalExceptionHandler#L262-L267。
3. GlobalExceptionHandler:业务码到 HTTP 的映射
@RestControllerAdvice(#L54),每个 handler 都返回 CommonResult,不设置 HTTP 状态码:
| 异常 | 业务码 | 行 |
|---|---|---|
MissingServletRequestParameterException | 400 | #L122-L126 |
MethodArgumentTypeMismatchException | 400 | #L133-L137 |
MethodArgumentNotValidException | 400 + 字段错误 | #L142-L162 |
BindException | 400 | #L167-L173 |
HttpMessageNotReadableException | 400 | #L180-L192 |
ConstraintViolationException | 400 | #L197-L202 |
MaxUploadSizeExceededException | 400 | #L217-L220 |
NoHandlerFoundException | 404 | #L229-L233 |
HttpRequestMethodNotSupportedException | 405 | #L240-L244 |
HttpMediaTypeNotSupportedException | 400 | #L251-L255 |
AccessDeniedException | 403 | #L262-L267 |
ServiceException | 异常自带 code | #L284-L302 |
其它 Exception | 500 | #L307-L327 |
ServiceException 是业务代码唯一该抛的异常:CommonResult.error(ex.getCode(), ex.getMessage())(#L284-L302),code 来自 ErrorCode(全局码 0-999,业务码从 1_000_000_000 起,见 pmforge-common/.../exception/ErrorCode.java)。
兜底 handler 有几个细节:
- 先拆
ExecutionException/UncheckedExecutionException的 cause(#L274-L277、#L311-L313),否则@Cacheable里抛的业务异常会被当成 500; handleTableNotExists按表前缀识别「模块未导入」并返回 501NOT_IMPLEMENTED(#L378-L456),这是单体多模块的兼容手段:库里有表、代码没引入模块时,给前端一个可读提示而不是 500;- 5xx 才异步落
api_error_log(#L324),4xx 不落,避免刷库。
4. GlobalResponseBodyHandler:只记录,不包装
GlobalResponseBodyHandler 实现 ResponseBodyAdvice(#L23-L24),但 supports 只对返回类型正好是 CommonResult.class 生效(#L28-L34),beforeBodyWrite 只做一件事:WebFrameworkUtils.setCommonResult(request, body),然后原样返回(#L38-L43)。
为什么不自动把任意返回值包成 CommonResult?源码注释写得很直接(#L16-L21):AOP 不应该改变 Controller 的数据结构。自动包装会让「返回 CommonResult」和「返回 UserVO」两种写法行为不一致,也会破坏文件下载、ResponseEntity、三方回调等场景。它存在的唯一目的是把结果放进 request attribute,供后置的 ApiAccessLogFilter 记录响应体(ApiAccessLogFilter#L116-L123)。
5. XSS / 加解密 / 访问日志:开关与位置
| 能力 | 过滤器(order) | 开关 | 位置理由 |
|---|---|---|---|
| 请求体缓存 | CacheRequestBodyFilter(MIN+500) | 无开关,命中 URI 规则即生效 | 让后面三方都能重复读 body |
| API 加解密 | ApiEncryptFilter(MIN+501) | pmforge.api-encrypt.enable=false(yaml #L275-L281) | 最早解密、最晚加密(ApiEncryptFilter#L114-L124) |
| 访问日志 | ApiAccessLogFilter(-103) | pmforge.access-log.enable,默认 true | 在 XSS 之前,日志记录原始请求(#L71-L72 注释) |
| XSS | XssFilter(-102) | pmforge.xss.enable=false(yaml #L267-L271) | 包 XssRequestWrapper(XssFilter#L35-L38),另注册 Jackson 反序列化器(PmforgeXssAutoConfiguration#L42-L51) |
加解密的注解优先级:先看方法上的 @ApiEncrypt,再看类上的(ApiEncryptFilter#L148-L150)。只有 POST/PUT/DELETE 且带 X-Api-Encrypt 头才解密(#L97-L111);响应是否加密由 @ApiEncrypt(response = true) 决定,且包装顺序保证「最后加密」。
XSS 注意:它只处理 JSON 请求体(escape 由 XssStringJsonDeserializer 完成)和参数包装,不处理富文本白名单之外的 HTML;富文本字段应在前端/业务侧另行放行,不要指望全局过滤器。
6. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
请求体只能读一次 / getInputStream 报错 | REQUEST_BODY_CACHE_FILTER 是否注册 | 缓存过滤器被移除,或 URI 命中 CacheRequestBodyFilter#L26 的忽略列表 |
| XSS 没过滤 | pmforge.xss.enable、XssFilter#L41-L50 | yaml 里默认 false;excludeUrls 命中;或参数不是 JSON body |
| 解密失败 | ApiEncryptFilter#L91-L111 | header 名不对、算法与密钥不匹配、请求方法不是 POST/PUT/DELETE |
| 加密响应被截断 | ApiEncryptFilter#L114-L124 | 包装器顺序错,或另一个过滤器提前写了响应 |
| 访问日志没有响应体 | ApiAccessLogFilter#L137-L140 | responseEnable 默认 false,需要在 @ApiAccessLog 上打开 |
| 前端拿不到 HTTP 401/403 | 设计如此 | 全部返回 200 + CommonResult.code;要 HTTP 码得自己加 @ResponseStatus |
| 过滤器顺序不对 | WebFilterOrderEnum | 检查是否用 FilterRegistrationBean 设 order,而不是 @Order |
| 静态资源被过滤器拦了 | ApiRequestFilter#L21-L25 | 只有 /admin-api、/app-api 前缀才进业务过滤器 |
| 模块表存在但接口 501 | GlobalExceptionHandler#L378-L456 | 表前缀对应的模块没引入,返回 NOT_IMPLEMENTED 是预期 |