Skip to content

横切机制 ​

一句话:平台把「租户、数据权限、功能权限、过滤器与响应、数据访问、消息、调度、代码生成」八件事做成 注解 + 拦截器/切面 + 自动配置 三件套,业务代码只加一个注解或继承一个基类;本目录逐条拆开它们的链路、顺序与坑。

适用场景:需要改一处、影响所有请求/所有 SQL 的机制(登录态、租户隔离、行级权限、日志、消息投递、任务调度),或排查"查询少了数据""消息丢了""任务跑了两次"这类跨层问题。

不适用场景:单表增删改查的业务细节(看 功能卡)、接口路径与权限点清单(看 /code/api/system)、模块划分(看 /code/architecture/)。

1. 机制清单 ​

机制一句话关键类页面
多租户租户号放 TTL,入口 Filter 建立并校验,SQL/缓存/MQ/Job/WebSocket 各自透传TenantContextHolder、TenantDatabaseInterceptor、TenantRedisCacheManager多租户
数据权限@DataPermission 触发 AOP,把部门/本人条件拼进 SQL 的 WHEREDataPermissionInterceptor、DataPermissionRuleHandler、DeptDataPermissionRule数据权限
鉴权与权限点@PreAuthorize("@ss.hasPermission(...)") → PermissionCommonApi → 角色/菜单缓存SecurityFrameworkServiceImpl、PermissionServiceImpl鉴权与权限点
Web 过滤器与统一响应一条 Filter 链定顺序,异常统一转 CommonResult,HTTP 恒 200WebFilterOrderEnum、GlobalExceptionHandler、GlobalResponseBodyHandlerWeb过滤器与统一响应
数据访问约定BaseDO 管审计字段、BaseMapperX 管分页/join/批量、插件管租户/权限/分页BaseDO、BaseMapperX、MyBatisUtils数据访问约定
消息与实时推送Redis Pub/Sub 与 Stream 两套模型,WebSocket 五套 sender 按配置切换RedisMQTemplate、AbstractRedisChannelMessageListener、WebSocketMessageSender消息与实时推送
定时任务与异步JobHandler 交给 Quartz,JobHandlerInvoker 统一落日志与重试,@TenantJob 按租户循环SchedulerManager、JobHandlerInvoker、TenantJobAspect定时任务与异步
代码生成闭环导表 → 补默认值 → Velocity 渲染 → 预览/下载 zipCodegenBuilder、CodegenEngine、CodegenServiceImpl代码生成闭环

2. 三条公共约定 ​

所有机制都长成同一个形状,认出形状就能猜到落点:

  1. 注解 + 拦截器/切面 + 自动配置。注解只声明意图(@TenantIgnore、@DataPermission、@TenantJob),真正干活的是拦截器/切面;自动配置负责在满足条件时把它们装进容器,业务模块不写装配代码。
  2. 顺序敏感项集中定义。Web 端顺序集中在 WebFilterOrderEnum(CORS -> 租户上下文 -> 访问日志 -> XSS -> Spring Security -> 租户校验,见 pmforge-common/.../enums/WebFilterOrderEnum.java#L12-L34);MyBatis 端靠 MyBatisUtils.addInterceptor 的插入位置(inner、0)保证租户、数据权限排在分页之前。
  3. 跳过用注解,不改全局。@TenantIgnore、@DataPermission(enable = false)、@ApiAccessLog(enable = false) 都是一次性的;改全局配置会让所有租户、所有请求一起变,回归面不可控。

3. 机制页的写法 ​

本目录的 8 篇按同一结构组织,读的时候可以跳着看:

小节回答的问题
一句话总结 + 适用/不适用这个机制解决什么,什么时候不要用它
链路拆解从注解/入口到最终生效,经过哪几个类,类与类的边界在哪
顺序与位置为什么排在这一位,挪动会坏什么
新增/扩展按步骤加一条规则、一种消息、一套模板
常见坑线上真实会踩的坑,每条给排查手段
排错清单症状 → 先看哪个类的哪一行

写作规范(见 docs/_meta/规范-内容与ID.md):代码不整段粘贴,只给「类名 + 仓库相对路径#行号」;所有关于行为的话必须能在 code: 里找到落点;机制页正文控制在 90–180 行,超了就拆页。

4. 一次请求里,机制按什么顺序生效 ​

理解顺序比记住类名更有用。以 POST /admin-api/system/user/create 为例:

阶段生效的机制落点
1. 进 Servlet 容器CORS → 请求体缓存 → 解密WebFilterOrderEnum#L12-L18
2. 建立上下文租户上下文(-104)→ 访问日志(-103)→ XSS(-102)见Web过滤器与统一响应
3. 认证TokenAuthenticationFilter 解析 token,写 LoginUser见鉴权与权限点
4. 租户校验请求租户 = 登录租户;非忽略 URL 校验租户存在见多租户
5. 方法鉴权@PreAuthorize("@ss.hasPermission(...)")见鉴权与权限点
6. Service 调用@DataPermission 压栈;@Transactional 开事务见数据权限
7. 访问数据库租户插件 → 数据权限插件 → 分页插件见数据访问约定
8. 副作用事务提交后清缓存;发 MQ;写任务日志见多租户、消息与实时推送
9. 出响应GlobalResponseBodyHandler 记录 → 访问日志落库见Web过滤器与统一响应

两个容易记反的点:

  • 日志在认证之前(-103 < -100),所以访问日志里的用户来自 request attribute,而不是 SecurityContextHolder;
  • 缓存清理在事务之后(setTransactionAware(true)),所以在事务内发了 MQ、消费方立刻查库,可能读不到还没提交的数据。

5. 相关页面 ​

6. 排错清单(按症状找机制) ​

症状先看
查出来的数据少了 / 多了数据权限 的 DataPermissionRuleHandler#L31-L62;再确认是否跨租户
接口 401 / 403,但前端说已登录鉴权与权限点;401 看 AuthenticationEntryPointImpl,403 看 AccessDeniedHandlerImpl 与 TenantSecurityWebFilter
新接口不生效、路径 404Web过滤器与统一响应 的 /admin-api、/app-api 前缀
MQ 消费端拿不到租户 / 广播串租户消息与实时推送 的「租户透传」与 WebSocketSessionManagerImpl#L92-L113
定时任务重复执行、日志缺失定时任务与异步 的并发与重试两节
生成的代码缺文件、路径不对代码生成闭环 的 CodegenEngine#L578-L601 过滤逻辑