主题
数据访问约定
一句话:所有 DO 继承
BaseDO(需要租户隔离就继承TenantBaseDO),所有 Mapper 继承BaseMapperX,分页/排序/逻辑删除/审计字段全部由基类和插件统一处理,业务代码只写「查询条件」。
适用场景:新建一张表要写 DO/Mapper;给列表接口加分页、排序、关键字模糊查询;判断某个字段该不该手写 SQL。
不适用场景:多表复杂报表 SQL(可以写 XML,但仍建议套 BaseMapperX 的返回类型);缓存策略(看消息与实时推送 里的 Redis 部分)。
1. BaseDO:四个审计字段 + 一个逻辑删除
core/dataobject/BaseDO.java(#L24)是抽象类,实现了 Serializable 与 easy-trans 的 TransPojo:
| 字段 | 注解 | 行 | 行为 |
|---|---|---|---|
createTime | @TableField(fill = INSERT) | #L29-L30 | 插入时由 DefaultDBFieldHandler 填当前时间 |
updateTime | @TableField(fill = INSERT_UPDATE) | #L34-L35 | 插入与更新都刷新 |
creator | @TableField(fill = INSERT) | #L41-L42 | 取 SecurityFrameworkUtils.getLoginUserId() |
updater | @TableField(fill = INSERT_UPDATE) | #L48-L49 | 同上,更新时刷新 |
deleted | @TableLogic | #L53-L54 | 逻辑删除:delete 变 UPDATE deleted=1,查询自动追加 deleted=0 |
clean()(#L59-L64)把审计字段与 deleted 清空,用于「复制一条记录」或测试断言。
填充逻辑在 core/handler/DefaultDBFieldHandler.java:insertFill(#L22-L46)先填时间,再填 creator/updater,且只在为空时填(#L38-L44),所以导入历史数据可以显式指定创建人;updateFill(#L49-L62)只刷新 updateTime 与 updater。取不到登录用户(定时任务、匿名接口)时不会报错,字段留空。
需要租户隔离的表继承 TenantBaseDO(core/db/TenantBaseDO.java#L14),它只多一个 tenantId(#L19),由 TenantLineInnerInterceptor 自动补 tenant_id。判断依据见 TenantDatabaseInterceptor#L68-L81:继承 TenantBaseDO 的表一定会拼租户条件,即使没在配置里登记。
2. BaseMapperX:分页、Join、批量
core/mapper/BaseMapperX.java 是 MPJBaseMapper<T> 的扩展(#L32),提供 default 方法,业务 Mapper 直接继承即可:
| 方法 | 行 | 说明 |
|---|---|---|
selectPage(SortablePageParam, Wrapper) | #L34-L36 | 用参数里自带的排序字段 |
selectPage(PageParam, Wrapper) | #L38-L40 | 无排序 |
selectPage(PageParam, Collection<SortingField>, Wrapper) | #L42-L55 | 核心实现:PAGE_SIZE_NONE 时不分页(#L44-L48),否则 MyBatisUtils.buildPage 后查(#L51-L54) |
selectJoinPage(...) | #L57-L99 | 三个重载,底层是 MyBatis-Plus-Join,返回 PageResult<DTO> |
selectOne(field, value) | #L101 起 | 单条件查询,字段可以是字符串或 SFunction |
selectOneForUpdate | #L130-L145 | SELECT ... FOR UPDATE,必须在事务里调用 |
selectFirstOne / selectLastOne | #L156-L181 | 按某列排序取第一条 / 最后一条 |
selectCount | #L185-L195 | 返回 Long,不是 int |
selectList | #L197-L229 | 条件列表,支持排序 |
insertBatch | #L232-L256 | 默认走 Db.saveBatch;SQL Server 分支逐条插(#L235-L238) |
updateBatch / delete / deleteBatch | #L258-L283 | 批量更新 / 按 Wrapper 删 / 按 ID 集合删 |
统一返回 PageResult<T>,不是 MP 的 IPage。这意味着 Controller 层不需要转格式,前端拿到的固定是 { list, total }。
3. MyBatisUtils:分页与排序白名单
core/util/MyBatisUtils.java 解决两个坑:
分页:buildPage(PageParam, Collection<SortingField>)(#L41-L60)创建 MP Page,并显式 setOptimizeJoinOfCountSql(false)(#L48)——关闭 count SQL 的 join 优化,避免它把必要的 join 表删掉导致 total 不对。
排序注入:排序字段来自请求参数,是典型的 SQL 注入面。addOrder(#L62-L98)与 buildSafeOrderColumn(#L108-L114)做两件事:驼峰转下划线,再用 SAFE_COLUMN_NAME_PATTERN(#L35,^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*$)校验;不合法的字段直接返回 null 跳过,不抛异常。所以前端传 orderBy=id;drop 不会报错,只是排序不生效——排错时要意识到这一点。
另一个容易忽略的方法:addInterceptor(MybatisPlusInterceptor, InnerInterceptor, index)(#L124-L128)。它复制原有 interceptors 列表再 add(index, ...) 后整体 setInterceptors,因为 MyBatis-Plus 不支持增量添加插件;这也是租户/数据权限插件都用它插入索引 0 的原因。
findInSet(#L167-L197)用来查「多值字段里包含某个值」,列名同样走白名单(#L188-L190),配合 JSON 数组类型处理器使用。
4. 插件顺序:租户 0、数据权限 0、分页最后
PmforgeMybatisAutoConfiguration#L47-L54 只注册分页插件(#L50);租户与数据权限各自在 starter 里用 addInterceptor(..., 0) 插到最前(PmforgeTenantAutoConfiguration#L77-L85、PmforgeDataPermissionAutoConfiguration#L30-L39)。
| 顺序 | 插件 | 谁注册 | 作用 |
|---|---|---|---|
| 0(动态) | TenantLineInnerInterceptor | 租户 starter | 给 TenantBaseDO 表补 tenant_id |
| 0(动态) | DataPermissionInterceptor | 数据权限 starter | 按规则补 dept_id IN (...) |
| 最后 | PaginationInnerInterceptor | mybatis starter | 生成 limit 与 count |
约束只有一条:分页必须最后。租户与数据权限谁先谁后不影响语义(都是 AND),但新增第三方插件时不要假设它们的前后关系,用 addInterceptor 显式指定索引。
5. 多数据源与类型处理器
- 数据源名是常量:
DataSourceEnum.MASTER = "master"、SLAVE = "slave"(datasource/core/enums/DataSourceEnum.java#L16、#L20)。方法上@DS(DataSourceEnum.SLAVE)切库,默认主库。 - 跨库事务不能用
@Transactional(只认一个 DataSource),要用@DSTransactional;现成例子:PermissionServiceImpl#L134的assignRoleMenu。 PmforgeDataSourceAutoConfiguration装配 Druid + 动态数据源;DruidAdRemoveFilter去掉监控页广告。- 类型处理器在
core/type/:EncryptTypeHandler(AES 加解密,密码取mybatis-plus.encryptor.password,见#L23)、LongListTypeHandler、LongSetTypeHandler、IntegerListTypeHandler、StringListTypeHandler。用法是字段上加@TableField(typeHandler = LongListTypeHandler.class),数据库里存 JSON 字符串;配合findInSet可以按元素过滤(AiChatMessageDO#L111、BpmProcessDefinitionInfoDO#L151都是这个套路)。
6. 写一条新查询:推荐写法
java
// 1) DO:租户表继承 TenantBaseDO,非租户表继承 BaseDO
public class ProjectDO extends TenantBaseDO {
private String name;
private Integer status;
}
// 2) Mapper:继承 BaseMapperX,条件用 LambdaQueryWrapperX
@Mapper
public interface ProjectMapper extends BaseMapperX<ProjectDO> {
default PageResult<ProjectDO> selectPage(ProjectPageReqVO reqVO) {
return selectPage(reqVO, new LambdaQueryWrapperX<ProjectDO>()
.likeIfPresent(ProjectDO::getName, reqVO.getName())
.eqIfPresent(ProjectDO::getStatus, reqVO.getStatus())
.betweenIfPresent(ProjectDO::getCreateTime, reqVO.getCreateTime())
.orderByDesc(ProjectDO::getId));
}
}要点:
- 别自己 new Page,走
selectPage,排序白名单与 count 优化都已处理; - 条件用
xxxIfPresent(LambdaQueryWrapperX#L21-L104),参数为空自动跳过,避免WHERE name LIKE '%%'这类全表条件; - 联表用
selectJoinPage,不要手写 XML 再自己拼分页; - 必须带租户/数据权限的表,不要加
@TenantIgnore绕过,先确认是否真需要跨租户; - 更新/删除前先
selectById校验归属,不要直接updateById一个前端传来的 ID(越权改数据)。
7. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
create_time 为空 | DefaultDBFieldHandler#L22-L46 | DO 没继承 BaseDO,或字段名与注解不匹配 |
| 逻辑删除后还能查到 | BaseDO#L53-L54 | 字段没加 @TableLogic,或用了自定义 SQL 手写 WHERE |
| 分页 total 不对 | MyBatisUtils#L48 | 有人重新打开了 optimizeJoinOfCountSql |
| 排序不生效 | MyBatisUtils#L108-L114 | 字段不在白名单(含下划线/别名),被静默跳过 |
| 租户条件没拼 | TenantDatabaseInterceptor#L68-L81 | DO 没继承 TenantBaseDO,或类上标了 @TenantIgnore |
| 批量插入慢 | BaseMapperX#L232-L256 | 走了 SQL Server 逐条分支,或 batch size 太小 |
FOR UPDATE 不生效 | #L130-L145 | 没在事务里调用,锁立即释放 |
| 类型处理器不生效 | @TableField(typeHandler = ...) | 字段类型与 handler 泛型不匹配;或查询用了自定义 XML 没声明 resultMap |
| 跨库事务部分回滚 | @DSTransactional | 用了 @Transactional,只覆盖当前数据源 |