Skip to content

请求处理链路 ​

以创建用户为例:代码里的映射是 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_FILTERInteger.MIN_VALUE跨域,必须最早PmforgeWebAutoConfiguration.java#L108-L118
TRACE_FILTERMIN_VALUE + 1TraceId 写入 MDCPmforgeTracerAutoConfiguration.java#L53
REQUEST_BODY_CACHE_FILTERMIN_VALUE + 500缓存请求体,供重复读取PmforgeWebAutoConfiguration.java#L125-L126
API_ENCRYPT_FILTERMIN_VALUE + 501API 加解密PmforgeApiEncryptAutoConfiguration.java#L30
TENANT_CONTEXT_FILTER-104取租户号放入 TTLPmforgeTenantAutoConfiguration.java#L89-L95
API_ACCESS_LOG_FILTER-103访问日志,含 401/403PmforgeApiLogAutoConfiguration.java#L25-L30
XSS_FILTER-102XSS 清洗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 之前 ​

  1. CORS 最先,避免预检被鉴权拦掉;Trace 把 traceId 放进响应头/MDC。
  2. 缓存请求体:CacheRequestBodyFilter 把 InputStream 包成可重复读,否则访问日志读完 body,@RequestBody 就拿不到数据。
  3. 租户上下文:TenantContextWebFilter 从请求头取租户号,写入 TenantContextHolder 的 TTL,finally 清理(TenantContextWebFilter.java#L25-L34)。
  4. 访问日志: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):

  1. 从 header 或 parameter 取 token(#L44-L45);
  2. 调 OAuth2TokenCommonApi.checkAccessToken 校验(#L73);
  3. 校验 userType,构建 LoginUser(id、userType、info、tenantId、scopes、expiresTime,#L85-L88);
  4. 写入 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.allExceptionHandler401/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. 每层可插入的扩展点 ​

层扩展点推荐做法注意
FilterFilterRegistrationBean + WebFilterOrderEnum新增常量并在 createFilterBean 注册不要只给 Filter 类加 @Order,以 RegistrationBean 为准
Controller@RestController + CommonResult返回值显式包 CommonResultGlobalResponseBodyHandler 不自动包装
方法权限@PreAuthorize("@ss.hasPermission(...)")权限点与 system_menu 数据一致菜单不存在时严格模式会拒绝
Service@Transactional / @DSTransactional事务边界放在 Service同类自调用不走代理
MyBatisInnerInterceptor用 MyBatisUtils.addInterceptor 指定 index顺序变化会改变 SQL
访问日志@ApiAccessLog需要响应体时显式 responseEnable=true默认不记录响应体,避免泄漏

相关页面:分层与依赖、模块化与自动配置、数据访问与多租户基线、用户创建卡片。