Skip to content

Web过滤器与统一响应 ​

一句话:所有横切动作都挂在一条显式的过滤器顺序表上(WebFilterOrderEnum),谁在前谁在后都有理由;异常统一由 GlobalExceptionHandler 转成 CommonResult,HTTP 状态码恒为 200,业务码才是给前端看的。

适用场景:新增一个过滤器要想清楚插在哪;排查「请求体读不到」「XSS 没生效」「401 为什么没有 HTTP 401」;理解统一响应到底包了什么。

不适用场景:接口鉴权逻辑本身(看鉴权与权限点);租户上下文怎么建立(看多租户)。

1. WebFilterOrderEnum:顺序即契约 ​

pmforge-common 的 com.pmforge.framework.common.enums.WebFilterOrderEnum 是一个只放常量的接口,所有 starter 都从这里取 order,避免各写各的数字:

常量值作用为什么排在这
CORS_FILTERInteger.MIN_VALUE(#L12)处理跨域必须最先,预检请求要在任何业务逻辑前返回
TRACE_FILTERMIN_VALUE + 1(#L14)链路 traceId紧跟 CORS,让后续所有日志都带 traceId
REQUEST_BODY_CACHE_FILTERMIN_VALUE + 500(#L16)缓存请求体,允许重复读必须在加密、日志、XSS 之前
API_ENCRYPT_FILTERREQUEST_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_FILTERInteger.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):

  1. 取 token(Header 优先、Parameter 兜底,SecurityFrameworkUtils#L41-L54),调 oauth2TokenApi.checkAccessToken 换 LoginUser;
  2. 有用户就 SecurityFrameworkUtils.setLoginUser:写入 SecurityContextHolder,同时把 userId/userType 写进 request attribute(#L125-L132,注释说明访问日志在 Security 之前,只能从 request 里拿);
  3. 自身异常不外抛,走 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 状态码:

异常业务码行
MissingServletRequestParameterException400#L122-L126
MethodArgumentTypeMismatchException400#L133-L137
MethodArgumentNotValidException400 + 字段错误#L142-L162
BindException400#L167-L173
HttpMessageNotReadableException400#L180-L192
ConstraintViolationException400#L197-L202
MaxUploadSizeExceededException400#L217-L220
NoHandlerFoundException404#L229-L233
HttpRequestMethodNotSupportedException405#L240-L244
HttpMediaTypeNotSupportedException400#L251-L255
AccessDeniedException403#L262-L267
ServiceException异常自带 code#L284-L302
其它 Exception500#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 按表前缀识别「模块未导入」并返回 501 NOT_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 注释)
XSSXssFilter(-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-L50yaml 里默认 false;excludeUrls 命中;或参数不是 JSON body
解密失败ApiEncryptFilter#L91-L111header 名不对、算法与密钥不匹配、请求方法不是 POST/PUT/DELETE
加密响应被截断ApiEncryptFilter#L114-L124包装器顺序错,或另一个过滤器提前写了响应
访问日志没有响应体ApiAccessLogFilter#L137-L140responseEnable 默认 false,需要在 @ApiAccessLog 上打开
前端拿不到 HTTP 401/403设计如此全部返回 200 + CommonResult.code;要 HTTP 码得自己加 @ResponseStatus
过滤器顺序不对WebFilterOrderEnum检查是否用 FilterRegistrationBean 设 order,而不是 @Order
静态资源被过滤器拦了ApiRequestFilter#L21-L25只有 /admin-api、/app-api 前缀才进业务过滤器
模块表存在但接口 501GlobalExceptionHandler#L378-L456表前缀对应的模块没引入,返回 NOT_IMPLEMENTED 是预期