主题
数据访问与多租户基线
一句话:默认数据模型是
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 / updateTime | LocalDateTime | INSERT / INSERT_UPDATE | 插入、更新时补时间 |
creator / updater | String | INSERT / INSERT_UPDATE | 当前登录用户 id 的字符串 |
deleted | Boolean | @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 Server | AUTO | 数据库自增/IDENTITY,不需要 @KeySequence |
| PostgreSQL / Oracle / Kingbase / DB2 / H2 | INPUT | 实体标 @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_idTenantContextWebFilter 从请求头取租户,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)三条硬规则:
- 租户表:继承
TenantBaseDO,例如AdminUserDO(AdminUserDO.java#L29),DDL 有tenant_id(sql/mysql/pmforge.sql#L5021-L5041)。 - 全局表:继承
BaseDO并加@TenantIgnore,例如MenuDO(MenuDO.java#L22-L23);system_menu的 DDL 确实没有tenant_id(pmforge.sql#L1877-L1898)。 - 陷阱:继承
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 策略里出现,没有建表脚本,不能算“已适配”。
| 方言 | 主键写法 | 类型/语法差异 | 备注 |
|---|---|---|---|
| MySQL | bigint AUTO_INCREMENT | datetime、bit(1)、反引号 | 默认脚本,48 张表 |
| PostgreSQL | bigint + CREATE SEQUENCE | dual 表、COMMENT ON | Kingbase/OpenGauss/HighGo 同源 |
| Oracle | number + varchar2 + 序列 | ALTER TABLE ADD CONSTRAINT | 序列需与表一起建,无触发器 |
| SQL Server / DM8 | bigint IDENTITY | nvarchar / 大小写、布尔差异 | 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?