字段映射与列类型
郭胜凯2026/08/17
Smart MyBatis 会根据实体字段、全局命名策略和当前数据库方言构建 ColumnDeclaration。普通业务优先使用约定推导，只有明确需要时才添加 @TableField。
命名策略
spring:
mybatis:
smart:
naming-convention: underline_upper
| 策略 | userName 对应列 |
|---|---|
underline_upper | USER_NAME |
underline_lower | user_name |
as_is | userName |
字段名会与表名使用同一套 naming-convention。
TableField 属性
public class User extends PO {
@ID
private Long id;
@TableField(length = 50, description = "用户名")
private String username;
@TableField(columnType = "VARCHAR(32)")
private String status;
@TableField(json = true)
private Map<String, Object> preferences;
@TableField(exist = false)
private String displayLabel;
}
| 属性 | 作用 |
|---|---|
description | 提供列注释/描述元数据；是否写入 DDL 由方言决定 |
exist=false | 普通非数据库字段，不参与 CRUD 和建表 |
json=true | 使用 SmartJsonTypeHandler 读写 JSON |
columnType | 跳过 Java 类型推导，直接使用指定 DDL 类型 |
length | 字符串列推导长度，默认 255 |
link/linkField/self/target | 声明自动关联字段 |
value | 列名声明；3.0.2 存在下述已知限制 |
类型由方言决定
同一个 Java 类型在不同数据库中可能映射为不同列类型：
| Java 类型/字段 | MySQL | H2 | Oracle | DB2 |
|---|---|---|---|---|
Integer | INT(11) | INT | NUMBER(10) | INTEGER |
Long | BIGINT | BIGINT | NUMBER(19) | BIGINT |
Boolean | TINYINT(1) | BOOLEAN | NUMBER(1) | DECIMAL(1) |
String | VARCHAR(n)/TEXT | VARCHAR(n)/CLOB | VARCHAR2(n)/CLOB | VARCHAR(n)/CLOB |
json=true | LONGTEXT | CLOB | CLOB | CLOB |
columnType 会直接耦合目标数据库。例如 VARCHAR2(100) 只能用于支持该类型的数据库；希望跨数据库时应让方言根据 Java 类型推导。
3.0.2 列名覆盖限制
当前行为
3.0.2 的字段名解析会在读取 @TableField.value 后继续按全局命名策略计算列名，因此 @TableField("LEGACY_NAME") 目前不能作为可靠的遗留列名覆盖方案。
在修复版本发布前：
- 优先让 Java 字段名通过命名策略映射到真实列名。
- 遗留表使用原生 MyBatis XML、
@Results或明确的注解 SQL。 - 不要在新代码中依赖
@TableField.value后再以切换命名策略的方式验证。
详情见 3.0.2 版本说明与已知限制。