主题
横切机制
一句话:平台把「租户、数据权限、功能权限、过滤器与响应、数据访问、消息、调度、代码生成」八件事做成 注解 + 拦截器/切面 + 自动配置 三件套,业务代码只加一个注解或继承一个基类;本目录逐条拆开它们的链路、顺序与坑。
适用场景:需要改一处、影响所有请求/所有 SQL 的机制(登录态、租户隔离、行级权限、日志、消息投递、任务调度),或排查"查询少了数据""消息丢了""任务跑了两次"这类跨层问题。
不适用场景:单表增删改查的业务细节(看 功能卡)、接口路径与权限点清单(看 /code/api/system)、模块划分(看 /code/architecture/)。
1. 机制清单
| 机制 | 一句话 | 关键类 | 页面 |
|---|---|---|---|
| 多租户 | 租户号放 TTL,入口 Filter 建立并校验,SQL/缓存/MQ/Job/WebSocket 各自透传 | TenantContextHolder、TenantDatabaseInterceptor、TenantRedisCacheManager | 多租户 |
| 数据权限 | @DataPermission 触发 AOP,把部门/本人条件拼进 SQL 的 WHERE | DataPermissionInterceptor、DataPermissionRuleHandler、DeptDataPermissionRule | 数据权限 |
| 鉴权与权限点 | @PreAuthorize("@ss.hasPermission(...)") → PermissionCommonApi → 角色/菜单缓存 | SecurityFrameworkServiceImpl、PermissionServiceImpl | 鉴权与权限点 |
| Web 过滤器与统一响应 | 一条 Filter 链定顺序,异常统一转 CommonResult,HTTP 恒 200 | WebFilterOrderEnum、GlobalExceptionHandler、GlobalResponseBodyHandler | Web过滤器与统一响应 |
| 数据访问约定 | BaseDO 管审计字段、BaseMapperX 管分页/join/批量、插件管租户/权限/分页 | BaseDO、BaseMapperX、MyBatisUtils | 数据访问约定 |
| 消息与实时推送 | Redis Pub/Sub 与 Stream 两套模型,WebSocket 五套 sender 按配置切换 | RedisMQTemplate、AbstractRedisChannelMessageListener、WebSocketMessageSender | 消息与实时推送 |
| 定时任务与异步 | JobHandler 交给 Quartz,JobHandlerInvoker 统一落日志与重试,@TenantJob 按租户循环 | SchedulerManager、JobHandlerInvoker、TenantJobAspect | 定时任务与异步 |
| 代码生成闭环 | 导表 → 补默认值 → Velocity 渲染 → 预览/下载 zip | CodegenBuilder、CodegenEngine、CodegenServiceImpl | 代码生成闭环 |
2. 三条公共约定
所有机制都长成同一个形状,认出形状就能猜到落点:
- 注解 + 拦截器/切面 + 自动配置。注解只声明意图(
@TenantIgnore、@DataPermission、@TenantJob),真正干活的是拦截器/切面;自动配置负责在满足条件时把它们装进容器,业务模块不写装配代码。 - 顺序敏感项集中定义。Web 端顺序集中在
WebFilterOrderEnum(CORS -> 租户上下文 -> 访问日志 -> XSS -> Spring Security -> 租户校验,见pmforge-common/.../enums/WebFilterOrderEnum.java#L12-L34);MyBatis 端靠MyBatisUtils.addInterceptor的插入位置(inner、0)保证租户、数据权限排在分页之前。 - 跳过用注解,不改全局。
@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. 相关页面
- 框架组件与配置前缀:框架组件(15 个 Starter)
- 请求整体链路:代码层地图 与 /code/architecture/
- 租户管理功能卡:SYS-TENANT-01、SYS-TENANT-02
- 权限功能卡:SYS-PERM-01、SYS-ROLE-01
- 生成物(勿手改):/code/api/system、/code/data/system、配置项速查
6. 排错清单(按症状找机制)
| 症状 | 先看 |
|---|---|
| 查出来的数据少了 / 多了 | 数据权限 的 DataPermissionRuleHandler#L31-L62;再确认是否跨租户 |
| 接口 401 / 403,但前端说已登录 | 鉴权与权限点;401 看 AuthenticationEntryPointImpl,403 看 AccessDeniedHandlerImpl 与 TenantSecurityWebFilter |
| 新接口不生效、路径 404 | Web过滤器与统一响应 的 /admin-api、/app-api 前缀 |
| MQ 消费端拿不到租户 / 广播串租户 | 消息与实时推送 的「租户透传」与 WebSocketSessionManagerImpl#L92-L113 |
| 定时任务重复执行、日志缺失 | 定时任务与异步 的并发与重试两节 |
| 生成的代码缺文件、路径不对 | 代码生成闭环 的 CodegenEngine#L578-L601 过滤逻辑 |