Skip to content

数据访问约定 ​

一句话:所有 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-L145SELECT ... 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 (...)
最后PaginationInnerInterceptormybatis 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));
    }
}

要点:

  1. 别自己 new Page,走 selectPage,排序白名单与 count 优化都已处理;
  2. 条件用 xxxIfPresent(LambdaQueryWrapperX#L21-L104),参数为空自动跳过,避免 WHERE name LIKE '%%' 这类全表条件;
  3. 联表用 selectJoinPage,不要手写 XML 再自己拼分页;
  4. 必须带租户/数据权限的表,不要加 @TenantIgnore 绕过,先确认是否真需要跨租户;
  5. 更新/删除前先 selectById 校验归属,不要直接 updateById 一个前端传来的 ID(越权改数据)。

7. 排错清单 ​

症状先看判断依据
create_time 为空DefaultDBFieldHandler#L22-L46DO 没继承 BaseDO,或字段名与注解不匹配
逻辑删除后还能查到BaseDO#L53-L54字段没加 @TableLogic,或用了自定义 SQL 手写 WHERE
分页 total 不对MyBatisUtils#L48有人重新打开了 optimizeJoinOfCountSql
排序不生效MyBatisUtils#L108-L114字段不在白名单(含下划线/别名),被静默跳过
租户条件没拼TenantDatabaseInterceptor#L68-L81DO 没继承 TenantBaseDO,或类上标了 @TenantIgnore
批量插入慢BaseMapperX#L232-L256走了 SQL Server 逐条分支,或 batch size 太小
FOR UPDATE 不生效#L130-L145没在事务里调用,锁立即释放
类型处理器不生效@TableField(typeHandler = ...)字段类型与 handler 泛型不匹配;或查询用了自定义 XML 没声明 resultMap
跨库事务部分回滚@DSTransactional用了 @Transactional,只覆盖当前数据源