MySQL 数据类型与 Java 类型映射

MySQL 数据类型与 Java 类型的完整映射手册，涵盖整数、浮点、字符串、日期、二进制等所有类型，以及 MyBatis 特殊映射和常见踩坑点。

MySQL 系列：MySQL 简介 · MySQL 数据库设计规范 · MySQL 索引原理与优化

整数类型

[!tip] 选型原则

• 主键 ID → BIGINT UNSIGNED + Java Long
• 业务状态/枚举 → TINYINT + Java Integer（MyBatis 可映射枚举）
• 计数器/普通数字 → INT + Java Integer
• 避免用 TINYINT(1) 存布尔，会被 JDBC 驱动自动映射为 Boolean，建议显式加 tinyint1isBit=false

浮点 / 定点类型

[!warning] 金额存储铁律 金额字段必须使用 DECIMAL(19,4) + Java BigDecimal，禁止使用 FLOAT/DOUBLE

price DECIMAL(19, 4) NOT NULL DEFAULT '0.0000' COMMENT '价格'

private BigDecimal price;

字符串类型

[!tip] VARCHAR 选型原则

• 短标识符（名称、编码）→ VARCHAR(64) 或 VARCHAR(128)
• 业务描述 → VARCHAR(512)
• URL / 路径 → VARCHAR(2048)
• 超过 2048 考虑用 TEXT
• VARCHAR(N) 的 N 是字符数，不是字节数（utf8mb4 每字符最多 4 字节）

日期 / 时间类型

[!warning] TIMESTAMP vs DATETIME

• TIMESTAMP 会随时区变化，存储 UTC，取出自动转本地时区
• DATETIME 存什么取什么，无时区概念
• 推荐使用 DATETIME + Java LocalDateTime，避免时区问题
• 创建时间/更新时间 → DATETIME DEFAULT CURRENT_TIMESTAMP

二进制类型

[!caution] 二进制存储建议 文件/图片等大二进制数据不建议存 MySQL，应使用对象存储（S3Plus/OSS），MySQL 只存 URL。

布尔 / 枚举 / 集合

完整 Java ↔ MySQL 类型对应速查

Java Type          → MySQL Type
─────────────────────────────────────────
Boolean            → TINYINT(1)
Byte               → TINYINT
Short              → SMALLINT
Integer            → INT
Long               → BIGINT
Float              → FLOAT
Double             → DOUBLE
BigDecimal         → DECIMAL(M,D)
String             → VARCHAR(N) / TEXT / CHAR(N)
byte[]             → BLOB / VARBINARY
java.util.Date     → DATETIME / TIMESTAMP
java.sql.Date      → DATE
java.sql.Timestamp → TIMESTAMP
LocalDate          → DATE
LocalTime          → TIME
LocalDateTime      → DATETIME
Enum               → VARCHAR / TINYINT（存 ordinal 或 name）

MyBatis / MBG 特殊映射

常用建表规范

CREATE TABLE `t_example` (
  `id`          BIGINT       NOT NULL AUTO_INCREMENT COMMENT '主键',
  `entity_key`  VARCHAR(128) NOT NULL DEFAULT '' COMMENT '业务唯一键',
  `status`      TINYINT      NOT NULL DEFAULT 1  COMMENT '状态 1-有效 0-无效',
  `amount`      DECIMAL(19,4)NOT NULL DEFAULT '0.0000' COMMENT '金额',
  `ext_info`    VARCHAR(2048)         DEFAULT NULL COMMENT '扩展JSON',
  `created_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_entity_key` (`entity_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='示例表';

常见坑点速记

[!bug] 高频踩坑

1. TINYINT(1) 被驱动当 Boolean：在 JDBC URL 加 tinyint1isBit=false
2. TIMESTAMP 2038 问题：新表统一用 DATETIME
3. VARCHAR 长度是字符数：VARCHAR(255) 在 utf8mb4 下最大 1020 字节
4. INT(11) 括号无意义：括号只影响展示宽度，不影响存储范围（MySQL 8.0.17 已废弃）
5. 枚举用 ordinal 存储：Java 枚举顺序变化会导致数据错乱，建议用 name() 或指定 code 字段
6. DECIMAL 精度：DECIMAL(19,4) 最多 15 位整数 + 4 位小数
7. 分布式 ID 用 BIGINT：INT 上限约 21 亿，高并发系统容易溢出

参考

• MySQL 8.0 官方数据类型文档
• MyBatis 类型映射