适用于所有 Nebula 框架业务项目的数据库脚本编写规范。
读完本文，你将掌握 Flyway 版本管理、DDL 建表标准格式（含 BaseEntity 11 个公共字段）、索引设计，以及菜单/字典初始化 DML 的写法。

---

目录

• 一、Flyway 版本文件命名
• 二、DDL 建表规范
• 三、字段设计规范
• 四、索引设计规范
• 五、菜单与字典 DML 规范
• 六、字段变更脚本规范

---

一、Flyway 版本文件命名

脚本存放路径：{项目}-server/src/main/resources/db/migration/

命名格式：V{大版本}.{小版本}.{补丁}__{描述}.sql

V1.0.0__init_t_demo.sql          # 建表 DDL
V1.0.1__add_column_xxx.sql       # 字段变更（新增列、修改注释等）
V1.0.2__init_demo_menu_data.sql  # 菜单/字典初始化 DML
V1.0.3__alter_t_demo_index.sql   # 索引调整

规则：

• 版本号必须严格递增，已提交的脚本文件绝对不可修改
• 双下划线 __ 分隔版本号与描述
• 描述用英文蛇形命名，简洁说明变更内容
• 一次发布对应一个文件，不拆分多文件（除非必要）

---

二、DDL 建表规范

2.1 表命名

• 格式：t_{业务名蛇形}
• 示例：t_demo、t_customer、t_order_detail
• 系统表使用 sys_ 前缀（如 sys_user、sys_menu）

2.2 BaseEntity 公共字段（必须完整包含）

每张业务表必须包含来自 BaseEntity 的 11 个公共字段，顺序固定，且全部集中置于业务字段之前（不可与业务字段交错排列）。

高频错误： 只写到 delete_flag 就结束，漏掉 remark 和 custom_fields。这会导致 MyBatis-Plus 自动填充时找不到列，运行时报错。

建表前逐一核对 11 个字段：

#	列名	类型约束	高频遗漏
1	id	BIGINT NOT NULL	—
2	tenant_id	BIGINT DEFAULT NULL	—
3	create_user_id	BIGINT DEFAULT NULL	—
4	creator	VARCHAR(128) DEFAULT NULL	—
5	create_time	DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)	—
6	modify_user_id	BIGINT DEFAULT NULL	—
7	updater	VARCHAR(128) DEFAULT NULL	—
8	modify_time	DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6)	—
9	delete_flag	INT NOT NULL DEFAULT 0	—
10	remark	VARCHAR(500) DEFAULT NULL	⚠️ 容易遗漏
11	custom_fields	TEXT DEFAULT NULL	⚠️ 容易遗漏

2.3 标准建表模板

