聚合数据库设计原则
本文档介绍使用 Pragmatic DDD 进行聚合数据库设计的最佳实践:先明确「一个聚合对应一组表、一张主表还是多张子表」的判定标准,再逐个值对象决定「展开成列还是整列 JSON」,最后落到表结构规范、复杂类型存储形态与一致性策略。
全文分两层判定:第一层(§2)集合怎么落表;第二层(§3)值对象怎么落列。两层相互独立,先定第一层,再逐个值对象定第二层。
1. 核心原则:表边界 = 聚合边界
一个聚合对应一组表:聚合根一张主表,聚合内有独立身份的实体各自成一张子表,无身份的内嵌值对象并入父表。数据库表的设计跟随聚合边界,聚合是多表还是单表,不是拍脑袋,而是由聚合内子对象的形态决定。
Order 聚合
├─ t_order 聚合根主表(基础列 + 金额展开列 + Customer/Address 等 JSON + search_* 生成列 + version)
└─ t_order_item 聚合内子实体表(OrderItem,有独立 id,TrackedList 差量同步)不跨聚合建物理外键:聚合间通过 ID 引用(如 Order 持有 customerId),表之间不建立物理外键约束,一致性由应用层 + 单聚合事务保证。
2. 第一层判定:集合怎么落表
一个聚合到底该一张表还是多张表,用下面的判定标准递进判断。
2.1 判定一:子对象是否有独立 DB 行
先看子对象有没有独立行身份。框架的 TrackedList 类注释给出了明确边界:
TrackedList只针对有独立 DB 行的对象类型(实体或独立表值对象),不处理基础类型或无身份的内嵌值对象。内嵌值对象的集合整体随父表替换,无需本容器。
| 子对象形态 | 表设计 | 例子 |
|---|---|---|
| 有独立 ID、独立行的实体 | 独立子表 | OrderItem(有 id,可单独 INSERT/DELETE) |
| 无身份的内嵌值对象 | 父表 JSON 列 | Customer、Address、Money 等 IValueObject |
Order 的取舍:OrderItem 有 id、order_id、独立行,能被增删 → 独立子表 t_order_item;Customer、Address、Money 是内嵌值对象,没有独立身份,不单独成表 → 整列 JSON 存在 t_order 上。
2.2 判定二:子实体是否需要独立访问
即使有 ID,还要看它的生命周期是否跟父聚合一致:
- 子实体只在父聚合上下文中存在,从不被单独查询、单独更新、单独引用 → 留在聚合内,用子表 +
TrackedList差量。 - 子实体可能被其他聚合独立访问(单独查、被别的聚合引用)→ 说明它可能是独立聚合,应拆出去,而不是硬塞进当前聚合。
Order 里 OrderItem 只在订单上下文存在,随订单一起增删,→ 归属订单聚合的子表。
2.3 判定三:单表 vs 多表的读写取舍
单张表(内嵌值对象全用 JSON 列):
- 适用:聚合根内部全是无身份值对象,没有需独立行的子实体。
- 优点:表少、join 少、一次读完整聚合、事务简单。
- 缺点:JSON 列内的字段无法用 SQL 单独过滤/索引/统计。
多张表(子实体独立子表):
- 适用:聚合内有有独立身份的实体(如
OrderItem),需增删、数量可能很多、要按子行过滤/统计。 - 优点:子行可单独 CRUD(
TrackedList差量)、可按子表字段建索引查询、避免 JSON 列过大。 - 缺点:表多、需级联维护、事务跨表。
2.4 多张表的"多"怎么定
不是"一个实体一张表"无限铺开,而是:
- 聚合根 = 一张主表(
t_order):聚合根自身字段 + 内嵌值对象(JSON 列)。 - 每个有独立身份的聚合内实体 = 一张子表(
t_order_item)。 - 一个实体只归属一个聚合、只一张表,不会出现在多张表重复存储。
3. 第二层判定:值对象怎么落列(形态 A / B)
集合落表定下来后,再逐个值对象决定列形态。选择粒度是值对象,不是表、不是聚合:同一张表可以混用两种形态,但同一个值对象只能选一种(不允许 JSON + 同义展开列双存)。
3.1 两种形态
| 项 | 形态 A:展开平铺 | 形态 B:JSON + 派生列 |
|---|---|---|
| 值对象怎么落 | 拆成业务事实列 | 整列 JSON / JSONB |
| 写权威 | 列 | JSON |
| 查询列 | 列本身 | search_* 生成列(只许生成列,不许自建) |
| 加字段成本 | DDL 迁移 | 零 DDL |
| 改结构成本 | DDL 迁移 | 数据迁移(JSON_SET / jsonb_set) |
| 数据库级约束 | 原生支持 | 生成列 + 唯一索引 |
| BI 直连 | 友好 | 不友好(需视图) |
| 子表适用 | 适用 | 适用 |
默认形态是 B;A 是准入制,满足 §3.4 的判据才能用。
3.2 形态 A 的硬规则
- 同一值对象的全部列必须在同一条 INSERT / UPDATE 内写全——部分列更新会在并发下产生「半个值对象」;
- resultMap 用嵌套映射(多列 → 值对象属性),领域层不感知列,
equalityComponents()不变; - 可空性与 DDL 对齐:值对象里不可空的字段,列必须
NOT NULL; - 不得再给该值对象建同义生成列——列已是权威,再挂派生列就是两个来源。
-- Money 展开为两列
amount_value DECIMAL(18, 2) NOT NULL COMMENT '金额数值(元)',
currency CHAR(3) NOT NULL COMMENT '币种'<!-- 多列 → 一个值对象:嵌套属性映射,不走 JSON TypeHandler -->
<result property="totalAmount.amount" column="amount_value"/>
<result property="totalAmount.currency" column="currency"/>写入侧必须成对出现:#{totalAmount.amount} / #{totalAmount.currency},且在同一条语句里。
3.3 形态 B 的硬规则
- JSON 是唯一写入口:值对象整体替换,不做
JSON_SET式局部更新; search_*只能是生成列:由库从 JSON 推导,应用不写;- 生成列不进领域模型、不进 INSERT / UPDATE、不得用
SELECT *:它只被查询侧使用,写回聚合即退化成第二事实源; - 每个生成列必须建索引,且每表
search_*预算 ≤ 5; - 生成列只能做单行内、确定性的推导(见 §3.5 能力缺口)。
-- MySQL 8:JSON_EXTRACT 是确定性的,STORED 可建索引
ALTER TABLE t_order
ADD COLUMN search_amount DECIMAL(18, 2)
GENERATED ALWAYS AS (CAST(JSON_UNQUOTE(JSON_EXTRACT(actual_amount, '$.amount')) AS DECIMAL(18, 2))) STORED,
ADD KEY idx_order_search_amount (search_amount);-- PostgreSQL:必须是 immutable 函数;json_extract_path_text 是 stable,不能用于生成列
ALTER TABLE t_order
ADD COLUMN search_amount NUMERIC(18, 2)
GENERATED ALWAYS AS (((actual_amount ->> 'amount')::numeric)) STORED;
CREATE INDEX idx_order_search_amount ON t_order (search_amount);STORED 还是 VIRTUAL:需要等值 / 范围过滤默认 STORED(可建索引、读无额外计算);仅取值计算、不建索引时用 VIRTUAL。
3.4 判据:默认 B,A 需准入
| 判据(满足任一才用 A) | 说明 |
|---|---|
| 该值对象全部字段都是查询 / 约束依据 | 不是「个别字段要查」 |
| 该值对象结构极稳定(预计一年不变) | 如 Money、GeoPoint、DateRange |
| 需要数据库级约束(唯一 / 非空 / 条件约束) | JSON 表达不了 |
| 外部系统必须直连平表且不允许加视图 | 且只用于只读副本表 |
一句话:A 给稳定的核心值对象,B 给演进中的业务数据。
3.5 生成列解决不了的需求(必须转读侧)
| # | 需求 | 为什么生成列做不到 | 正确解法 |
|---|---|---|---|
| G1 | 跨行汇总(如订单总额 = Σ 明细) | 不能跨行 / 子查询 | 视图 / 直读 JOIN / 同事务内维护业务事实列 |
| G2 | 外部数据(客户名、汇率、字典翻译) | 依赖其他表或外部系统 | 读侧 JOIN / ES 投影;不进写表 |
| G3 | 全文 / 分词检索 | 生成列只能等值 / 前缀 | MySQL FULLTEXT、PG GIN(to_tsvector(...))、ES |
| G4 | JSON 数组包含查询 | 生成列产出标量 | MySQL 多值索引、PG GIN |
两个易踩的细节:枚举 name 不用 CASE 生成列(枚举一加值就要改 DDL,改为读侧 of(code).getName() 回填);时区 / 本地日期统一 UTC 存、读侧换算。
3.6 迁移:A 与 B 之间没有免费通道
| 方向 | 步骤 | 代价 |
|---|---|---|
| B → A | 加列 → 回填 → 改 resultMap / SQL → 切写 → 删 JSON | 高,需窗口或双写期 |
| A → B | JSON_SET 回填 JSON → 双读兼容 → 切写 → 删列 | 高,需窗口或双写期 |
因此形态必须在设计期定,不做「先随便选一个」。
3.7 台账:形态从 DDL 反推,判据留在设计里
实际形态能从表结构读出来(展开列 vs JSON 列一目了然;GENERATED ALWAYS AS 即 search 生成列),所以不需要另存一份现状台账:
| 读什么 | 从哪儿读 |
|---|---|
| 表形态 | DDL:整列 JSON = B 型;多列展开 = A 型 |
| search 列台账 | DDL 里带 GENERATED ALWAYS AS 的列 + 其索引 |
而为什么这么选(准入判据)不可反推,它登记在写设计 §7.1 的落列形态决策表里,属契约内容。
4. 合理性三问检验法
一组表设计得是否合理,用三个问题检验,都通过才算合理:
- 一致性:这一组表是否总能在同一个事务内保持一致?→ Order 两张表在
@Transactional内整存整取,能保证。 - 边界:子实体是否从不被聚合外单独访问/修改?→
OrderItem只随Order增删,成立。 - 读写:有没有因"一张表塞太多 JSON 导致没法查"或"多张表 join 太重"?→ Order 子表可独立过滤,合理。
若某个子实体越界被独立访问,或某块数据只是"临时聚合"不需要一致性,就应拆成独立聚合/独立表,而不是硬塞进聚合。
一句话:一张主表 + N 张子实体表(N = 聚合内独立实体数),并以"同一事务一致性 + 边界不外泄 + 读写顺畅"三项检验合理性。
形态复核:每个值对象是否已按 §3.4 选定 A / B 并写入写设计 §7.1 决策表;未写即视为未完成。
5. 表结构设计规范
5.1 主键与标识
聚合根与子实体的唯一标识均支持两种落地模式,由项目按需选用,本文不替用户做取舍(命名统一为 {聚合名}_id,如订单聚合为 order_id、订单项为 order_item_id)。
- 聚合根表标识列 =
order_id,两种模式:- 模式一:
order_id为AUTO_INCREMENT主键,直接作为聚合根entityId,ID 落库后由数据库生成(ID 后生成)。因 ID 后置,需由仓储在插入后通过 MyBatis 自增键回填(useGeneratedKeys)将order_id写回聚合根entityId、将order_item_id写回子实体,再回填子表order_id逻辑外键(详见 §7)。 - 模式二:
id为AUTO_INCREMENT主键(物理行号),另设order_id为唯一索引(UNIQUE KEY,=entityId),由应用层/IdSegmentMapper落库前代码生成。
- 模式一:
- 子实体表自身标识(
order_item_id)同样适用上述两种模式。 - 子表指向父聚合的列(
order_id)始终是逻辑外键(过滤键),不是领域属性,不映射进OrderItem,仅用于查询与级联;它不受上面两种模式影响,聚合根标识走何种模式该列都不变。
5.2 字段与列映射
- 值对象默认整列 JSON(形态 B);只有满足 §3.4 准入的才展开成列(形态 A),粒度是值对象不是字段。
- 派生列只能是生成列:
search_*由 JSON 推导,不进领域模型、不进 INSERT / UPDATE、不用SELECT *。 - 显式映射:列名下划线、属性驼峰,靠
mapUnderscoreToCamelCase自动映射 + 显式 resultMap;A 型值对象用嵌套属性映射(totalAmount.amount)。 - 逻辑外键不入领域:
order_id(对子实体而言)是查询过滤键,不纳入 resultMap 显式映射、不作为领域属性。 - 审计列统一:
created_at/created_by/updated_at/updated_by四列由框架父类托管,表必须预留。 - 版本列:聚合根表必须有
version列,作为乐观锁基线(读入oldVersion,更新时 CAS)。 - 业务唯一号与
entity_id区分:两者不同时,业务号单独成列 + 唯一索引;不要塞进 JSON。
5.3 建表示例(Order)
聚合根
order_id与子实体order_item_id的标识支持两种模式,下面各给一份完整建表语句,差异仅在标识列;其余业务列、search_*生成列、version、审计列两种模式一致。
-- 模式一:DB 自增列 = entityId(ID 后生成)
CREATE TABLE t_order (
order_id BIGINT NOT NULL AUTO_INCREMENT COMMENT '订单标识(聚合根 entityId,插后生成)',
customer JSON NOT NULL COMMENT '客户值对象(B)',
status INT NOT NULL COMMENT '订单状态(枚举 CODE)',
shipping_address JSON NULL COMMENT '收货地址值对象(B)',
amount_value DECIMAL(18, 2) NOT NULL COMMENT '实付金额数值(A:Money 展开)',
currency CHAR(3) NOT NULL COMMENT '币种(A:Money 展开)',
remark VARCHAR(255) NULL,
paid_at DATETIME NULL,
payment_method INT NULL COMMENT '支付方式(枚举 CODE)',
search_customer_id BIGINT
GENERATED ALWAYS AS (CAST(JSON_UNQUOTE(JSON_EXTRACT(customer, '$.customerId')) AS UNSIGNED)) STORED
COMMENT '派生列:按客户筛选(生成列,不进领域模型)',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(64) NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(64) NULL,
version BIGINT NOT NULL DEFAULT 1 COMMENT '乐观锁版本',
PRIMARY KEY (order_id),
KEY idx_order_search_customer (search_customer_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '订单聚合根表';
-- 聚合内子实体表:t_order_item(模式一)
CREATE TABLE t_order_item (
order_item_id BIGINT NOT NULL AUTO_INCREMENT COMMENT '订单项标识(子实体 entityId,插后生成)',
order_id BIGINT NOT NULL COMMENT '逻辑外键(查询过滤键,非领域属性)',
product_id BIGINT NOT NULL,
product_name VARCHAR(128) NOT NULL,
spec VARCHAR(64) NULL,
price JSON NULL COMMENT '金额值对象',
quantity INT NOT NULL,
subtotal JSON NULL COMMENT '金额值对象',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(64) NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(64) NULL,
PRIMARY KEY (order_item_id),
KEY idx_order_id (order_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '订单项子实体表';
-- 模式二:代码生成 entityId + 物理自增列(id 为主键,order_id / order_item_id 为唯一索引)
CREATE TABLE t_order (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '物理自增主键(行号,非 entityId)',
order_id BIGINT NOT NULL COMMENT '订单标识(聚合根 entityId,代码生成,落库前已知)',
customer JSON NOT NULL COMMENT '客户值对象(B)',
status INT NOT NULL COMMENT '订单状态(枚举 CODE)',
shipping_address JSON NULL COMMENT '收货地址值对象(B)',
amount_value DECIMAL(18, 2) NOT NULL COMMENT '实付金额数值(A:Money 展开)',
currency CHAR(3) NOT NULL COMMENT '币种(A:Money 展开)',
remark VARCHAR(255) NULL,
paid_at DATETIME NULL,
payment_method INT NULL COMMENT '支付方式(枚举 CODE)',
search_customer_id BIGINT
GENERATED ALWAYS AS (CAST(JSON_UNQUOTE(JSON_EXTRACT(customer, '$.customerId')) AS UNSIGNED)) STORED
COMMENT '派生列:按客户筛选(生成列,不进领域模型)',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(64) NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(64) NULL,
version BIGINT NOT NULL DEFAULT 1 COMMENT '乐观锁版本',
PRIMARY KEY (id),
UNIQUE KEY uk_order_id (order_id),
KEY idx_order_search_customer (search_customer_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '订单聚合根表';
-- 聚合内子实体表:t_order_item(模式二)
CREATE TABLE t_order_item (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '物理自增主键(行号)',
order_item_id BIGINT NOT NULL COMMENT '订单项标识(子实体 entityId,代码生成)',
order_id BIGINT NOT NULL COMMENT '逻辑外键(查询过滤键,非领域属性)',
product_id BIGINT NOT NULL,
product_name VARCHAR(128) NOT NULL,
spec VARCHAR(64) NULL,
price JSON NULL COMMENT '金额值对象',
quantity INT NOT NULL,
subtotal JSON NULL COMMENT '金额值对象',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(64) NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(64) NULL,
PRIMARY KEY (id),
UNIQUE KEY uk_order_item_id (order_item_id),
KEY idx_order_id (order_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '订单项子实体表';6. 复杂类型的存储形态
复杂类型通过 TypeHandler 三通道落地,存储形态由对象性质决定:
| 类型 | 存储形态 | 通道 | 说明 |
|---|---|---|---|
| 单列枚举 | 整数值 | 枚举通道(EnumRule.CODE) | status、payment_method 存业务 value |
| 内嵌值对象 · 形态 B | 整列 JSON | JSON 通道(GenericJsonTypeHandler) | 默认;Customer、Address 等 IValueObject |
| 内嵌值对象 · 形态 A | 多列展开 | resultMap 嵌套属性映射 | 需全列同写;Money、GeoPoint 等稳定值对象 |
| JSON 内字段的查询列 | search_* 生成列 | 库自动推导 | 只许生成列,必建索引,不进领域模型 |
| 有独立行的子实体集合 | 独立子表 | TrackedList 差量同步 | OrderItem,只发增量 INSERT/DELETE |
| 无身份值对象集合 | 单列 JSON 数组 | 集合通道(ListTypeHandler) | 如颜色列表,整列 JSON,不建子表 |
判定核心:有独立身份、需独立行 → 子表;无身份、随父表替换 → JSON 列。不要为无身份值对象集合建子表,也不要把有独立身份的实体压进 JSON 列。
7. 一致性策略
- 无物理外键:靠应用层事务 + 仓储级联(先子后主)保证一致性,避免孤儿行。
- 乐观锁:聚合根表
version列做 CAS,冲突抛OptimisticLockingFailureException。 - 子集合差量:
TrackedList只发增量 INSERT/DELETE,不整表覆盖。 - 标识模式与整存整取顺序:两种标识模式对仓储整存整取的顺序要求不同。
- 模式一(ID 后生成):必须先插入主表,再通过 MyBatis 自增键回填(
useGeneratedKeys+keyProperty="entityId")将数据库生成的自增order_id写回聚合根entityId;随后以该order_id回填子表逻辑外键,并批量插入子实体,同样用useGeneratedKeys把order_item_id写回TrackedList内子实体,使内存聚合与 DB 行一致;TrackedList差量基于加载态计算。 - 模式二(代码生成):
order_id/order_item_id(唯一索引)落库前已知,物理主键id自增但不参与领域;主表与子表逻辑外键可先行填充,插入顺序无约束,无需回填。
- 模式一(ID 后生成):必须先插入主表,再通过 MyBatis 自增键回填(
8. 常见反模式
| 反模式 | 问题 | 正确做法 |
|---|---|---|
| 为无身份值对象建子表 | 表爆炸、join 重 | 并入父表 JSON 列 |
| 把有独立身份的实体塞进 JSON 列 | 无法按子行过滤/统计/增删 | 独立子表 + TrackedList |
| 跨聚合建物理外键 | 锁竞争、性能差、边界模糊 | 只保留 ID 引用,无外键约束 |
| 一个实体在多张表重复存储 | 数据冗余、一致难保证 | 一个实体只归属一个聚合、一张表 |
| 子表不加逻辑外键索引 | 子表过滤慢 | order_id 建普通索引 |
聚合根表缺 version 列 | 乐观锁失效 | 预留版本列做 CAS |
| 表缺审计列 | 无法追踪 | 预留 created_at/by、updated_at/by |
| 逻辑外键映射进子实体 | 领域模型污染 | 逻辑外键不入领域、不入 resultMap |
| 同一值对象既 JSON 又手写展开列 | 两个写入口,必然漂移 | 一个值对象只选一种形态 |
自建 search_* 列(应用写) | 派生值与 JSON 双写,必然不一致 | search_* 只能是生成列 |
| 生成列出现在 INSERT / UPDATE,或被映射进聚合 | 派生退化成事实,写回会覆盖权威值 | 生成列只读、只给查询侧 |
建了 search_* 却不建索引 | 等于没加,还多一份维护成本 | 每个生成列配一个索引 |
| 展开式写值对象时只更新部分列 | 并发下产生半个值对象 | 同一值对象全列同一条语句写全 |
| 用生成列做跨行汇总 / 字典翻译 / 全文检索 | 生成列只能做单行确定性推导 | 转读侧:视图 / 直读 / ES / FULLTEXT / GIN |
search_* 里放手机号、证件号等敏感字段 | 绕过列级脱敏与权限 | 敏感字段不进派生列,按需脱敏后再派生 |
下一步
- 聚合设计原则:聚合根边界、
TrackedList子集合、版本号与乐观锁 - 仓储设计原则:仓储如何整存整取聚合、子集合差量同步
- MyBatis 配置设计原则:TypeHandler 三通道装配、全局开关与框架固定 Mapper
- 值对象最佳实践:值对象 JSON 序列化往返
- 枚举值:枚举按 CODE 持久化
- Outbox 链路装配:
OutboxMapper与异构事件投递