数据库设计规范与表结构变更
校对日期:2026-11-16。适用于社区版及全部商业版。
UJCMS 的表结构不靠手工执行 SQL 维护:建表、加字段都写在 Liquibase 的变更日志里,程序启动时自动执行。 二次开发新增表时,表名、字段名和字段类型要遵守本文的约定,后端的通用查询和实体类映射都依赖这些约定。 模块与包的位置见源码结构与分层。
一、命名规范
查询解析器(com.)根据实体的名称直接推算表名、字段名和关联条件,不查配置。 比如查询条件 Like_ 会被解析成“关联 ujcms_user 表,条件是 t.user_,比较 username_ 列”。 所以下面的规则不是风格建议,不遵守时列表查询、排序和关联查询会拼出错误的 SQL。
| 规则 | 例子 |
|---|---|
表名全部小写,单词之间用下划线分隔,以 ujcms_ 开头 | ujcms_article、ujcms_ |
| 字段名全部小写,单词之间用下划线分隔,以下划线结尾 | name_、publish_date_ |
主键是名为 id_ 的单个字段,没有业务含义 | id_ |
| 多对多的关联表用双方的外键做联合主键 | ujcms_user_role 的 user_id_ + role_id_ |
外键字段以 _id_ 结尾,通常是“被引用的表名 + _id_” | ujcms_ 引用 ujcms_channel |
| 同一张表有多个字段引用同一张表时,在前面加限定词 | user_id_、modified_;ujcms_ 的 ancestor_id_、descendant_id_ |
布尔字段不加 is_ 前缀 | enabled_,不是 is_enabled_ |
字段名以下划线结尾,是为了不与数据库的关键字(order、type、name 等)冲突。实体类的属性名是去掉末尾下划线后的驼峰写法: publish_date_ 对应 publishDate,表 ujcms_ 对应实体 LinkGroup。
索引和约束的命名,现有的表是这样做的:索引 idx_<表>_<字段>,唯一约束 uk_<表>_<字段>,外键 fk_<表>_<被引用的表>, 其中的表名去掉 ujcms_ 前缀和下划线,如 idx_、fk_link_group。
自己新增的表同样用 ujcms_ 前缀。为了不与以后官方新增的表重名,可以在前缀后面加上项目自己的词,如 ujcms_。
二、字段类型
变更日志里写的是 Liquibase 的类型,由 Liquibase 按实际使用的数据库转换成对应的类型。现有的表只用下面几种:
| 用途 | 变更日志中的类型 | 实体类属性 | Mapper XML 的 jdbcType |
|---|---|---|---|
| 主键、外键 | BIGINT | Long | BIGINT |
| 字符串 | VARCHAR(n) | String | VARCHAR |
| 大文本 | MEDIUMTEXT | String | LONGVARCHAR |
| 整数 | INT | Integer | INTEGER |
| 状态、类型等固定取值 | SMALLINT | Short | SMALLINT |
| 布尔 | CHAR(1) | Boolean | CHAR |
| 日期时间 | datetime | OffsetDateTime | TIMESTAMP |
- 主键 的值由程序生成(一般用雪花算法,见主键生成),不使用数据库的自增字段。
- 布尔 字段存
'1'(是)和'0'(否),设为非空并给默认值。jdbcType写成CHAR的Boolean属性由com.负责转换。ujcms. common. db. CharBooleanTypeHandler - 固定取值 的字段(状态、类型)用数字表示,各取值的含义写在字段备注里,如
类型(1:。文字链接, 2: 图片链接) - 字符串长度 按字节留:保存中文的字段,长度取“允许的字数 × 3”,实体类上的
@Length写字数。如名称允许 50 个字, 字段是VARCHAR(150),属性上是@Length(max = 50)。只保存英文、数字的字段(网址、编码、散列值)按实际长度写, 如VARCHAR(255)对应@Length(max = 255)。 - 每个字段和每张表都写备注(
remarks),实体类属性的注释与它保持一致。
三、变更日志的位置
变更日志在 ujcms-cms/:
db.changelog-master.是入口,只有一串yaml include,按顺序引入其它文件。db.changelog-10.是 10.0 版的完整表结构;之后的改动每个主题一个文件,命名为0-whole. yaml db.changelog-<版本>-<主题>.,如yaml db.changelog-13.。0-link-group. yaml - 商业版功能的表也在这里建,
ujcms-commercial模块没有自己的变更日志。
程序每次启动时,Liquibase 按入口文件的顺序检查每个变更集(changeSet):没有执行过的就执行,执行过的跳过。 执行记录保存在数据库的 databasechangelog 表里,以变更集的 id、author 和所在文件路径作为标识,并保存内容的校验和。
四、新建一张表
在
db/changelog/下新建一个文件,如db.changelog-acme-order.(文件名不要与官方的文件重名)。yaml 写建表的变更集。下面是
db.changelog-13.里建0-link-group. yaml ujcms_表的写法(省略了部分字段, 为便于阅读调整了各项的先后顺序):link_ group yamldatabaseChangeLog: - changeSet: id: 13.0-link-group-table author: PONY changes: - createTable: tableName: ujcms_link_group remarks: 链接组表 columns: - column: name: id_ type: BIGINT remarks: 链接组ID constraints: nullable: false primaryKey: true - column: name: site_id_ type: BIGINT remarks: 站点ID constraints: nullable: false - column: name: name_ type: VARCHAR(150) remarks: 名称 constraints: nullable: false - column: name: type_ type: SMALLINT remarks: 类型(1:文字链接,2:图片链接) defaultValueNumeric: 1 constraints: nullable: false布尔字段的默认值写成字符串,如同一个文件里
ujcms_link表的enabled_:yaml- column: name: enabled_ type: CHAR(1) remarks: 是否启用 defaultValue: '1' constraints: nullable: false索引和外键各写一个变更集,放在建表之后(同一个文件里的写法,有删节):
yaml- changeSet: id: 13.0-link-group-indexes author: PONY changes: - createIndex: tableName: ujcms_link_group indexName: idx_linkgroup_site columns: - column: name: site_id_ - changeSet: id: 13.0-link-group-fk author: PONY changes: - addForeignKeyConstraint: baseTableName: ujcms_link_group baseColumnNames: site_id_ constraintName: fk_linkgroup_site referencedTableName: ujcms_site referencedColumnNames: id_ onDelete: RESTRICT onUpdate: RESTRICT在
db.changelog-master.的末尾加一段yaml include:yaml- include: file: db.changelog-acme-order.yaml relativeToChangelogFile: true重新启动程序,表即被创建。
变更集的 id 在同一个文件里不能重复,现有文件用“版本-主题-动作”的形式(13.0-link-group-table),author 写自己的名字。 完整的例子直接看 db.changelog-13.:建两张表、建索引、建外键、迁移旧表的数据、删除旧表,各是一个变更集。
五、修改已有的表
加字段、改类型、加索引都通过追加新的变更集完成,写在自己的文件里,或者在自己的文件末尾继续追加。 下面是 db.changelog-13. 给 ujcms_user_ext 表加一个字段的完整内容:
databaseChangeLog:
- changeSet:
id: 13.1-user-preferences
author: PONY
preConditions:
- onFail: MARK_RAN
- not:
- columnExists:
tableName: ujcms_user_ext
columnName: preferences_
changes:
- addColumn:
tableName: ujcms_user_ext
columns:
- column:
name: preferences_
remarks: 控制台偏好JSON
type: MEDIUMTEXTpreConditions 这一段的意思是:字段已经存在时不执行,只把变更集记为已执行。开发过程中已经手工加过字段的数据库,靠它避免重复加字段报错。
两条规则:
- 已经执行过的变更集不要再修改。 Liquibase 发现内容与记录的校验和不一致时会拒绝启动。要改就追加一个新的变更集。 只有还没有在任何需要保留的数据库上执行过的变更集(比如刚写完、只在本机开发库跑过)才可以直接改:改完后把开发库里对应的表删掉, 并删除
databasechangelog表里这个变更集的记录,再启动。 - 不要修改官方的变更日志文件。 升级版本时这些文件会被新版本覆盖,改动会丢失,或者因为校验和不一致而无法启动。 自己的改动放在自己的文件里,升级时只需要在新版本的
db.changelog-master.末尾重新加上自己的yaml include。
改了表结构之后,实体类的基类和 Mapper XML 里与字段绑定的部分要一起改。
六、常见问题
- 可以不用 Liquibase,直接执行 SQL 建表吗? 可以,程序不检查表是不是由变更日志创建的。但这样每个环境(开发、测试、生产) 都要手工执行一遍,在空数据库上全新安装时也不会有这张表;SQL 里的类型还要自己保证与上面的约定一致。只在一个数据库上使用的简单扩展可以这样做, 其它情况建议写变更日志。
- 启动时停在
Waiting for changelog lock...,或报Could not acquire change log lock。 上一次启动在更新表结构的过程中被强行中止, 锁没有释放。处理方法见 Jar 部署的“常见问题”一节。