最佳实践模式库
这里是一套可落地的模式库：每篇文档把一个框架能力点写成一条落地模式（原则 + 代码骨架 + ⚠️约束 + 反模式），读者照着即可生成正确代码。新模块开发 = 查模式 + 套模板——把示例中的聚合 / 存储替换成目标场景，即得新实现（举一反三）。
模式链路
从聚合建模到事件一致性，本模式库覆盖全链路：
text
写模型建模 → 业务规则与校验 → 应用编排 → 持久化 / 读模型 → 基础设施装配 → 事件与一致性上表是代码落地链路；此外 ⑦ 设计文档规范 是横切环节——它不产出代码，而是规定「动手之前那份设计文档该怎么写」，使人可评审、AI 可落地。
| 环节 | 覆盖的落地问题 |
|---|---|
| 写模型建模 | 聚合边界怎么划、表怎么落、实体 / 值对象 / 枚举怎么写、规则码与操作码怎么声明 |
| 业务规则与校验 | 校验规则怎么组织、怎么触发、外部依赖校验怎么接入 |
| 应用编排 | 应用服务层怎么与聚合协作、操作/事件顺序与工作单元清理 |
| 持久化 / 读模型 | 写模型仓储怎么实现、聚合到异构存储的读模型怎么落 |
| 基础设施装配 | MySQL / Elasticsearch / RocketMQ / Outbox 的 Bean 怎么装配 |
| 事件与一致性 | 事件怎么建模、跨模块消息怎么可靠投递 |
模式清单
① 写模型建模
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 聚合目录落地骨架 | 新建聚合先初始化目录、按图索骥到各模式 | Order 目录 → 任何聚合目录 |
| 聚合设计原则 | 聚合边界与粒度、框架父类已托管能力、聚合根编码规范 | Order → 任何聚合根 |
| 聚合数据库设计原则 | 表边界 = 聚合边界、字段列映射、复杂类型存储 | 订单多表 → 任何聚合的表结构 |
| 普通实体设计原则 | 聚合内子实体的设计与编码 | OrderItem → 任何聚合内实体 |
| 值对象最佳实践 | 结构相等的可嵌入数据结构、与实体/枚举取舍 | 地址 / 金额 → 任何值对象 |
| 枚举值对象最佳实践 | 用 IEnumValue 替代 Java enum、CODE 持久化 | 订单状态 → 任何离散常量集合 |
| 规则注册表设计 | 校验消息码集中声明、消灭魔法字符串 | Order 规则码 → 任何聚合校验码 |
| 操作注册表设计 | 领域操作集中声明、事件自动归属成因 | 支付/取消操作 → 任何聚合操作 |
| 领域服务落地模式 | 四类领域服务契约怎么声明、应用层怎么实现 | 订单计算/ID生成 → 任何领域能力 |
② 业务规则与校验
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 聚合业务规则（OrderRule 范式） | {聚合}Rule 容器 + {聚合}RuleRegistry + 契约注入，校验规则统一触发 | 订单规则 → 任何聚合规则 |
③ 应用编排
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 应用层落地模式 | WriteService 编排、execute 模板、创建/修改/预校验三场景 | 订单应用服务 → 任何应用服务 |
④ 持久化 / 读模型
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 仓储设计原则 | 写模型仓储定位、框架契约、MyBatis 落地与测试 | 订单仓储 → 任何写模型仓储 |
| 投影读模型代码落地指南 | 聚合 → 异构存储读模型的代码落地，以及读侧三跳取数（选路 / 检索 / 裁剪） | Order + Es → 任何聚合 + 任何异构存储 |
⑤ 基础设施装配
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| MySQL 配置设计原则 | SqlSessionFactory / TypeHandler / 事务管理器装配 | MySQL → 任何数据访问基础设施 |
| Elasticsearch 配置设计原则 | RestClient → Transport → Client 三层构建、认证超时 | ES → 任何外部存储客户端 |
| 事件管理器装配与选择 | IEventManager 二选一装配原则、本地线程池实现与数据丢失风险 | 事件管理器 → 任何应用 |
| RocketMQ 配置设计原则 | 应用级 MQ 装配、主题路由、订阅落地 | Order → MQ → 任何聚合事件 |
| Outbox 链路装配 | 事务性发件箱五个协作 Bean 的装配 | Order → Outbox → 任何聚合事件 |
⑥ 事件与一致性
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 事件建模指南 | 事件只带聚合标识、buildEvent 工厂、即时/延迟事件 | 订单事件 → 任何领域事件 |
| 事件订阅领域服务落地模式 | EVENT_SUBSCRIBER 契约怎么声明、订阅者怎么写、注册表怎么绑定 | 订单发短信/发积分/投影 ES → 任何聚合的事件响应动作 |
⑦ 设计文档规范
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 设计文档编写规范 | 新需求 / 迭代的设计文档怎么组织，人怎么评审、AI 怎么落地 | 订单发货修正设计 → 任何需求的设计文档 |
如何使用
- 找模式：新模块先定位到对应环节（建模 / 规则 / 编排 / 持久化 / 装配 / 事件），找到最贴近的落地模式文档。
- 套模板：把文档中的示例聚合 / 存储替换为目标场景，按代码骨架逐个落地组件。
- 避坑：对照每篇的 ⚠️ 约束与常见反模式表，在实现前预判易错点。
- 验证：落地后按各篇的规则自检，并补充单元测试。