最佳实践模式库
这里是一套可落地的模式库：每篇文档把一个框架能力点写成一条落地模式（原则 + 代码骨架 + ⚠️约束 + 反模式），读者照着即可生成正确代码。新模块开发 = 查模式 + 套模板——把示例中的聚合 / 存储替换成目标场景，即得新实现（举一反三）。
模式链路
从聚合建模到事件一致性，本模式库覆盖全链路：
text
写模型建模 → 业务规则与校验 → 应用编排 → 持久化 / 读模型 → 基础设施装配 → 事件与一致性上表是代码落地链路；此外 ⑦ 设计文档（语义 → 写 / 读 → 事实快照） 与 ⑧ 代码注释规范 是横切环节——⑦ 不产代码，规定「动手之前聚合怎么识别 / 演进，设计文档怎么分三契约 + 一快照写」；⑧ 是横切编码规范，规定领域模型与应用服务「注释写什么、写到什么程度」。两者都服务于人可评审、AI 可落地。
| 环节 | 覆盖的落地问题 |
|---|---|
| 写模型建模 | 聚合边界怎么划、表怎么落、实体 / 值对象 / 枚举怎么写、规则码与操作码怎么声明 |
| 业务规则与校验 | 校验规则怎么组织、怎么触发、外部依赖校验怎么接入 |
| 应用编排 | 应用服务层怎么与聚合协作、操作/事件顺序与工作单元清理 |
| 持久化 / 读模型 | 写模型仓储怎么实现、聚合到异构存储的读模型怎么落 |
| 基础设施装配 | MySQL / PostgreSQL / Elasticsearch / RocketMQ / Outbox 的 Bean 怎么装配 |
| 事件与一致性 | 事件怎么建模、跨模块消息怎么可靠投递 |
模式清单
① 写模型建模
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 聚合目录落地骨架 | 新建聚合先初始化目录、按图索骥到各模式 | Order 目录 → 任何聚合目录 |
| 聚合设计原则 | 聚合边界与粒度、框架父类已托管能力、聚合根编码规范 | Order → 任何聚合根 |
| 聚合数据库设计原则 | 表边界 = 聚合边界、字段列映射、复杂类型存储 | 订单多表 → 任何聚合的表结构 |
| 普通实体设计原则 | 聚合内子实体的设计与编码 | OrderItem → 任何聚合内实体 |
| 值对象最佳实践 | 结构相等的可嵌入数据结构、与实体/枚举取舍 | 地址 / 金额 → 任何值对象 |
| 枚举值对象最佳实践 | 用 IEnumValue 替代 Java enum、CODE 持久化 | 订单状态 → 任何离散常量集合 |
| 规则注册表设计 | 校验消息码集中声明、消灭魔法字符串 | Order 规则码 → 任何聚合校验码 |
| 操作注册表设计 | 领域操作集中声明、事件自动归属成因 | 支付/取消操作 → 任何聚合操作 |
| 领域服务落地模式 | 四类领域服务契约怎么声明、应用层怎么实现 | 订单计算/ID生成 → 任何领域能力 |
② 业务规则与校验
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 聚合业务规则（OrderRule 范式） | {聚合}Rule 容器 + {聚合}RuleRegistry + 契约注入，校验规则统一触发 | 订单规则 → 任何聚合规则 |
③ 应用编排
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 应用层落地模式 | WriteService 编排、execute 模板、创建/修改/预校验三场景 | 订单应用服务 → 任何应用服务 |
④ 持久化 / 读模型
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 仓储设计原则 | 写模型仓储定位、框架契约、MyBatis 落地与测试 | 订单仓储 → 任何写模型仓储 |
| 投影读模型代码落地指南 | 聚合 → 异构存储读模型的代码落地，以及读侧三跳取数（选路 / 检索 / 裁剪） | Order + Es → 任何聚合 + 任何异构存储 |
⑤ 基础设施装配
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| MySQL 配置设计原则 | 数据源、连接池与事务管理器装配 | MySQL → 任何关系型数据库的 JDBC 层 |
| PostgreSQL 配置设计原则 | PG 数据源、方言 XML、databaseId、建表脚本与 TypeHandler 适配 | MySQL → PostgreSQL 的方言装配 |
| MyBatis 配置设计原则 | SqlSessionFactory / TypeHandler 多聚合装配 / Mapper XML 加载（含框架固定 Mapper） | MyBatis → 任何 ORM 会话装配 |
| Elasticsearch 配置设计原则 | RestClient → Transport → Client 三层构建、认证超时 | ES → 任何外部存储客户端 |
| 事件管理器装配与选择 | IEventManager 二选一装配原则、本地线程池实现与数据丢失风险 | 事件管理器 → 任何应用 |
| RocketMQ 配置设计原则 | 应用级 MQ 装配、主题路由、订阅落地 | Order → MQ → 任何聚合事件 |
| Kafka 配置设计原则 | 与 RocketMQ 互斥的应用级 Kafka 装配、消费者组、延时/重试回投器 | Order → Kafka → 任何聚合事件 |
| Outbox 链路装配 | 事务性发件箱五个协作 Bean 的装配 | Order → Outbox → 任何聚合事件 |
⑥ 事件与一致性
| 文档 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|
| 事件建模指南 | 事件只带聚合标识、buildEvent 工厂、即时/延迟事件 | 订单事件 → 任何领域事件 |
| 事件订阅领域服务落地模式 | EVENT_SUBSCRIBER 契约怎么声明、订阅者怎么写、注册表怎么绑定 | 订单发短信/发积分/投影 ES → 任何聚合的事件响应动作 |
| 对外广播落地模式 | 领域事件怎么触发对外广播、信封与订阅者怎么写、topic 怎么定义 | 订单对外广播 → 任何聚合的标准信封推送 |
⑦ 设计文档（识别 → 演进 → 文档标准）
本主题是横切环节：它不产出代码，而是规定「动手之前那份设计文档该怎么写」以及「动笔之前聚合怎么识别 / 演进」，使人可评审、AI 可落地。三者按生命周期排序——先识别聚合、再演进既有聚合，最终落为一份符合《设计文档编写规范》的统一结构文档。
| 文档 | 性质 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|---|
| 聚合识别设计原则 | 方法论（原则） | 全新 / 加聚合时，从需求中识别聚合候选、边界与不变量 | 订单域识别 → 任何域的聚合识别 |
| 聚合演进设计原则 | 方法论（原则） | 既有聚合加操作 / 子实体 / 事件时，设计文档怎么写（对应「修改场景」） | 订单发货修正 → 任何聚合的迭代演进 |
| 设计文档标准（三层） | 文档体系（规范） | 一个聚合的文档分「业务语义 → 写设计 → 投影读设计」三层，各自的职责、边界与推导关系 | 订单三层文档 → 任何聚合的文档体系 |
| ① 业务语义文档 | 文档模板 | 8 章 + 3 附录：属性 / 动作 / 事件 / 规则 / 状态 / 依赖 / 查询场景 | 订单业务语义 → 任何聚合的业务语义 |
| ② 聚合写设计文档 | 文档模板 | 11 节：静态结构 ~ 持久化，含改动清单 / 测试 / 风险 / 实施回填 | 订单写设计 → 任何聚合的写设计 |
| ③ 投影读设计文档 | 文档模板 | 6 节：读源与澄清、四角色、读源结构、构建同步、查询设计 | 订单投影读设计 → 任何聚合的读设计 |
| ④ 聚合事实 | 文档模板（快照） | 6 节：从代码推导当前实际形态，包含与语义的偏离及处置 | 订单事实文档 → 任何聚合的当前态 |
| 实施前置条件 | 机制（规范） | 生成代码前必须确认的项目级前提，未确认项阻断对应产出 | 任何项目的实施前闸门 |
⑧ 编码规范（横切）
本主题是横切编码规范：不产代码结构，只规定代码里的业务语义怎么表达。适用于 ① 写模型建模与 ③ 应用编排产出的所有代码。
| 文档 | 性质 | 落地问题 | 举一反三（示例 → 泛化） |
|---|---|---|---|
| 代码注释规范 | 编码规范（横切） | 实体字段、业务方法、Input 类与字段的注释标准、格式与反模式 | Order 字段 / OrderItem 方法 / PayOrderInput → 任何实体、任何 Input |
如何使用
- 找模式：新模块先定位到对应环节（建模 / 规则 / 编排 / 持久化 / 装配 / 事件），找到最贴近的落地模式文档。
- 套模板：把文档中的示例聚合 / 存储替换为目标场景，按代码骨架逐个落地组件。
- 避坑：对照每篇的 ⚠️ 约束与常见反模式表，在实现前预判易错点。
- 验证：落地后按各篇的规则自检，并补充单元测试。