Java开发经验——阿里巴巴编码规范实践解析6

摘要

本文深入解析了阿里巴巴编码规范在数据库设计和Java开发中的实践应用。详细阐述了数据库字段命名、类型选择、索引命名等规范，以及Java POJO类的对应规范。强调了字段命名的重要性，如布尔字段命名规则、表名和字段名的命名禁忌等。同时，介绍了主键、唯一索引和普通索引的区别，以及小数类型和字符串类型的选择建议。还提出了表设计的必备字段、逻辑删除操作、表命名规则、字段注释更新、冗余字段使用、分库分表等最佳实践。

1. 【强制】表达是与否概念的字段，必须使用 is_xxx 的方式命名，数据类型是 unsigned tinyint（1 表示是，0 表示否）。

注意：POJO 类中的任何布尔类型的变量，都不要加 is 前缀，所以，需要在<resultMap>设置从 is_xxx 到 Xxx 的映射关系。数据库表示是与否的值，使用 tinyint 类型，坚持 is_xxx 的命名方式是为了明确其取值含义与取值范围。说明：任何字段如果为非负数，必须是 unsigned。

正例：表达逻辑删除的字段名 is_deleted，1 表示删除，0 表示未删除。

1.1. 数据库字段规范

表示“是/否”概念的字段（即布尔逻辑值），数据库字段名必须是 is_xxx 的形式。
字段类型必须是 TINYINT(1) UNSIGNED。

- 1 表示是，0 表示否。
- UNSIGNED 表示值非负，防止异常数据（如 -1）存入。

示例字段：

is_deleted TINYINT(1) UNSIGNED DEFAULT 0 COMMENT '是否已删除：0-否，1-是'

1.2. Java 对应 POJO 类中的规范

在 Java Bean 中，不要将布尔变量命名为 isXxx，而是直接命名为 xxx（符合 JavaBean 的 getter/setter 规范）。
对应 MyBatis 的 <resultMap> 中，应将数据库字段 is_xxx 映射到 Java 字段 xxx。

1.2.1. ✅ 正例示范

数据库表结构：

CREATE TABLE user (
  id BIGINT PRIMARY KEY,
  name VARCHAR(50),
  is_deleted TINYINT(1) UNSIGNED NOT NULL DEFAULT 0 COMMENT '是否删除，0：未删除，1：已删除',
  is_active TINYINT(1) UNSIGNED NOT NULL DEFAULT 1 COMMENT '是否激活，1：是，0：否'
);

Java 实体类：

public class User {
    private Long id;
    private String name;
    private Boolean deleted; // 对应 is_deleted
    private Boolean active;  // 对应 is_active

    // Getter & Setter
}

MyBatis resultMap 映射：

<resultMap id="userMap" type="com.example.User">
  <id column="id" property="id"/>
  <result column="name" property="name"/>
  <result column="is_deleted" property="deleted"/>
  <result column="is_active" property="active"/>
</resultMap>

1.2.2. ❌ 错误的数据库命名：

deleted TINYINT(1)

问题：字段不明确，是否是布尔值？是否为逻辑删除？不清晰。

1.2.3. ❌ 错误的 Java 命名：

private Boolean isDeleted;

问题：违反 JavaBean 标准（可能会导致序列化、反射或工具类识别异常）。

2. 【强制】表名、字段名必须使用小写字母或数字，禁止出现数字开头禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。

说明：MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是区分大小写。因此，数据库名、表名、字段名，都不允许出现任何大写字母，避免节外生枝。

正例：aliyun_admin，rdc_config，level3_name
----------------------------------------------
反例：AliyunAdmin，rdcConfig，level_3_name

2.1. 字段名、表名的命名规则

要求项	说明	示例
✅ 必须小写	表名、字段名全部使用小写字母	`user` , `order_detail`
✅ 可包含数字	数字可以出现但不能开头	`level3_name` , `config_2025`
✅ 使用下划线分隔	多个单词之间用下划线分隔（snake_case）	`user_address` , `order_item_detail`
❌ 禁止使用大写字母	防止 Linux 环境下大小写敏感导致识别错误	`AliyunAdmin`, `RDC_Config`（❌）
❌ 禁止数字开头	SQL 不允许以数字开头的标识符	`3rd_party_data`（❌）
❌ 禁止两个下划线中只出现数字	防止字段难以理解、阅读性差	`level__3_name`（❌）

