Skip to content

数据访问与多租户基线 ​

一句话:默认数据模型是 BaseDO(审计 + 逻辑删除),需要租户隔离的表再继承 TenantBaseDO;SQL 由三个 MyBatis 拦截器重写,ID 走数据库自增/序列,不走雪花。

1. 数据模型约定 ​

text
BaseDO
├── createTime  LocalDateTime   INSERT
├── updateTime  LocalDateTime   INSERT_UPDATE
├── creator     String          INSERT
├── updater     String          INSERT_UPDATE
└── deleted     Boolean         @TableLogic
        ▲ extends
TenantBaseDO
└── tenantId    Long            租户编号
        ▲ extends
AdminUserDO(system_users)
字段类型填充说明
createTime / updateTimeLocalDateTimeINSERT / INSERT_UPDATE插入、更新时补时间
creator / updaterStringINSERT / INSERT_UPDATE当前登录用户 id 的字符串
deletedBoolean@TableLogic逻辑删除,1=删、0=未删

字段定义在 BaseDO.java#L24-L54,配套约定:

  • 业务 DO 继承 BaseDO;需要租户隔离的再继承 TenantBaseDO(TenantBaseDO.java#L14-L19)。
  • 审计字段由 DefaultDBFieldHandler 填充:只处理 BaseDO 子类,登录用户取自 SecurityFrameworkUtils.getLoginUserId()(DefaultDBFieldHandler.java#L22-L46)。没有登录上下文时 creator/updater 为空,不伪造“系统用户”。
  • 更新前调用 clean() 清空 creator/createTime/updater/updateTime,防止前端传审计字段覆盖真实值(BaseDO.java#L56-L64)。
  • 逻辑删除值在 application.yaml#L76-L77 固定为 1/0,查询自动追加 deleted = 0。
  • Mapper 继承 BaseMapperX,分页/排序走统一封装;排序字段必须过白名单,不能把前端字符串直接拼进 ORDER BY。

ID 策略 ​

application.yaml#L71-L72 配的是 id-type: NONE,由 IdTypeEnvironmentPostProcessor 在启动时按数据源类型自动适配(IdTypeEnvironmentPostProcessor.java#L36-L58、#L107-L117):

数据库自动选择实体要求
MySQL / MariaDB / TiDB / DM / SQL ServerAUTO数据库自增/IDENTITY,不需要 @KeySequence
PostgreSQL / Oracle / Kingbase / DB2 / H2INPUT实体标 @KeySequence("xxx_seq"),由数据库序列取号

判定集合在 IdTypeEnvironmentPostProcessor.java#L32-L33:ORACLE、ORACLE_12C、POSTGRE_SQL、KINGBASE_ES、DB2、H2;DM 不在集合里,走 AUTO(#L57-L58)。

本仓库不启用雪花 ID:全仓没有 IdType.ASSIGN_ID,DO 上大量保留 @KeySequence;application.yaml#L75 只是注释说明“可选 ASSIGN_ID 用雪花,但要移除 @KeySequence”,不是当前配置。强行改成 ASSIGN_ID 会让现有序列注解失效,属于偏离基线。

2. 多租户实现 ​

text
请求头 tenant-id
      │
      ▼
TenantContextWebFilter(order -104)
      │ 写入 TenantContextHolder(TransmittableThreadLocal)
      ▼
TenantSecurityWebFilter(order -99)
      │ 登录用户租户 vs 请求头租户;校验租户是否禁用/到期
      ▼
TenantLineInnerInterceptor
      │ 对 SELECT/UPDATE/DELETE 追加 tenant_id = ?
      │ 对 INSERT 补 tenant_id 列
      ▼
SQL 落到 system_users.tenant_id

TenantContextWebFilter 从请求头取租户,finally 清理(TenantContextWebFilter.java#L25-L34);TenantContextHolder 用两个 TTL 保存租户号与 ignore 标记,取不到租户时 getRequiredTenantId() 抛 NPE(TenantContextHolder.java#L16-L66);TenantSecurityWebFilter 校验请求头租户与登录用户租户一致、租户有效(TenantSecurityWebFilter.java#L67-L107);TenantDatabaseInterceptor 实现 TenantLineHandler,提供租户值和忽略表判断(TenantDatabaseInterceptor.java#L21-L81)。

哪些表会被拼 tenant_id ​

TenantDatabaseInterceptor.computeIgnoreTable 的判断顺序(#L68-L81)非常关键:

text
TableInfo 为空                  → true(忽略)
实体是 TenantBaseDO 子类        → false(不忽略,拼 tenant_id)
实体有 @TenantIgnore            → true(忽略)
其余(BaseDO 且无注解)          → false(也拼 tenant_id)

三条硬规则:

  1. 租户表:继承 TenantBaseDO,例如 AdminUserDO(AdminUserDO.java#L29),DDL 有 tenant_id(sql/mysql/pmforge.sql#L5021-L5041)。
  2. 全局表:继承 BaseDO 并加 @TenantIgnore,例如 MenuDO(MenuDO.java#L22-L23);system_menu 的 DDL 确实没有 tenant_id(pmforge.sql#L1877-L1898)。
  3. 陷阱:继承 BaseDO 但忘了 @TenantIgnore,拦截器仍会拼 tenant_id;表里没有该列就直接 SQL 报错。反过来,TenantBaseDO 子类即使加了 @TenantIgnore 也不会被忽略(判断顺序在注解之前)。

@TenantIgnore 支持方法/类型级别(TenantIgnore.java#L20-L23),enable 是 SpEL 字符串(#L30)。标在 Controller 方法上时,启动扫描会把对应 URL 加入忽略列表(PmforgeTenantAutoConfiguration.java#L135-L158);标在 DO 上时,表名参与忽略表判断。

忽略配置与缓存 ​

application.yaml#L312-L328 是租户总开关与忽略清单:

配置作用当前值
pmforge.tenant.enable是否装配整租户能力true
ignore-urls完全不经过租户过滤的 URL/jmreport/*
ignore-visit-urls不校验“请求头租户 vs 登录用户租户”的 URL用户资料、登录相关
ignore-tables额外忽略的表名空
ignore-caches不追加租户后缀的缓存名用户角色、菜单权限、OAuth2 客户端、邮件/短信模板等

Redis 缓存也做租户隔离:TenantRedisCacheManager 在缓存名后追加 :租户号,ignoreCaches 中的缓存不追加(TenantRedisCacheManager.java#L37-L44)。它改的是 cache name;实际 Redis key 还包含 Spring Cache 的 key 部分,排障时两者都要看。

跨租户操作必须显式切换:TenantUtils.execute(tenantId, ...) 临时切到指定租户并强制 setIgnore(false)(TenantUtils.java#L26-L38);TenantUtils.executeIgnore(...) 临时忽略租户过滤(#L71-L99)。异步线程、定时任务、MQ 消费都可能继承调用方的 TTL,不能依赖“线程里碰巧有值”。

3. 多数据源与读写分离 ​

text
DynamicDataSource(primary = master)
├── master:pmforge-jdk8(实际读写都走它)
├── slave :同库 URL,lazy=true(当前没有业务 @DS 指向它)
└── tdengine:仅 iot 模块用 @DS("tdengine")

配置在 application-local.yaml:spring.datasource.dynamic.primary: master(#L48);master 在 #L50-L69,slave 在 #L70-L74,lazy: true,URL 与 master 相同;数据源实现是 dynamic-datasource 4.5.0(pmforge-dependencies/pom.xml#L32)。

现状要讲清楚:主从配置存在,但代码里没有 @DS("slave") 或 @Slave 的业务使用;唯一显式切换是 iot 的 TDengineDS.java#L15 @DS("tdengine")。因此 slave 当前不承流,“读写分离”只是预留能力,不是已生效架构。

@DSTransactional 在 TenantServiceImpl、PermissionServiceImpl、TenantPackageServiceImpl 中出现(例如 TenantServiceImpl.java#L98),它解决的是多数据源本地事务一致性,不是数据源路由;方法上没有 @DS,就不会切库。DataSourceConfigServiceImpl 是后台“数据源配置”的 CRUD 与连接测试:id=0 返回 master 配置(#L77-L85),从 DynamicDataSourceProperties 构建配置(#L102-L108),用 JdbcUtils 测连接(#L95-L99),不是运行期路由开关。

要真正启用读写分离:只读方法标 @DS(DataSourceEnum.SLAVE)、把 slave 换成真实从库、写后立刻读强制走 master,并验证 @DSTransactional 的边界。

4. SQL 方言适配 ​

text
sql/
├── mysql/        pmforge.sql + quartz.sql
├── postgresql/   pmforge.sql + quartz.sql
├── oracle/       pmforge.sql + quartz.sql
├── sqlserver/    pmforge.sql + quartz.sql
├── dm/           pmforge-dm8.sql + quartz.sql + DM/Liquibase 适配类
├── kingbase/     pmforge.sql + quartz.sql
├── opengauss/    pmforge.sql + quartz.sql
├── highgo/       pmforge.sql + quartz.sql
├── db2/          (空目录,没有脚本)
└── tools/        convertor.py、docker-compose.yaml、建库辅助脚本

9 个方言目录,8 套可执行脚本。README 宣称支持 10 个数据库家族(README.md#L115),其中 MariaDB/TiDB 复用 MySQL 脚本;DB2 只在代码的 ID 策略里出现,没有建表脚本,不能算“已适配”。

方言主键写法类型/语法差异备注
MySQLbigint AUTO_INCREMENTdatetime、bit(1)、反引号默认脚本,48 张表
PostgreSQLbigint + CREATE SEQUENCEdual 表、COMMENT ONKingbase/OpenGauss/HighGo 同源
Oraclenumber + varchar2 + 序列ALTER TABLE ADD CONSTRAINT序列需与表一起建,无触发器
SQL Server / DM8bigint IDENTITYnvarchar / 大小写、布尔差异SQL Server 需先建 schema;DM 目录另有 DmDatabase、BooleanType 等 Liquibase 适配类

脚本规模(sql/mysql/pmforge.sql):5228 行、48 个 CREATE TABLE、3797 个 INSERT INTO、1068 处 tenant_id;quartz.sql 另有 11 张表。48 张 = system 32 + infra 16(其中 11 张 infra_* + 5 张 pmforge_demo*);docs/code/data/index.md 的 373 含全部模块实体(含 13 个预留模块),不是默认建表数。

5. 初始化与迁移顺序 ​

text
1. 建库:CREATE DATABASE pmforge
2. 导业务表:sql/mysql/pmforge.sql
3. 导调度表:sql/mysql/quartz.sql
4. 改配置:application-local.yaml 的数据源/Redis
5. 启动:pmforge-server
  • README 的四步是“建库 + 导 pmforge.sql + 改 application-local.yaml + 启动”(README.md#L35-L37),没提 quartz.sql;但 Quartz 配了 job-store-type: jdbc、initialize-schema: NEVER(application-local.yaml#L98、#L120),不导 quartz.sql,调度器初始化时会找不到 QRTZ_* 表。新库初始化必须补第 3 步。
  • 仓库没有引入 Flyway/Liquibase 版本化迁移(根/BOM/server pom 均无依赖);DM 目录里的 Liquibase 类只是方言适配,不是迁移框架。升级靠人工执行 sql/ 脚本,已发布的脚本不要回改,新增变更另起增量脚本。
  • 启用预留模块时,默认主脚本没有该模块的表;先合并 src/test/resources/sql/create_tables.sql 或补正式 DDL,再启动。菜单数据同理,见 模块化与自动配置。

6. 基线检查清单 ​

  • [ ] 新表有 creator/create_time/updater/update_time/deleted 五件套?
  • [ ] 租户表继承 TenantBaseDO,DDL 有 tenant_id?
  • [ ] 全局表继承 BaseDO 且加了 @TenantIgnore?
  • [ ] 需要序列的库,DO 上标了 @KeySequence?
  • [ ] 新库导了 pmforge.sql 和 quartz.sql?

相关页面:分层与依赖、模块化与自动配置、请求处理链路、租户卡片、数据源卡片。