Skip to content

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
TenantPropertiespmforge.tenant.*(5 个配置项)tenant/config/TenantProperties.java
TenantContextHolderTransmittableThreadLocal 保存 tenantId 与 ignore 标志tenant/core/context/TenantContextHolder.java
TenantBaseDO继承 BaseDO 并加 tenantId;实体是否继承它决定该表是否被加租户条件tenant/core/db/TenantBaseDO.java
TenantDatabaseInterceptorTenantLineHandler 实现:给 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 权限,设置 visitTenantIdtenant/core/web/TenantVisitContextInterceptor.java
TenantFrameworkService / ImplgetTenantIds()、validTenant(),Guava 缓存 1 分钟tenant/core/service/
TenantUtilsexecute(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: 结果} 的 JSONtenant/core/job/
TenantRedisMessageInterceptor / RabbitMQ / RocketMQ / Kafka 组件消息链路透传租户tenant/core/mq/
InvocableHandlerMethod复制到 org.springframework.messaging.handler.invocation 包,覆盖 Spring 同名类以在消费前读 headersrc/main/java/org/springframework/messaging/handler/invocation/InvocableHandlerMethod.java

3. 自动配置 ​

配置类 / 组件生效条件注册了什么
PmforgeTenantAutoConfigurationpmforge.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 / JobHandlerTenantRedisMessageInterceptor、TenantRabbitMQInitializer、TenantRocketMQInitializer、TenantJobAspect
TenantKafkaEnvironmentPostProcessorspring.factories 注册把 TenantKafkaProducerInterceptor 追加进 spring.kafka.producer.properties.interceptor.classes;无 Kafka 依赖时忽略 NoClassDefFoundError

TenantDatabaseInterceptor 判定某张表是否加租户条件的顺序:上下文 ignore → 表在忽略列表(含硬编码的 DUAL)→ MyBatis-Plus 里没有该表信息(非本项目表)→ 实体没继承 TenantBaseDO → 实体类上有 @TenantIgnore。

4. 配置项 ​

前缀键默认值说明
pmforge.tenantenabletrue总开关
pmforge.tenantignore-urls空免租户的 Open API(示例值 [/jmreport/*],积木报表无法带租户编号)
pmforge.tenantignore-visit-urls空不允许租户切换的接口(示例 [/admin-api/system/user/profile/**, /admin-api/system/auth/**])
pmforge.tenantignore-tables空不需要 tenant_id 的表;注释原话「默认所有表都开启多租户的功能,所以记得添加对应的 tenant_id 字段哟」
pmforge.tenantignore-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. 常见坑 ​

  1. 「默认所有表都开租户」是字面意思:任何 TableInfo 里存在、且实体没继承 TenantBaseDO 的表会被忽略,但继承了的表若没有 tenant_id 字段,SQL 会直接报错——新建表忘了加列,运行期才炸。
  2. DUAL 是硬编码忽略的:注释写明 Oracle 的 OracleKeyGenerator 生成主键会查 DUAL,拼上 TENANT_ID 会报错;换数据库时这段逻辑不会自动适配。
  3. @TenantJob 要求任务幂等:某租户失败触发 Quartz 重试时,前面已成功的租户会再执行一遍(类注释原话);且多租户共用一条执行日志,粒度是「整个 Job」而不是「每个租户」。
  4. TenantContextHolder.getRequiredTenantId() 抛的是 NullPointerException(不是 ServiceException),提示「TenantContextHolder 不存在租户编号!」,全局异常处理下就是 500——异步线程里忘了传租户时最容易遇到。
  5. 它直接覆盖了 Spring 的类:org.springframework.messaging.handler.invocation.InvocableHandlerMethod 是复制品,升级 Spring 版本时可能「悄悄」被官方版本替换,导致 RabbitMQ/Kafka 消费端丢租户(源码 TODO 也承认没有更好的扩展点)。
  6. 租户切换会连带放开权限校验:visitTenantId != tenantId 时 SecurityFrameworkServiceImpl.skipPermissionCheck() 返回 true,功能权限与数据权限一起失效。

7. 关联页面 ​