2.2. ✅ 正确示例

类型	命名示例	说明
表名	`aliyun_admin`	小写字母 + 下划线
表名	`rdc_config`	多单词用下划线分隔
字段名	`level3_name`	数字不能开头，不能 `_3_`

2.3. 🚫 错误示例及原因

错误命名	原因说明
`AliyunAdmin`	包含大写字母，不兼容 Linux 下默认设置
`rdcConfig`	使用了驼峰命名法，不标准
`3rd_party`	数字不能开头
`level__3_name`	`__3_`中仅包含数字，阅读性差

2.4. ⚠️ 补充说明

MySQL 在 Windows 是大小写不敏感，但在 Linux 是敏感的。
表名、字段名一旦设计完成并投入生产，修改代价极大，涉及代码、SQL、工具等多方调整，无法热部署、灰度发布。
因此在建表、建字段初期就应当一次设计好、长期使用，统一规范是非常重要的。

3. 【强制】表名不使用复数名词。

说明：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数形式，符合表达习惯。

4. 【强制】禁用保留字，如 desc、range、match、delayed 等，请参考 MySQL 官方保留字。

5. 【强制】主键索引名为 pk_字段名；唯一索引名为 uk_字段名；普通索引名则为 idx_字段名。

说明：pk_即 primary key；uk_即 unique key；idx_即 index 的简称。

这条规范强调数据库索引命名应 遵循统一的命名规则，以提高可读性、维护性和一致性。主要定义了三类索引的命名方式：

5.1. ✅ 命名规则说明

索引类型	命名格式	含义
主键索引	`pk_字段名`	Primary Key（主键）
唯一索引	`uk_字段名`	Unique Key（唯一约束）
普通索引	`idx_字段名`	Index（一般查询优化用途）

5.2. ✅ 正确示例

假设我们有一张 user 表，结构如下：

CREATE TABLE user (
  id BIGINT NOT NULL,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100) NOT NULL,
  phone VARCHAR(20),
  PRIMARY KEY (id),
  UNIQUE KEY uk_username (username),
  UNIQUE KEY uk_email (email),
  KEY idx_phone (phone)
);

解读：

pk_id：主键索引，命名为 pk_id。
uk_username：username 字段上的唯一约束，命名为 uk_username。
uk_email：email 字段上的唯一约束。
idx_phone：普通索引，用于加速对 phone 字段的查询。

5.3. ❌ 错误示例（不规范命名）

CREATE TABLE user (
  id BIGINT NOT NULL,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100) NOT NULL,
  phone VARCHAR(20),
  PRIMARY KEY (id),
  UNIQUE KEY unique_user_name (username),
  UNIQUE KEY EMAIL_UNIQ (email),
  KEY PHONE_INDEX (phone)
);

问题：

命名不统一，难以快速识别索引用途
存在大小写混用、冗余命名（如加上 _index）

5.4. ✅ 建议总结

项目	建议命名示例
主键	`pk_id`
唯一索引	`uk_username`、`uk_email`
普通索引	`idx_phone`、`idx_create_time`

5.5. ✅ 小贴士

命名使用 小写字母 + 下划线，符合 MySQL 通用命名规范。
如果是联合索引，命名可组合字段名：idx_userid_orderid。
命名规范不仅清晰，还能便于代码自动生成工具（如 MyBatis Generator）正确识别索引用途。

6. 主键（Primary Key）、唯一索引（Unique Key）和普通索引（Index）区别？

主键（Primary Key）、唯一索引（Unique Key）和普通索引（Index）是数据库中三种常见的索引类型，它们的主要区别如下：

6.1. 主键（Primary Key）

特点

表中只能有一个主键。
不允许为 NULL。
自动创建一个唯一索引。
通常用于唯一标识一条记录。

📌 示例

CREATE TABLE user (
  id BIGINT NOT NULL,
  name VARCHAR(50),
  PRIMARY KEY (id)  -- 主键
);

🧠 场景

用作每行数据的唯一标识，例如 id 字段。

6.2. 唯一索引（Unique Key）

特点：

可以有多个唯一索引。
所有列的组合值必须唯一。
允许为 NULL（但有数据库兼容性差异，如 MySQL 可有多个 NULL）。

示例：

