04-实体与数据访问 pojo-mapper¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/bams-sdk/04-pojo-mapper.md

bams-pojo（50 个类）定义共享实体/DTO/VO 和类型处理器；bams-mapper（30 个类）提供 MyBatis-Plus 数据访问增强。

一、BaseEntity —— 所有业务实体的父类¶

cn.cnbm.bams.pojo.base.BaseEntity

@FieldNameConstants
@Data
public class BaseEntity implements Serializable

字段清单¶

自动填充机制¶

id 的填充不由 @TableId 完成，而是由 EnergyMetaObjectHandler.insertFill()（bams-pojo）在插入时调 IDUtil.getId() 生成。

EnergyMetaObjectHandler（抽象类，cn.cnbm.bams.ibatis.handler）： - insertFill：id 为空则 IDUtil.getId()；createdTime/updatedTime 设当前时间；createdBy/updatedBy 从 getCurrentLoginUser().get("userId") 取（默认 0L） - updateFill：只填 updatedTime/updatedBy - 抽象方法 getCurrentLoginUser()：返回 Dict，由业务应用实现

common-func 的 MyBatisPlusMetaObjectHandler 继承它，从 PermissionContextHolder 取 userId。详见 09-通用功能。

继承注意事项¶

⚠️ 子类必须用 @EqualsAndHashCode(callSuper = true) 才能把 BaseEntity 的字段纳入 equals/hashCode。历史代码中部分子类用了 callSuper = false（BdDept/BdPerson/BdPost 等），这是遗留问题。详见 12-FAQ与注意事项。

// ✅ 正确写法
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("my_table")
public class MyEntity extends BaseEntity {
    private String name;
}

// ⚠️ 不推荐（id 等字段不纳入 equals/hashCode）
@Data
@EqualsAndHashCode(callSuper = false)  // 历史遗留
public class LegacyEntity extends BaseEntity { ... }

BaseEntity.of() 静态方法¶

public static <T extends BaseEntity> T of(Object o, Class<T> clazz)

把 Map 或 Bean 转成目标实体（用 hutool BeanUtil），方便从 Dict 查询结果反构实体。

二、实体清单（按业务域）¶

bd 域 —— 基础主数据¶

sys 域 —— 系统管理¶

规律：关联表实体（UserRole/RoleResource/RoleButton/AppRole）都是轻量 POJO，不走 BaseEntity 的审计字段。

pub 域 —— 公共¶

三、BaseMapperExt —— 数据访问增强¶

cn.cnbm.bams.mapper.ext.BaseMapperExt<T>

继承 MyBatis-Plus 的 BaseMapper<T>，新增 5 个方法。业务 Mapper 一律继承此类。

public interface MyMapper extends BaseMapperExt<MyEntity> { }

新增方法¶

⚠️ 后 4 个 executeSql* 方法用 ${sql} 字符串拼接（非预编译），存在 SQL 注入风险，应由 SDK 内部受控调用，不要直接透传用户输入。

selectPageMaps 示例¶

// 分页查 Map 结果（无需建 VO）
Page<Dict> page = new Page<>(1, 10);
QueryWrapper<MyEntity> wrapper = new QueryWrapper<>();
wrapper.eq("status", 1);
Page<Dict> result = myMapper.selectPageMaps(page, wrapper);

Dict 类¶

cn.cnbm.bams.common.core.lang.Dict —— 自定义 Map 子类，重写了 getOrDefault 以区分 null 值。

四、SqlInjectorExt 机制 —— 自定义方法全局注入¶

三个类协作，把 selectPageMaps 自动注入到所有继承 BaseMapperExt 的 Mapper：

工作原理¶

SqlMethodExt（枚举，定义方法元信息）
    │ 定义方法名 "selectPageMaps" + SQL 模板
    ▼
SelectPageMaps（继承 AbstractMethod）
    │ injectMappedStatement() 构造 MappedStatement
    │ 返回类型映射为 Dict.class
    ▼
SqlInjectorExt（@Component，继承 DefaultSqlInjector）
    │ getMethodList() 在 MP 默认方法基础上追加 SelectPageMaps
    │ 因是 @Component，Spring Boot 启动时对所有 Mapper 全局生效

关键文件¶

辅助工具¶

五、@Formula 注解 —— 实体字段 = 子查询¶

cn.cnbm.bams.common.annotations.mybatis.Formula

标记在实体字段上，让该字段的值来自一个子查询表达式。

@Formula("(SELECT COUNT(*) FROM order WHERE order.cust_id = id)")
private Integer orderCount;  // 查询时自动执行子查询填充

ServiceExtImpl.getQueryWrapper 和 SqlScriptHelper 会解析 @Formula 注解，把子查询拼到 SELECT 列中。getById 也重写了以支持 @Formula。

六、多租户数据源机制¶

@TenantDataSource 注解¶

cn.cnbm.bams.common.annotations.TenantDataSource（在 common-tool 模块）

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TenantDataSource {
    String value() default "master";  // 数据源标识，默认主库
}

标记类/方法走哪个数据源。如 @TenantDataSource("sys") 表示操作 sys 系统库。

SysTenantDb 实体¶

cn.cnbm.bams.pojo.sys.SysTenantDb（表 sys_tenant_db）

承载每个租户的数据源连接信息：一个租户一行记录 = 一个独立数据库连接配置。

⚠️ 动态数据源是半成品：AbstractRoutingDataSource + ThreadLocal + Manager 框架完整，@TenantDataSource 注解已定义，但缺少 AOP 切面实现注解→自动切换，且 DynamicDataSource Bean 未注册。详见 05-业务服务层。

七、DTO / VO 补充¶

常用 DTO¶

常用 VO¶

BasicParamWrapper / BasicParamers¶

cn.cnbm.bams.pojo.basics.BasicParamWrapper（继承 BasicParamers）

通用查询参数容器。前端传一个扁平 JSON，后端按操作符分桶构建 QueryWrapper。

// 前端传参示例
{
  "current": 1,
  "size": 10,
  "searchVal": "关键词",
  "andMap": {"status": 1, "corp_code": "C001"},
  "likeMap": {"name": "张"},
  "orderBy": {"created_time": "desc"}
}

// Service 层使用
Page<MyEntity> page = myService.listPage(basicParamWrapper);

ServiceExtImpl.getQueryWrapper() 会解析 BasicParamWrapper 自动构建 MyBatis-Plus QueryWrapper，详见 05-业务服务层。

八、ibatis 类型处理器¶

相关文档¶

• 03-通用工具库 — @Formula / @TenantDataSource 等注解
• 05-业务服务层 — ServiceExtImpl 使用 BaseMapperExt
• 07-数据权限 — 数据权限与实体的 corp_code/dept_code 列