主键生成
校对日期:2026-11-16。适用于社区版及全部商业版。
数据表的主键是 bigint 类型的 id_ 字段,值由程序用雪花算法生成,不使用数据库的自增或序列。这样的主键不依赖具体的数据库, 多个节点可以同时生成而不冲突,也不会从 ID 上暴露数据量。本文说明在自己的代码里怎样取主键、ID 的构成,以及 ID 在接口中为什么是字符串。
一、在代码里取主键
注入 com.,插入之前调用 nextId()。示例表的写法(com.):
java
@Transactional(rollbackFor = Exception.class)
public void insert(Example bean) {
bean.setId(snowflakeSequence.nextId());
mapper.insert(bean);
}SnowflakeSequence是全局唯一的 Spring Bean(在com.中创建),所有表共用,不需要按表区分。ujcms. cms. core. MyBatisConfig nextId()是同步方法,同一进程内生成的 ID 严格递增,按 ID 排序大致就是按创建时间排序。- 主键相同的一对一扩展表直接沿用主表的 ID,如
UserService.中的insert ext.。setId(bean. getId()) - 建表时主键写成
bigint、不设自增;Mapper XML 的insert语句里照常写入id_。
二、ID 的构成
ID 是一个 63 位的正整数,从高到低分为四段:
| 段 | 位数 | 说明 |
|---|---|---|
| 时间戳 | 42 | 自 2020-10-01(北京时间)起经过的毫秒数,可用到 2160 年 |
| 数据中心 ID | 5 | 0~31 |
| 工作节点 ID | 5 | 0~31 |
| 序列号 | 11 | 同一毫秒内的序号,每毫秒最多 2048 个 |
- 每进入新的一毫秒,序列号从 1 或 2 随机开始,避免低并发时生成的 ID 全是偶数。
- 同一毫秒内的序列号用完时,借用下一毫秒继续生成,不等待。
- 系统时钟被回拨时,沿用上一次的时间戳继续生成,不等待也不报错;回拨达到 1 秒时在日志中记录警告。 回拨期间进程如果重启,理论上有可能生成与重启前重复的 ID,所以服务器应当开启时间同步。
SnowflakeSequence.可以从 ID 反推出生成时间(毫秒时间戳)。parseIdTimestamp(id)
三、节点编号
数据中心 ID 和工作节点 ID 合起来标识一个运行中的节点,两个节点的编号相同时可能生成重复的 ID。
- 默认不需要设置:程序根据网卡 MAC 地址、主机名和进程 ID 推算。单机部署用默认值即可。
- 集群部署要在每个节点的配置文件中指定
ujcms.和datacenterId ujcms.workerId,各节点的组合不能重复。 两项必须同时设置,只设置一项时程序启动失败。取值、示例和确认方法见集群部署的“雪花算法节点编号”一节。
四、接口中的 ID 是字符串
雪花 ID 已经超过 JavaScript 能精确表示的最大整数(2^53 - 1,约 9×10^15),以数字输出到浏览器会丢失末几位。 因此所有 Long 类型的值在 JSON 中都输出为字符串(ujcms-starter 的 Application 中注册的 Jackson 序列化器),long[] 输出为字符串数组:
json
{"id": "405429841498667009", "siteId": "1", "channelId": "405429836104792065"}由此带来的约定:
- 前端始终把 ID 当字符串处理,不要转成数字,也不要用数字类型的输入框编辑 ID。
- 提交给后端时照样传字符串,后端的
Long属性和参数可以直接接收。 - 不只是 ID:其它
Long类型的属性(如排列顺序order、分页信息里的总条数)在 JSON 中也是字符串。Integer、Short仍是数字。 - 实体类里要给前端的数值属性,范围不大时用
Integer或Short;用了Long,前端拿到的就是字符串。 - 按 ID 查询时类型写
Long,如EQ_siteId_Long,见查询解析器 QueryParser。
五、不是雪花值的主键
- 系统内置的数据使用固定的小 ID。 安装时写入的站点(ID 为
1)、管理员(ID 为1)、会员用户组(Group.,MEMBER_ GROUP_ID 10)、 会员所属的组织(Org.,MEMBER_ ORG_ID 0)等都是固定值,代码里通过常量引用它们。所以不要假定 ID 一定是很大的数。 - 访问日志使用序列表。
SeqService(com.)用数据表ujcms. cms. core. service ujcms_seq模拟数据库序列,每次从表里取一段号码缓存在内存中, 缓存的数量由ujcms.设置。目前只有访问统计的两张表(sequence-cache-size ujcms_visit_log、ujcms_)使用它,其余的表都用雪花 ID。visit_ page
六、常见问题
前端拿到的 ID 末几位是 0,或者与数据库里的不一样。 某个环节把 ID 转成了数字,例如对接口返回的 ID 用了 Number()、parseInt(),或者别的系统把它当数字存取。全程按字符串处理。
保存数据时报主键冲突(Duplicate entry)。 集群中有节点的编号重复,见“节点编号”一节。