CREATE TABLE user (
  id BIGINT NOT NULL,
  email VARCHAR(100),
  username VARCHAR(50),
  PRIMARY KEY (id),
  UNIQUE KEY uk_email (email),       -- 唯一索引
  UNIQUE KEY uk_username (username)  -- 唯一索引
);

场景：适合用于如 邮箱、用户名 等不允许重复的字段。

6.3. 普通索引（Index）

特点：

没有唯一性限制。
可以创建多个普通索引。
主要用于加速查询，不会约束数据唯一性。

示例：

CREATE TABLE user (
  id BIGINT NOT NULL,
  phone VARCHAR(20),
  PRIMARY KEY (id),
  KEY idx_phone (phone)  -- 普通索引
);

场景：适用于频繁用于 WHERE、ORDER BY 的查询字段，提高查询性能。

6.4. 对比总结

项目	主键（Primary Key）	唯一索引（Unique Key）	普通索引（Index）
是否唯一	✅ 唯一	✅ 唯一	❌ 不保证唯一
是否可为 NULL	❌ 不可	✅ 可为 NULL（MySQL 中）	✅ 可为 NULL
数量限制	仅 1 个	多个	多个
自动索引	✅ 是	✅ 是	✅ 是
用途	主键标识，约束唯一	唯一约束某字段或组合	查询加速，无约束功能

7. 【强制】小数类型为 decimal，禁止使用float和 double。

说明：在存储的时候，float 和 double 都存在精度损失的问题，很可能在比较值的时候，得到不正确的结果。如果存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数并分开存储。

7.1. ❌ float / double：

属于浮点类型，底层是二进制存储，存在精度误差。
不适合用于表示金额、利率、积分等精准计算数据。
比如存入 0.1，取出来可能是 0.100000001，比较时可能出现误判。

7.2. ✅ decimal（或 numeric）：

定点数类型，可设定精确的小数位数。
存储精度高，不会有精度损失。
非常适合用来表示金额、比例、利率、计量单位等对精度要求高的场景。

7.3. ❌ 错误示例：使用 `float`

CREATE TABLE order_info (
  order_id BIGINT PRIMARY KEY,
  amount FLOAT(10, 2)  -- ❌ 错误，金额不能用 float
);

7.4. ✅ 正确示例：使用 `decimal`

CREATE TABLE order_info (
  order_id BIGINT PRIMARY KEY,
  amount DECIMAL(10, 2)  -- ✅ 精确保留 2 位小数，适合金额
);

DECIMAL(10, 2) 表示总位数最多 10 位，其中小数位最多 2 位，例如最大可存储 99999999.99。

7.5. 场景举例

字段名称	推荐类型	原因
金额	`decimal(10, 2)`	防止精度误差
比例	`decimal(5, 4)`	精确表示 0.1234
积分	`decimal(10, 0)`	整数，不丢失精度
税率	`decimal(5, 3)`	精确控制千分位

8. 【强制】如果存储的字符串长度几乎相等，使用 char 定长字符串类型。

如果字符串长度基本一致（差异极小，比如身份证号、手机号、MD5、UUID 等），使用 CHAR(n) 类型
如果长度变化较大（如评论、地址等），使用 VARCHAR(n)

8.1. 为什么选 `CHAR` 而不是 `VARCHAR`？

CHAR 是定长：数据库在存储时预留固定空间，读取更快。
VARCHAR 是变长：虽然节省空间，但读取时性能略差（因为存储时多一个字节表示长度）。
当字段长度固定或接近固定时，用 CHAR 可以带来更好的查询效率和缓存命中率。

8.2. ✅ 正确使用 `CHAR`

字段用途	示例字段名	推荐类型	理由
身份证号码	`id_card_no`	`CHAR(18)`	长度固定 18 位
手机号	`phone_number`	`CHAR(11)`	长度固定 11 位
UUID	`uuid`	`CHAR(36)`	固定长度 36 字符
MD5 值	`md5_hash`	`CHAR(32)`	MD5 长度恒定为 32 位

CREATE TABLE user_info (
  id BIGINT PRIMARY KEY,
  id_card_no CHAR(18) NOT NULL,
  phone_number CHAR(11),
  uuid CHAR(36)
);

8.3. ❌ 错误使用 `VARCHAR`（会增加开销）

