实体类定义

郭胜凯2025/11/21

说明

在Smart Mybatis中, 实体类用于表示数据库中的表结构。每个实体类对应数据库中的一张表, 类的属性对应表中的字段。通过定义实体类, 开发者可以方便地进行数据库操作, 如增删改查等。

我们可以使用标准的JavaBean规范来定义实体类, 包括私有属性、公共的getter和setter方法。此外, Smart Mybatis还支持使用注解来指定实体类与数据库表之间的映射关系, 例如指定表名、字段名、主键生成策略等。

基础规范

实体类必须继承自PO类, 以便获得基本的持久化功能。
实体类中必须有一个主键字段, 并使用@ID注解进行标识。
一个实体只能声明一个 @ID 字段。

@SmartMeta 是可选的编译期元数据标记，不影响普通 Mapper 使用。详情见编译期实体元数据。

简单示例

下面是一个简单的实体类示例:

public class User extends PO {
    @ID
    private Long id; 
    private String username; 
    private String email;

    // Getter和Setter方法
}

在这个示例中, User类表示数据库中的user表, 包含id, username和email三个字段。@ID注解用于标识主键字段。

进阶用法

表名映射

默认情况下, 实体类名会被转换为下划线命名的大写表名(如UserProfile会映射为USER_PROFILE表)。具体的转换规则取决于配置中的naming-convention选项命名转换规则详情。

如果需要自定义表名, 比如将这个实体类强制映射为custom_user_table表, 可以使用@TableName注解:

@TableName("custom_user_table")
public class User extends PO {
    @ID
    private Long id; 
    private String username; 
    private String email;

    // Getter和Setter方法
}

字段映射

类似地, 实体类的属性名会被转换为下划线命名的大写字段名(如userName会映射为USER_NAME字段)。

@TableField 可以声明字段长度、数据库类型、描述、JSON 存储、非数据库字段和关联元数据：

@TableName("custom_user_table")
public class User extends PO {
    @ID
    private Long id;

    @TableField(length = 50, description = "用户名字段")
    private String username;

    @TableField(json = true, description = "偏好设置")
    private Map<String, Object> preferences;

    @TableField(exist = false)
    private String displayLabel;

    private String email;
}

属性	说明
`value`	列名声明；3.0.2 存在已知限制，见下方提示
`description`	字段描述/注释元数据
`exist`	是否为物理列；`false` 时普通字段不参与持久化
`json`	是否通过 JSON TypeHandler 序列化
`columnType`	显式指定 DDL 类型，会绑定具体数据库
`length`	推导字符串列长度，默认 255
`link/linkField/self/target`	自动关联查询元数据

3.0.2

当前实现会在读取 @TableField.value 后继续按全局命名策略计算列名，因此不要依赖 @TableField("LEGACY_COL") 覆盖真实列名。遗留字段先使用原生 MyBatis 映射，详见版本说明。

事实上, 我们会根据实体类的属性类型, 自动推断数据库字段的类型, 以以下代码为例:

@TableField(length = 50, description = "用户名字段")

框架会根据 Java 类型和当前数据库方言推导列类型。只有在明确接受数据库绑定时，才使用：

@TableField(columnType = "VARCHAR(50)", description = "用户名字段")

例如 MySQL、H2、Oracle 对字符串和 JSON 的列类型并不完全相同，默认推导通常更利于跨数据库运行。

同时, Smart Mybatis 也会根据其他常见的Java类型, 自动映射为合适的数据库字段类型, 包括枚举类型和自定义对象类型. 具体可以查看自定义字段映射和对象字段存储章节。