主题
starter-biz-tenant
1. 职责
让「一套代码、多套租户数据」只靠一个请求头 tenant-id 就自动成立:Web 层解析并校验租户 → 放进 TenantContextHolder → MyBatis 拦截器给每条 SQL 自动补 tenant_id = ? 条件。
它把租户穿透做进了所有「跳出请求线程」的地方:Redis 缓存 key 追加租户、消息 header 带租户、@TenantJob 按租户循环执行、RabbitMQ/RocketMQ/Kafka 的生产与消费都补租户。
它不解决:租户的增删改查与套餐、租户与用户/角色的绑定(在 pmforge-module-system)、物理隔离(同一个库,靠列隔离)。
本节路径均省略公共前缀
framework/pmforge-spring-boot-starter-biz-tenant/src/main/java/com/pmforge/framework/。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
PmforgeTenantAutoConfiguration | 总装配:拦截器、Filter、缓存管理器、4 组 MQ 增强 | tenant/config/PmforgeTenantAutoConfiguration.java |
TenantProperties | pmforge.tenant.*(5 个配置项) | tenant/config/TenantProperties.java |
TenantContextHolder | TransmittableThreadLocal 保存 tenantId 与 ignore 标志 | tenant/core/context/TenantContextHolder.java |
TenantBaseDO | 继承 BaseDO 并加 tenantId;实体是否继承它决定该表是否被加租户条件 | tenant/core/db/TenantBaseDO.java |
TenantDatabaseInterceptor | TenantLineHandler 实现:给 SQL 加 tenant_id,并判定哪些表忽略 | tenant/core/db/TenantDatabaseInterceptor.java |
TenantSecurityWebFilter | 校验请求租户:缺失 400、越权 403、非法租户交全局异常处理 | tenant/core/security/TenantSecurityWebFilter.java |
TenantContextWebFilter | 从 tenant-id 请求头写入上下文 | tenant/core/web/TenantContextWebFilter.java |
TenantVisitContextInterceptor | 租户切换:校验 system:tenant:visit 权限,设置 visitTenantId | tenant/core/web/TenantVisitContextInterceptor.java |
TenantFrameworkService / Impl | getTenantIds()、validTenant(),Guava 缓存 1 分钟 | tenant/core/service/ |
TenantUtils | execute(tenantId, runnable)、executeIgnore(...)、addTenantHeader(...) | tenant/core/util/TenantUtils.java |
TenantRedisCacheManager | 继承 TimeoutRedisCacheManager,缓存名追加 :租户ID(#ttl 仍生效) | tenant/core/redis/TenantRedisCacheManager.java |
TenantIgnore / TenantIgnoreAspect | 注解 + 切面:按 SpEL 条件临时 setIgnore(true) | tenant/core/aop/ |
TenantJob / TenantJobAspect | 定时任务按租户并行执行,返回 {tenantId: 结果} 的 JSON | tenant/core/job/ |
TenantRedisMessageInterceptor / RabbitMQ / RocketMQ / Kafka 组件 | 消息链路透传租户 | tenant/core/mq/ |
InvocableHandlerMethod | 复制到 org.springframework.messaging.handler.invocation 包,覆盖 Spring 同名类以在消费前读 header | src/main/java/org/springframework/messaging/handler/invocation/InvocableHandlerMethod.java |
3. 自动配置
| 配置类 / 组件 | 生效条件 | 注册了什么 |
|---|---|---|
PmforgeTenantAutoConfiguration | pmforge.tenant.enable=true(缺省 true) | 下列 1~6 全部 |
| ① 租户服务 | 始终 | TenantFrameworkService(Guava 缓存租户列表与校验结果各 1 分钟) |
| ② MyBatis | 始终 | TenantLineInnerInterceptor(new TenantDatabaseInterceptor(properties)),用 MyBatisUtils.addInterceptor(interceptor, inner, 0) 放在第 0 位(必须在分页之前) |
| ③ Web Filter | 始终 | TenantContextWebFilter(order TENANT_CONTEXT_FILTER);TenantSecurityWebFilter(order TENANT_SECURITY_FILTER);TenantVisitContextInterceptor + WebMvcConfigurer(排除 ignore-visit-urls) |
| ④ 缓存 | 始终 | @Primary RedisCacheManager = TenantRedisCacheManager(setTransactionAware(true)) |
| ⑤ AOP | 始终 | TenantIgnoreAspect |
⑥ MQ 增强(内部 @Configuration) | 分别 @ConditionalOnClass Redis 拦截器 / RabbitTemplate / RocketMQTemplate / JobHandler | TenantRedisMessageInterceptor、TenantRabbitMQInitializer、TenantRocketMQInitializer、TenantJobAspect |
TenantKafkaEnvironmentPostProcessor | spring.factories 注册 | 把 TenantKafkaProducerInterceptor 追加进 spring.kafka.producer.properties.interceptor.classes;无 Kafka 依赖时忽略 NoClassDefFoundError |
TenantDatabaseInterceptor 判定某张表是否加租户条件的顺序:上下文 ignore → 表在忽略列表(含硬编码的 DUAL)→ MyBatis-Plus 里没有该表信息(非本项目表)→ 实体没继承 TenantBaseDO → 实体类上有 @TenantIgnore。
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
pmforge.tenant | enable | true | 总开关 |
pmforge.tenant | ignore-urls | 空 | 免租户的 Open API(示例值 [/jmreport/*],积木报表无法带租户编号) |
pmforge.tenant | ignore-visit-urls | 空 | 不允许租户切换的接口(示例 [/admin-api/system/user/profile/**, /admin-api/system/auth/**]) |
pmforge.tenant | ignore-tables | 空 | 不需要 tenant_id 的表;注释原话「默认所有表都开启多租户的功能,所以记得添加对应的 tenant_id 字段哟」 |
pmforge.tenant | ignore-caches | 空 | 不追加租户后缀的缓存名(示例含 user_role_ids、oauth_client、iot:device 等) |
5. 扩展点
- 新表要租户隔离:DO
extends TenantBaseDO并在表上加tenant_id;不想隔离就extends BaseDO或把表名写进ignore-tables。 - 单个方法忽略租户:方法/类上标
@TenantIgnore(支持enable = "#flag"SpEL 条件),框架扫描它会同时把 URL 加进免租户列表。 - 手工切租户:
TenantUtils.execute(tenantId, () -> ...);只忽略不切用的是executeIgnore。 - 租户切换:前端带
visit-tenant-id头,需要system:tenant:visit权限;TenantVisitContextInterceptor会在afterCompletion还原。 - 消息带租户:Redis 用拦截器自动带;RabbitMQ/RocketMQ 用对应的
Initializer注册 hook;Kafka 通过TenantKafkaEnvironmentPostProcessor注入 producer 拦截器。 - 自定义缓存租户化:
TenantRedisCacheManager已覆盖@Primary,业务不要再建RedisCacheManager。
6. 常见坑
- 「默认所有表都开租户」是字面意思:任何
TableInfo里存在、且实体没继承TenantBaseDO的表会被忽略,但继承了的表若没有tenant_id字段,SQL 会直接报错——新建表忘了加列,运行期才炸。 DUAL是硬编码忽略的:注释写明 Oracle 的OracleKeyGenerator生成主键会查DUAL,拼上TENANT_ID会报错;换数据库时这段逻辑不会自动适配。@TenantJob要求任务幂等:某租户失败触发 Quartz 重试时,前面已成功的租户会再执行一遍(类注释原话);且多租户共用一条执行日志,粒度是「整个 Job」而不是「每个租户」。TenantContextHolder.getRequiredTenantId()抛的是NullPointerException(不是ServiceException),提示「TenantContextHolder 不存在租户编号!」,全局异常处理下就是 500——异步线程里忘了传租户时最容易遇到。- 它直接覆盖了 Spring 的类:
org.springframework.messaging.handler.invocation.InvocableHandlerMethod是复制品,升级 Spring 版本时可能「悄悄」被官方版本替换,导致 RabbitMQ/Kafka 消费端丢租户(源码 TODO 也承认没有更好的扩展点)。 - 租户切换会连带放开权限校验:
visitTenantId != tenantId时SecurityFrameworkServiceImpl.skipPermissionCheck()返回 true,功能权限与数据权限一起失效。
7. 关联页面
- starter-mybatis:第 0 位的拦截器顺序
- starter-security:
LoginUser.tenantId与visitTenantId - starter-redis:被覆盖的
RedisCacheManager - starter-job:
@TenantJob的执行载体 - starter-mq:租户 header 的发送与恢复
- 横切机制、租户管理、/modules/system/