-- 不推荐的写法
CREATE TABLE user_info (
  id_card_no VARCHAR(18),
  phone_number VARCHAR(11)
);

会消耗更多 CPU 来处理长度字段。
在索引上也会影响查询效率。

9. `CHAR`、`VARCHAR`、`TEXT`、`LONGTEXT`、`JSON`类型怎么选择

在设计数据库时选择合适的字符串类型（CHAR、VARCHAR、TEXT、JSON 等）非常关键，它直接关系到性能、存储、查询能力和未来扩展性。以下是各类型的适用场景、优缺点和使用建议：

9.1. `CHAR(n)`（定长字符串）

✅ 使用场景：

字段长度固定或几乎固定，如：

- 身份证号（18 位）
- 手机号（11 位）
- UUID（36 位）
- 状态码、性别标识、等级标识等短字段

✅ 优点：

存储效率高，查询速度快
内部无需存储长度信息（相比 VARCHAR）
在索引中表现更好

❌ 缺点：

会浪费空间（不足会用空格填充）

9.2. `VARCHAR(n)`（变长字符串）

✅ 使用场景：

字符串长度不固定，但最大长度可预期

- 姓名、地址、标题、描述、邮箱、URL
- 用户备注、标签、岗位名称

✅ 优点：

节省空间
灵活性更高

❌ 缺点：

查询性能略差于 CHAR
需要额外字节存储实际长度

9.3. `TEXT`（长文本）

✅ 使用场景：

大段内容存储，如：

- 文章正文、博客内容、富文本
- 聊天记录、用户反馈、日志内容

✅ 优点：

可存储大容量文本（最大约 64KB）

❌ 缺点：

不能创建普通索引（要用全文索引 Fulltext）
查询和排序性能低
不能设置默认值
使用时不走 InnoDB 缓存（页缓存）

9.4. `JSON`（MySQL 5.7+ 支持的 JSON 类型）

✅ 使用场景：

数据结构多变、不固定，但需结构化查询的字段，如：

- 可变配置字段
- 动态参数、扩展字段（metadata）
- 日志上下文结构、第三方返回结果原始数据

✅ 优点：

可以使用 JSON 函数查询子字段
数据结构灵活，不需要频繁改表
比 TEXT 更可控（支持路径查询）

❌ 缺点：

不适合做频繁的复杂查询（特别是多层嵌套）
MySQL 不对 JSON 字段做强类型校验
查询性能低于结构化字段

9.5. 数据库字段类型选择总结对比

类型	可索引	适合场景	是否支持结构化查询	默认值	备注
CHAR	✅	固定长度、标识符	❌	✅	性能最好，浪费空间
VARCHAR	✅	一般字符串	❌	✅	最常用，平衡空间和性能
TEXT	🚫（支持全文）	大段文本	❌	❌	不可默认，不能索引排序
JSON	✅（仅部分支持）	动态结构、可选字段	✅（使用 JSON 函数）	❌	查询略慢，适合扩展字段

MySQL 中的 TEXT 并非只有一种，而是有多个变种，每种容量不同：

类型	最大长度（字符）	最大容量（字节）	描述
`TINYTEXT`	255 字符	255 字节	非常小的文本数据
`TEXT`	65,535 字符	64 KB	常用的一般文本
`MEDIUMTEXT`	16,777,215 字符	16 MB	中等大小文本，如文章、日志等
`LONGTEXT`	4,294,967,295 字符	4 GB	超大文本，如小说、配置等

9.6. 使用建议（选型规则）

固定长度字段（手机号、身份证） → CHAR
普通内容字段（姓名、地址、标题） → VARCHAR
长文本内容（富文本、日志、文章） → TEXT
结构不固定字段但需要查询（配置、上下文参数） → JSON

10. 【强制】varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引率。

11. 【强制】表必备三字段：id，create_time，update_time。

说明：其中 id 必为主键，类型为 bigint unsigned、单表时自增、步长为 1。create_time，update_time 的类型均为datetime 类型，如果要记录时区信息，那么类型设置为 timestamp。

除了【强制】的三大字段 id、create_time、update_time 之外，数据表设计中通常还会包含一些常用的“必要字段”，这些字段能够增强数据管理、业务逻辑和安全性。下面给你梳理一下常见且推荐的字段：

11.1. 常见数据表必要字段汇总

