主题
请求处理链路
以创建用户为例:代码里的映射是
POST /system/user/create,外部实际请求是POST /admin-api/system/user/create。前缀由WebMvcRegistrations按 controller 包统一添加,Controller 本身不写(PmforgeWebAutoConfiguration.java#L45-L81)。
1. 从 TCP 到 Controller
text
POST /admin-api/system/user/create
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Tomcat → Servlet Filter Chain(order 从小到大) │
│ CORS MIN_VALUE │
│ TRACE MIN_VALUE + 1 │
│ REQUEST_BODY_CACHE MIN_VALUE + 500 │
│ API_ENCRYPT MIN_VALUE + 501 │
│ TENANT_CONTEXT -104 │
│ API_ACCESS_LOG -103 │
│ XSS -102(默认关闭) │
│ Spring Security -100(框架默认) │
│ └─ TokenAuthenticationFilter │
│ TENANT_SECURITY -99 │
│ FLOWABLE -98(引入 Flowable 才注册) │
│ DEMO MAX_VALUE(pmforge.demo=true 才注册) │
└───────────────────────────┬──────────────────────────────────┘
▼
DispatcherServlet → HandlerMapping
(/admin-api 前缀 + /system/user/create)
▼
UserController#createUser顺序常量集中在 WebFilterOrderEnum.java#L12-L34:
| 常量 | 值 | 作用 | 注册处 |
|---|---|---|---|
CORS_FILTER | Integer.MIN_VALUE | 跨域,必须最早 | PmforgeWebAutoConfiguration.java#L108-L118 |
TRACE_FILTER | MIN_VALUE + 1 | TraceId 写入 MDC | PmforgeTracerAutoConfiguration.java#L53 |
REQUEST_BODY_CACHE_FILTER | MIN_VALUE + 500 | 缓存请求体,供重复读取 | PmforgeWebAutoConfiguration.java#L125-L126 |
API_ENCRYPT_FILTER | MIN_VALUE + 501 | API 加解密 | PmforgeApiEncryptAutoConfiguration.java#L30 |
TENANT_CONTEXT_FILTER | -104 | 取租户号放入 TTL | PmforgeTenantAutoConfiguration.java#L89-L95 |
API_ACCESS_LOG_FILTER | -103 | 访问日志,含 401/403 | PmforgeApiLogAutoConfiguration.java#L25-L30 |
XSS_FILTER | -102 | XSS 清洗 | PmforgeXssAutoConfiguration.java#L56-L59 |
TENANT_SECURITY_FILTER | -99 | 租户合法性/越权校验 | PmforgeTenantAutoConfiguration.java#L118-L128 |
两个容易看漏的点:访问日志在 Spring Security 之前(-103 < -100),所以 401/403 也能记录,且它要先读 body,故 CacheRequestBodyFilter 必须更早;XSS 在 application.yaml#L268 配成 false,PmforgeXssAutoConfiguration.java#L23 的 @ConditionalOnProperty 使过滤器不装配,链路保留位置但默认不执行。
2. 一次创建请求的时序
text
Client FilterChain Security Controller/Service MyBatis/DB
│ POST create │ │ │ │
├───────────────▶│ │ │ │
│ │ tenant -104 │ │ │
│ │ accesslog -103 │ │
│ │ xss -102(off)│ │ │
│ ├─────────────▶│ │ │
│ │ │ TokenFilter │ │
│ │ │ checkAccessToken │ │
│ │ │ set LoginUser │ │
│ │ ├─────────────────▶│ │
│ │ │ │ @PreAuthorize │
│ │ │ │ → @ss 权限判断 │
│ │ │◀─────────────────┤ │
│ │ │ PermissionCommonApi → 菜单/角色缓存 │
│ │ │ │ createUser(事务) │
│ │ │ │ 租户账号数/唯一性 │
│ │ │ ├──────────────────▶│
│ │ │ │ │ TenantLine
│ │ │ │ │ DataPermission
│ │ │ │ │ Pagination
│ │ │ │ │ INSERT system_users
│ │ │ │◀──────────────────┤
│ │ │ │ CommonResult(id) │
│ │◀─────────────┴──────────────────┤ │
│ │ GlobalResponseBodyHandler 只记录结果 │
│ │ finally:异步写访问日志 │
│◀──────────────┤ │ │ │3. 每一段发生了什么
3.1 进入 Spring Security 之前
- CORS 最先,避免预检被鉴权拦掉;Trace 把 traceId 放进响应头/MDC。
- 缓存请求体:
CacheRequestBodyFilter把InputStream包成可重复读,否则访问日志读完 body,@RequestBody就拿不到数据。 - 租户上下文:
TenantContextWebFilter从请求头取租户号,写入TenantContextHolder的 TTL,finally清理(TenantContextWebFilter.java#L25-L34)。 - 访问日志:
ApiAccessLogFilter先记开始时间、query、body;成功或异常最后都走createApiAccessLog(ApiAccessLogFilter.java#L66-L84)。
3.2 Spring Security 与 Token
PmforgeWebSecurityConfigurerAdapter.java#L109-L152 的过滤链:关 CSRF、STATELESS、关 frameOptions;注册 401/403 处理器;扫描 @PermitAll;其余 anyRequest().authenticated();把 TokenAuthenticationFilter 插到 UsernamePasswordAuthenticationFilter 之前(#L150-L151)。
TokenAuthenticationFilter 做四件事(TokenAuthenticationFilter.java#L42-L68):
- 从 header 或 parameter 取 token(
#L44-L45); - 调
OAuth2TokenCommonApi.checkAccessToken校验(#L73); - 校验 userType,构建
LoginUser(id、userType、info、tenantId、scopes、expiresTime,#L85-L88); - 写入
SecurityContextHolder(策略是TransmittableThreadLocal)。
校验失败时它不把异常抛给 MVC,而是直接调 GlobalExceptionHandler.allExceptionHandler(...) 并写 JSON(#L60-L63),因此 Filter 里的 401 也能返回统一 CommonResult。
3.3 Controller、@PreAuthorize 与 Service
UserController.java:#L43 @RequestMapping("/system/user")、#L52 @PostMapping("/create")、#L54 @PreAuthorize("@ss.hasPermission('system:user:create')")、#L55-L56 CommonResult<Long> createUser(@Valid @RequestBody UserSaveReqVO reqVO)。
@ss 是 PmforgeSecurityAutoConfiguration.java#L76-L79 注册的 SecurityFrameworkServiceImpl:
text
@PreAuthorize
→ SecurityFrameworkServiceImpl.hasPermission
→ PermissionCommonApi.hasAnyPermissions
→ PermissionServiceImpl:用户角色缓存 + 菜单权限缓存PermissionServiceImpl.java#L63-L111:先取用户角色(缓存),超管直接放行;普通用户按权限点查菜单 id,再查“菜单 → 角色”缓存;严格模式下菜单不存在即拒绝。
进入 AdminUserServiceImpl.java#L95-L122 后:@Transactional(rollbackFor=Exception.class) 开事务;@LogRecord 记操作日志(bizNo 取 #user.id 占位符);tenantService.handleTenantInfo 校验租户账号数(#L101-L106);唯一性校验放在 DataPermissionUtils.executeIgnore 内,避免数据权限干扰(#L405-L419);userMapper.insert(user) 后 userPostMapper.insertBatch(...),最后把 user 放进 LogRecordContext。
3.4 MyBatis 拦截器与落库
职责上可理解为三层 SQL 重写(实际顺序由注册顺序决定):
text
TenantLineInnerInterceptor → 拼 tenant_id = ?
DataPermissionInterceptor → 拼部门/用户数据范围
PaginationInnerInterceptor → 追加 LIMIT / COUNT- 租户拦截器通过
MyBatisUtils.addInterceptor(interceptor, inner, 0)插到索引 0(PmforgeTenantAutoConfiguration.java#L78-L84); - 数据权限拦截器同样插到索引 0(
PmforgeDataPermissionAutoConfiguration.java#L29-L39); - 分页拦截器由
PmforgeMybatisAutoConfiguration.java#L47-L54注册。
两者都插到 0,先后由自动配置顺序决定,业务上不要假设固定顺序;能确定的是它们都在分页之前,且 MyBatisUtils.buildPage 把 optimizeJoinOfCountSql 设为 false(MyBatisUtils.java#L45-L60),排序字段必须过白名单(#L35、#L108-L114)。
落库前,DefaultDBFieldHandler.insertFill 只处理 BaseDO 子类:补 createTime/updateTime,并从 SecurityFrameworkUtils.getLoginUserId() 补 creator/updater(DefaultDBFieldHandler.java#L22-L46)。ID 由启动时的 IdTypeEnvironmentPostProcessor 决定:MySQL 走 AUTO_INCREMENT,PG/Oracle 等走 INPUT + @KeySequence;本链路不生成雪花 id。
3.5 返回与异常
Controller 显式返回 CommonResult.success(id)。GlobalResponseBodyHandler 只对返回类型恰好是 CommonResult 的方法生效(GlobalResponseBodyHandler.java#L28-L34),只把结果塞进 request attribute 供访问日志读取(#L38-L42),不做自动包装。
| 异常发生位置 | 处理者 | 结果 |
|---|---|---|
| Filter(Token 校验等) | TokenAuthenticationFilter 手动调 GlobalExceptionHandler.allExceptionHandler | 401/403 JSON |
| Controller/Service | @RestControllerAdvice(GlobalExceptionHandler.java#L57) | 400/403/500 统一 CommonResult |
| 表不存在(模块没启用) | handleTableNotExists(#L378 起) | NOT_IMPLEMENTED + 提示检查 pom |
ServiceException 保留业务错误码;未知异常记 error 日志并异步写 infra_api_error_log(#L316-L338)。
3.6 访问日志异步落库
ApiAccessLogFilter 在 finally 里构建日志(#L86-L94),调用接口上的 @Async default 方法 createApiAccessLogAsync(ApiAccessLogCommonApi.java#L27-L30),实现类委托给 ApiAccessLogServiceImpl:#L41 插入 infra_api_access_log;#L40-L45 若上下文没有租户号,用 TenantUtils.executeIgnore(...) 兜底,避免插入失败。
异步真正生效依赖 starter-job 的 PmforgeAsyncAutoConfiguration(#L15-L17 @EnableAsync)。访问日志是旁路,写入失败不影响主请求返回。
4. 每层可插入的扩展点
| 层 | 扩展点 | 推荐做法 | 注意 |
|---|---|---|---|
| Filter | FilterRegistrationBean + WebFilterOrderEnum | 新增常量并在 createFilterBean 注册 | 不要只给 Filter 类加 @Order,以 RegistrationBean 为准 |
| Controller | @RestController + CommonResult | 返回值显式包 CommonResult | GlobalResponseBodyHandler 不自动包装 |
| 方法权限 | @PreAuthorize("@ss.hasPermission(...)") | 权限点与 system_menu 数据一致 | 菜单不存在时严格模式会拒绝 |
| Service | @Transactional / @DSTransactional | 事务边界放在 Service | 同类自调用不走代理 |
| MyBatis | InnerInterceptor | 用 MyBatisUtils.addInterceptor 指定 index | 顺序变化会改变 SQL |
| 访问日志 | @ApiAccessLog | 需要响应体时显式 responseEnable=true | 默认不记录响应体,避免泄漏 |
相关页面:分层与依赖、模块化与自动配置、数据访问与多租户基线、用户创建卡片。