实体类与 Mapper
校对日期:2026-11-16。适用于社区版及全部商业版。
持久层使用 MyBatis(没有使用 MyBatis-Plus 或 JPA)。每张表对应一个实体类、一个 Mapper 接口和一个 Mapper XML, 实体类又拆成“与字段一一对应的基类”和“写业务代码的子类”两层。这些文件全部手写:源码中曾有的代码生成器模块 ujcms-code-generator 已经移除,新增表或修改表结构时按本文的约定编写。下文以源码自带的示例表 ujcms_example 为例。
一、一张表对应的文件
| 文件 | 作用 |
|---|---|
ujcms-cms/ | 基类:一个字段对应一个属性,不写别的 |
ujcms-cms/ | 实体类:继承基类,关联对象、常量、计算属性、JSON 注解写在这里 |
ujcms-cms/ | Mapper 接口 |
ujcms-cms/ | Mapper XML:字段映射与 SQL |
系统自带的功能分在两个包里:com.(文章、栏目、用户等核心功能)和 com.(留言、投票、友情链接等扩展功能), 两个包的结构相同。二次开发新增的表建议放在 ext 包,Mapper 不需要额外配置就会被扫描到(见“Mapper 接口”一节)。
Service、查询参数类和 Controller 的写法见后端功能开发,建表见数据库设计规范与表结构变更。
二、基类 GeneratedXxx
基类只描述表结构。类名是 Generated 加实体名,放在 domain/ 包下,用 Lombok 的 @Data 生成 getter 和 setter:
@Data
public class GeneratedExample implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
/**
* 数据库表名
*/
public static final String TABLE_NAME = "example";
/**
* ID
*/
@NotNull
@Schema(description="ID")
private Long id = 0L;
/**
* 名称
*/
@Length(max = 30)
@Nullable
@Schema(description="名称")
private String name;
/**
* 是否启用
*/
@NotNull
@Schema(description="是否启用")
private Boolean enabled = true;
}编写规则:
- 一个字段一个属性,顺序与表中字段的顺序一致。 字段名去掉末尾的下划线、转成驼峰就是属性名:
site_id_对应siteId。 TABLE_NAME是去掉ujcms_前缀的表名。 查询解析器用它拼出主表名,见查询解析器 QueryParser。- 字段注释写两遍:Javadoc 和
@Schema(description = …),后者会出现在接口文档里。 - 不可为空的字段标
@NotNull(jakarta.)并给初始值:有默认值的用默认值,没有的数字用validation. constraints. NotNull 0、 字符串用空串、日期用OffsetDateTime.。可为空的字段标now() @Nullable(org.),不给初始值。jspecify. annotations. Nullable - 字符串字段标
@Length(max = …)(org.)。长度是 30 的倍数的hibernate. validator. constraints. Length varchar按“可能存中文”处理, 上限取字段长度的三分之一:varchar(90)写@Length(max = 30),varchar(450)写@Length(max = 150);其它长度原样使用, 如varchar(100)写@Length(max = 100)。这条约定的来由见数据库设计规范与表结构变更。
字段类型与 Java 类型、Mapper XML 中 jdbcType 的对应关系:
| 字段类型 | Java 类型 | jdbcType | 说明 |
|---|---|---|---|
bigint | Long | BIGINT | 主键和外键都是它 |
int | Integer | INTEGER | |
smallint | Short | SMALLINT | 状态、类型一类的枚举值 |
char(1) | Boolean | CHAR | '1' 为是、'0' 为否,由 CharBooleanTypeHandler 转换 |
varchar | String | VARCHAR | |
text、mediumtext | String | LONGVARCHAR | 大文本,映射写在 ResultMapWithBLOBs 里(见“Mapper XML”一节) |
json | String | OTHER | 属性里是 JSON 字符串,由 JsonStringTypeHandler 按数据库读写;同样写在 ResultMapWithBLOBs 里 |
datetime | OffsetDateTime | TIMESTAMP | 日期一律用 OffsetDateTime,不用 Date |
两个类型处理器在 com. 中全局注册,XML 里只写 jdbcType 即可,不需要逐个字段指定 typeHandler。
源码里这些基类的类注释仍写着 This class was generated by MyBatis Generator,是生成器留下的,不代表文件会被重新生成。
三、实体类 Xxx
业务代码都通过实体类使用,它继承基类。示例表的实体类是空的:
public class Example extends GeneratedExample {
}表结构以外的东西都写在这一层。com.(留言板)是一个内容比较全的例子,里面有:
- 关联对象:
site、user、type等属性及其 getter、setter,由 Mapper XML 的ResultMap填充(见“Mapper XML”一节)。 用@JsonIncludeProperties({"id", "name"})限定输出到 JSON 的属性,避免把关联对象整个带出去。 - 常量:状态值
STATUS_AUDITED、STATUS_等。UNREVIEWED - 计算属性:如
isDisplayable(),不需要输出时加@JsonIgnore。 - 覆盖基类的 getter 以加注解:联系方式等隐私字段覆盖 getter 并加
@JsonView(Views.,公开的列表接口就不会返回它们。Whole. class)
有延迟加载关联(XML 中 fetchType=)的实体类要加 @JsonIgnoreProperties("handler"),否则序列化时会带出 MyBatis 代理对象的内部属性。
四、Mapper 接口
@Mapper
@Repository
public interface ExampleMapper {
int insert(Example bean);
int update(Example bean);
int delete(Long id);
@Nullable
Example select(Long id);
List<Example> selectAll(@Nullable @Param("queryInfo") QueryInfo queryInfo);
}这是普通的 MyBatis 接口,五个方法是每张表的基本配置,需要别的语句就继续加方法。selectAll 的参数 QueryInfo 是查询解析器的解析结果, 列表和分页查询都走它;参数名必须是 queryInfo,公用的 SQL 片段按这个名字取值。
接口的扫描与 XML 的位置:
com.上的ujcms. cms. ext. ContextConfig @MapperScan("com.扫描ujcms. cms. ext. mapper") ext包的 Mapper,core包同理。 Mapper 放在别的包时,要在自己的配置类上加@MapperScan;启动类只扫描com.ujcms.cms之下的包,配置类也要放在这个包之下。- XML 没有单独配置位置,靠“与接口同包同名”被找到:接口是
com., XML 就是ujcms. cms. ext. mapper. ExampleMapper src/,main/ resources/ com/ ujcms/ cms/ ext/ mapper/ ExampleMapper. xml namespace写接口的全名。
调试时在 application. 中打开 logging.(core 包同理),可以在日志里看到执行的 SQL。
五、Mapper XML
完整的例子见 ExampleMapper.。文件由三部分组成。
5.1 与字段绑定的六个元素
| 元素 | 内容 |
|---|---|
BaseResultMap | 除大文本、JSON 以外各字段的映射,主键用 <id>,其余用 <result> |
ResultMapWithBLOBs | 继承 BaseResultMap,放 text、json 类字段的映射;没有这类字段时是一个空的继承 |
Column_List | 全部字段,带主表别名 t.,如 t.id_, t. |
insert | 全部字段的插入语句 |
update | 按主键更新全部字段 |
updateBase | 按主键更新,但不含 ResultMapWithBLOBs 里的字段;没有这类字段时与 update 相同 |
这六个元素与基类一样,只跟着表结构走,不在里面加别的东西。updateBase 在接口里没有对应的方法, 需要“只改普通字段、不动大文本”时再到接口中声明 int updateBase(Xxx bean)(SiteMapper 是这样用的)。每个字段都写明 jdbcType:
<resultMap id="BaseResultMap" type="com.ujcms.cms.ext.domain.Example">
<id column="id_" jdbcType="BIGINT" property="id" />
<result column="name_" jdbcType="VARCHAR" property="name" />
<result column="enabled_" jdbcType="CHAR" property="enabled" />
</resultMap>
<resultMap extends="BaseResultMap" id="ResultMapWithBLOBs" type="com.ujcms.cms.ext.domain.Example" />5.2 ResultMap 与关联对象
查询语句统一使用 ResultMap,它继承 ResultMapWithBLOBs。没有关联对象时是一个空的继承;有关联对象时写在这里,不要写进 BaseResultMap。 留言板的写法(MessageBoardMapper.):
<resultMap extends="ResultMapWithBLOBs" id="ResultMap" type="com.ujcms.cms.ext.domain.MessageBoard">
<association column="site_id_" javaType="com.ujcms.cms.core.domain.Site" property="site" select="com.ujcms.cms.core.mapper.SiteMapper.selectRefer" />
<association column="user_id_" javaType="com.ujcms.cms.core.domain.User" property="user" select="com.ujcms.cms.core.mapper.UserMapper.selectRefer" />
</resultMap>外键字段 site_id_、user_id_ 本身仍然是基类里的普通属性,在 BaseResultMap 中照常映射。一对多的集合用 <collection>, 例子见 VoteMapper.xml 中投票与选项的关系。
5.3 查询语句与公用片段
select、delete 是按主键操作的普通语句。selectAll 不自己写 SQL,而是引用公用片段 Select_All:
<sql id="selectAllSelect" />
<sql id="selectAllJoin" />
<sql id="selectAllWhere" />
<select id="selectAll" resultMap="ResultMap">
<include refid="com.ujcms.cms.core.mapper.SeqMapper.Select_All">
<property name="tableName" value="ujcms_example" />
</include>
</select>Select_All 定义在 ujcms-cms/,它根据 queryInfo 拼出 SELECT … FROM 主表 t JOIN … WHERE … ORDER BY …:关联哪些表、有哪些条件、怎么排序,都来自查询解析器的解析结果。 tableName 只在 queryInfo 为空时使用。
Select_All 会回头引用当前文件里的四个片段,所以它们必须存在,哪怕是空的:
| 片段 | 拼在哪里 | 写法 |
|---|---|---|
Column_List | SELECT 之后 | 见 5.1 |
selectAllSelect | 字段列表之后 | 额外的查询列,以逗号开头 |
selectAllJoin | 解析器生成的 JOIN 之后 | 额外的表关联 |
selectAllWhere | 解析器生成的条件之后 | 额外的条件,以 and 开头 |
查询解析器表达不了的条件写在这三个片段里,需要的参数作为 selectAll 的额外参数传入。组织表按上级筛选的写法(OrgMapper.xml):
<sql id="selectAllJoin">
<if test="ancestorId != null">
join ujcms_org_tree orgTree on t.id_ = orgTree.descendant_id_
</if>
</sql>
<sql id="selectAllWhere">
<if test="ancestorId != null">
and orgTree.ancestor_id_ = #{ancestorId}
</if>
</sql>对应的接口方法多一个参数:selectAll(@Param("queryInfo") QueryInfo queryInfo, @Param("ancestorId") Long ancestorId, …)。 selectAllSelect 的例子见 DictTypeMapper.(给每个字典类型带出字典条数)。
系统支持多种数据库。确实要写某种数据库专用的 SQL 时,按 _databaseId 判断(SeqMapper.xml 里处理 JSON 字段的片段就是这样写的), 可用的标识在 MyBatisConfig 的 databaseIdProvider 中登记(mysql、mariadb、postgresql、dm、kingbase 等)。
六、修改表结构时要改的地方
加一个字段、改长度、改注释,都要同时改三处,并保持字段顺序一致:
- Liquibase 的变更日志(见数据库设计规范与表结构变更)。
- 基类
GeneratedXxx:增改属性及其注解、初始值。 - Mapper XML 的六个元素:
BaseResultMap或ResultMapWithBLOBs、Column_List、insert、update、updateBase。insert的字段列表与取值列表要一一对应,最容易漏。
实体类 Xxx、Mapper 接口和 XML 的其余部分不受影响。
七、常见问题
手里的源码有 ujcms-code-generator 目录,或者旧文档提到运行 CodeGenerator。 13.2.3 及更早版本的源码里有代码生成器模块,之后的版本已经移除。现在的基类和 XML 都是手写的,写法沿用生成器当初的格式, 所以新旧文件看起来一样;新增表或修改表结构时按本文的约定手写即可。
varchar(90) 的字段,为什么校验上限是 30? 长度为 30 的倍数的字符串字段按每个汉字 3 个字节预留了空间,@Length 写的是允许的字符数,见“基类 GeneratedXxx”一节。