字段名	类型	作用说明	备注
`id`	`bigint unsigned`	主键，自增，唯一标识一条记录	必须
`create_time`	`datetime` / `timestamp`	记录创建时间	必须
`update_time`	`datetime` / `timestamp`	记录最后修改时间	必须
`is_deleted`	`tinyint unsigned` (0/1)	逻辑删除标志，1=已删除，0=未删除	代替物理删除，方便数据恢复
`create_user`	`bigint unsigned`	记录创建该条数据的用户ID	可选，追踪操作人
`update_user`	`bigint unsigned`	记录最后修改该条数据的用户ID	可选，追踪操作人
`version`	`int unsigned`	乐观锁版本号，用于控制并发更新	预防并发修改冲突
`status`	`tinyint unsigned`	业务状态字段，如激活、禁用、审核中等	业务自定义状态码
`remark`	`varchar(255)`	备注字段	可存储补充说明

11.2. 数据库设计建议

逻辑删除字段 is_deleted，避免直接物理删除，方便数据恢复与审计。
操作用户字段 create_user 和 update_user，便于追踪责任。
乐观锁字段 version，防止数据被并发修改导致不一致。
状态字段 status，统一管理业务状态，方便业务流程控制。
备注字段 remark，记录额外信息，便于维护和扩展。

CREATE TABLE example_entity (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  is_deleted TINYINT UNSIGNED NOT NULL DEFAULT 0,
  create_user BIGINT UNSIGNED, -- 适合采用用户id 而不是采用字符类型
  update_user BIGINT UNSIGNED, -- 适合采用用户id 而不是采用字符类型
  create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  version INT UNSIGNED NOT NULL DEFAULT 0,
  status TINYINT UNSIGNED NOT NULL DEFAULT 1,
  remark VARCHAR(255)
);

12. 【强制】在数据库中不能使用物理删除操作，要使用逻辑删除。

说明：逻辑删除在数据删除后可以追溯到行为操作。不过会使得一些情况下的唯一主键变得不唯一，需要根据情况来酌情解决。

13. 【推荐】表的命名最好是遵循“业务名称表的作用”

正例：alipay_task / force_project / trade_config / tes_question

14. 【推荐】库名与应用名称尽量一致。

15. 【推荐】如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。

16. 【推荐】字段允许适当冗余，以提高查询性能，但必须考虑数据一致。冗余字段应遵循：

不是频繁修改的字段。
不是唯一索引的字段。
不是 varchar 超长字段，更不能是 text 字段。

正例：各业务线经常冗余存储商品名称，避免查询时需要调用 IC 服务获取。

17. 【推荐】单表行数超过 500 万行或者单表容量超过 2GB，才推荐进行分库分表。

说明：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。

这条建议是基于实际项目中分库分表的复杂度和维护成本而总结的经验，确实很有参考价值。下面我帮你详细说明实际情况和背后的考虑：

17.1. 实际情况分析：

单表数据量和性能瓶颈

单表数据量超过 几百万行，数据库的查询性能、索引维护、备份恢复等都会受到影响，尤其是没有做合理索引和查询优化时。
表容量超过 2GB，尤其是普通的 OLTP 场景，可能导致 I/O 压力变大，查询响应变慢。
但具体影响还依赖于硬件性能、数据库版本、存储引擎（InnoDB等）、缓存配置等。

分库分表的复杂度

设计分库分表架构，代码复杂度大幅提升，开发和运维成本高。
涉及跨库事务处理难度大，分布式事务开销大，调试复杂。
预先分库分表可能带来不必要的系统复杂度和风险。

业务增长预估与实际

很多项目上线初期数据量较小，提前做分库分表导致资源浪费和开发负担。
预测三年后的数据量不到 500 万或容量不到 2GB，完全可以先用单库单表，后期再扩展。
可以结合归档策略、清理机制等避免数据爆表。

分库分表时机

实际上很多大公司都是业务增长到瓶颈才开始分库分表，采用平滑迁移方案。
使用中间件（如 MyCat、ShardingSphere）或自研分片逻辑，逐步迁移。

17.2. 总结建议：

条件	推荐做法
数据量 < 500万行，容量 < 2GB	单库单表即可，先保证稳定
数据量接近或超过 500万行，容量 > 2GB	评估是否做分表，考虑读写压力
业务增长迅速，数据爆发式增长	尽早设计分库分表方案