CREATE TABLE IF NOT EXISTS `t_demo`
(
    -- ========== 公共字段（对应 BaseEntity，顺序固定，不可省略） ==========
    `id`             BIGINT       NOT NULL COMMENT '主键（雪花算法）',
    `tenant_id`      BIGINT                DEFAULT NULL COMMENT '租户ID（多租户行级隔离）',
    `create_user_id` BIGINT                DEFAULT NULL COMMENT '创建人ID',
    `creator`        VARCHAR(128)          DEFAULT NULL COMMENT '创建人用户名',
    `create_time`    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6) COMMENT '创建时间',
    `modify_user_id` BIGINT                DEFAULT NULL COMMENT '最后修改人ID',
    `updater`        VARCHAR(128)          DEFAULT NULL COMMENT '最后修改人用户名',
    `modify_time`    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) COMMENT '最后修改时间',
    `delete_flag`    INT          NOT NULL DEFAULT 0 COMMENT '逻辑删除（0:未删除 1:已删除）',
    `remark`         VARCHAR(500)          DEFAULT NULL COMMENT '备注',
    `custom_fields`  TEXT                  DEFAULT NULL COMMENT '自定义扩展字段（JSON）',

    -- ========== 业务字段（放公共字段之后） ==========
    `demo_name`      VARCHAR(100) NOT NULL COMMENT '示例名称',
    `demo_code`      VARCHAR(50)  NOT NULL COMMENT '示例编码（租户内唯一）',
    `demo_type`      VARCHAR(20)           DEFAULT NULL COMMENT '示例类型（A:类型A B:类型B）',
    `status`         INT          NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用）',

    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_tenant_demo_code` (`tenant_id`, `demo_code`),
    KEY `idx_demo_name` (`demo_name`),
    KEY `idx_status` (`status`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='示例表';

2.4 公共字段 Java 映射（BaseEntity 自动填充）

SQL 字段	Java 属性	填充时机	说明
id	id	INSERT	雪花算法，无需手动赋值
tenant_id	tenantId	INSERT	从 TenantContext 自动获取
create_user_id	createUserId	INSERT	自动填充
creator	creator	INSERT	创建人用户名，自动填充
create_time	createTime	INSERT	自动填充
modify_user_id	modifyUserId	INSERT + UPDATE	自动填充
updater	updater	INSERT + UPDATE	最后修改人，自动填充
modify_time	modifyTime	INSERT + UPDATE	自动填充
delete_flag	deleteFlag	逻辑删除标记	@TableLogic，查询自动追加 AND delete_flag=0
remark	remark	手动赋值	通用备注
custom_fields	customFields	手动赋值	JSON 扩展字段，配合表单设计器

---

三、字段设计规范

3.1 字段类型映射

数据库类型	Java 类型	适用场景
VARCHAR(N)	String	字符串，N 根据业务设定
TEXT	String	长文本（> 500 字符）
INT	Integer	整数（状态、数量等）
BIGINT	Long	主键、ID、大整数
DATETIME	LocalDateTime	日期时间
DATE	LocalDate	仅日期
DECIMAL(M,D)	BigDecimal	金额、精确小数（禁止用 Double）
TINYINT(1)	Boolean	布尔值

3.2 字段命名

• 数据库列：蛇形命名，如 demo_name、create_time
• Java 字段：驼峰命名，如 demoName、createTime
• MyBatis-Plus 全局开启 camel-case-column-map，自动完成两者映射

3.3 枚举值约定

枚举值使用整数存储，字段注释中说明含义：

`status`     INT NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用）',
`order_type` INT DEFAULT NULL COMMENT '订单类型（1:普通订单 2:定制订单 3:补单）',

3.4 状态字段

• 通用状态字段名：status
• 约定：0 为正常/启用，1 为禁用/停用

---

四、索引设计规范

索引类型	命名格式	示例
主键	PRIMARY KEY (id)	—
唯一键	uk_{表简称}_{列名}	uk_tenant_demo_code
普通索引	idx_{列名}	idx_demo_name、idx_status
联合索引	idx_{列1}_{列2}	idx_tenant_status

多租户唯一键必须包含 tenant_id：

UNIQUE KEY `uk_tenant_demo_code` (`tenant_id`, `demo_code`)

---

五、菜单与字典 DML 规范

5.1 存放位置

菜单和字典 DML 维护在 nebula-system 项目的迁移脚本中，不放在业务服务的迁移脚本里：

nebula-system-server/src/main/resources/db/migration/

5.2 菜单插入模板

-- 一级目录菜单
INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, path, component, sort_order, visible, status)
VALUES (40000, 0, 'M', 'LTC管理', '', '/ltcapp', '', 10, 1, 1);

-- 二级功能菜单
INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, path, component, sort_order, visible, status)
VALUES (40001, 40000, 'C', '示例管理', 'ltc:demo:query', '/ltcapp/demo', 'ltcapp/demo', 1, 1, 1);

-- 权限按钮（menu_type = 'F'）
INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
VALUES (40010, 40001, 'F', '新增', 'ltc:demo:create', 1);

INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
VALUES (40011, 40001, 'F', '修改', 'ltc:demo:update', 2);

INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
VALUES (40012, 40001, 'F', '删除', 'ltc:demo:delete', 3);

权限标识格式： {业务域}:{资源}:{操作}

常用操作：query（查询）、create（新增）、update（修改）、delete（删除）、export（导出）

5.3 字典插入模板

-- 字典类型
INSERT INTO sys_dict_type (id, dict_name, type_code, status, remark)
VALUES (100, '示例类型', 'demo_type', 0, '示例模块使用的类型字典');

-- 字典项
INSERT INTO sys_dict_item (dict_type_id, item_label, item_value, sort_order, status)
VALUES (100, '类型A', 'A', 1, 0);

INSERT INTO sys_dict_item (dict_type_id, item_label, item_value, sort_order, status)
VALUES (100, '类型B', 'B', 2, 0);

---

六、字段变更脚本规范

-- 新增列（安全，不影响现有数据）
ALTER TABLE `t_demo`
    ADD COLUMN `new_field` VARCHAR(100) DEFAULT NULL COMMENT '新字段说明'
    AFTER `demo_code`;   -- 指定插入位置

-- 修改列注释（不修改类型，最安全）
ALTER TABLE `t_demo`
    MODIFY COLUMN `status` INT NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用 2:待审核）';

-- 新增索引
ALTER TABLE `t_demo`
    ADD INDEX `idx_new_field` (`new_field`);

-- 新增唯一键
ALTER TABLE `t_demo`
    ADD UNIQUE KEY `uk_tenant_new_field` (`tenant_id`, `new_field`);

注意：

• 生产环境禁止 DROP COLUMN / DROP TABLE（需单独审批）
• 不允许修改已提交的 Flyway 脚本，必须新建版本文件来变更
• 字段变更后对应更新 Java DO 类和相关 VO 类