外观
数据库设计规范
2026-04-01
适用于所有 Nebula 框架业务项目的数据库脚本编写规范。
读完本文,你将掌握 Flyway 版本管理、DDL 建表标准格式(含 BaseEntity 11 个公共字段)、索引设计,以及菜单/字典初始化 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 类
