聚合目录落地骨架
新建聚合的第一步:照本文建立
{agg}的目录骨架,再按图索骥到各阶段落地模式文档填充。目录即地图——每个文件夹对应一篇(或多篇)模式文档。模块级四层全貌见 推荐项目结构。
1. 本质与定位
本文档把「新建聚合」的第一步模板化:初始化 domain/{agg} / application/{agg} / api/{agg} / controller/{agg} 目录骨架,并在基础设施层对应落地 persistent / dependency / config 下的 {agg} 目录。它不是单一能力点的模式,而是聚合全链路的目录地图——每个文件夹指向对应的落地模式文档,按目录逐个填充即完成聚合落地。
- 适用:在既有模块内新建聚合(如
order/product),或从零初始化一个模块。 - 不适用:理解框架整体分包与多模块拆分(见 推荐项目结构)。
2. 目录骨架(核心)
以四层分包为骨架;其中领域 / 应用 / UI 层以聚合 {agg} 为第一级,基础设施层以类型(persistent / dependency / config)为第一级、聚合为第二级:
{module}/
├── api/{agg}/ # UI:协议 Request / Response
│ ├── cmd/ # 命令协议
│ ├── query/ # 查询协议
│ └── dto/ # 响应 DTO
├── controller/{agg}/ # UI:{Agg}Controller
├── application/{agg}/ # Application:编排领域逻辑、汇聚依赖
│ ├── input/ # {Action}Input 业务语义入参
│ ├── factory/ # EntityFactory 聚合工厂(先算后赋)
│ ├── updater/ # EntityUpdater 修改场景编排
│ ├── resolver/ # Command → 领域输入适配
│ ├── rule/ # 规则容器组装
│ ├── service/ # 领域服务实现(注解按 category:EVENT_SUBSCRIBER→@Component,其余→@Service)
│ ├── action/ # 可补偿动作 ICompensableAction(正向 / 回写 / 补偿三元组)
│ ├── compensation/ # 兜底处理器 ICompensationHandler(durable 模式)
│ └── subscriber/ # 事件订阅登记
├── domain/{agg}/ # Domain:业务原子零件与契约(无 acl/ 包)
│ ├── model/ # 聚合根 / 实体 / 值对象(含 enums/ valueobject/)
│ ├── event/ # 领域事件
│ ├── operation/ # 操作注册表
│ ├── param/ # 参数对象 IParamObject
│ ├── rule/ # 规则容器 + 规则注册表
│ ├── service/ # 事件订阅 / 校验规则 / 能力供给契约
│ ├── calculator/ # 属性计算契约
│ ├── dependency/ # 外部依赖声明
│ ├── repository/ # 仓储抽象
│ ├── projection/ # 投影契约(含 query/ 查询条件三族、replica/ 副本版本、补偿专属契约)
│ ├── requirement/ # 外部需求声明 IExternalRequirement(配合可补偿命令)
│ └── config/ # 领域配置
└── infrastructure/ # Infrastructure:技术实现,落地领域层契约(类型优先)
├── persistent/{agg}/ # 持久化:仓储实现 + 投影(projector/ searcher/ reducer/ + replica/ 写读一体源 / 版本 / 对账)
├── dependency/{agg}/ # 外部依赖实现(ACL 网关);跨聚合共享的放 dependency/shared/
└── config/ # @Configuration 装配(MySQL / ES / MQ / Outbox)
└── {agg}/ # 仅绑定聚合的配置进 config/{agg}/,通用配置放 config/ 外层⚠️ 分包维度:领域 / 应用层以聚合
{agg}为第一级(让单个聚合的契约与编排内聚成块),基础设施层以类型(persistent/dependency/config)为第一级、聚合为第二级(便于把通用技术配置与跨聚合共享适配器抽成单一来源,见 推荐项目结构 §2.3)。不同聚合不共享包或实体,聚合间通信走领域事件。
3. 按图索骥:目录 → 模式文档
建好目录后,按文件夹逐个填充,每个文件夹对应一篇(或多篇)落地模式:
| 目录 | 放什么 | 去查的模式文档 |
|---|---|---|
domain/{agg}/model | 聚合根、实体、值对象、枚举 | 聚合设计原则 · 普通实体设计原则 · 值对象最佳实践 · 枚举值对象最佳实践 |
domain/{agg}/event | 领域事件类 | 事件建模指南 |
domain/{agg}/operation | 操作注册表 | 操作注册表设计 |
domain/{agg}/param | 参数对象 | 聚合设计原则 |
domain/{agg}/rule | 规则容器 + 规则注册表 | 规则注册表设计 · 聚合业务规则(OrderRule 范式) |
domain/{agg}/service + calculator | 四类领域服务契约 | 领域服务落地模式 |
domain/{agg}/dependency | 外部依赖声明 | 核心:依赖体系 |
domain/{agg}/repository | 仓储抽象 | 仓储设计原则 |
domain/{agg}/projection | 投影契约 | 投影读模型代码落地指南 |
domain/{agg}/requirement | 外部需求声明(record) | 应用层落地模式 |
application/{agg}/input | 业务语义入参 | 应用层落地模式 |
application/{agg}/factory + updater + resolver | 聚合装配 / 修改 / 适配 | 领域服务落地模式 · 应用层落地模式 |
application/{agg}/service | 领域服务实现 | 领域服务落地模式 |
application/{agg}/action + compensation | 可补偿动作 / 兜底处理器 | 应用层落地模式 |
application/{agg}/subscriber | 事件订阅登记 | 投影读模型代码落地指南 · RocketMQ 配置设计原则 |
infrastructure/persistent/{agg}/repository | 仓储实现 | 仓储设计原则 · MyBatis 配置设计原则 |
infrastructure/persistent/{agg}/projection | 投影器 / 物化器 | 投影读模型代码落地指南 · Elasticsearch 配置设计原则 |
infrastructure/config(通用)+ config/{agg}/ | Bean 装配 | MySQL · MyBatis · Elasticsearch · RocketMQ · Outbox |
infrastructure/dependency/{agg}(+ shared/) | 外部依赖实现 | 核心:依赖体系 · ACL 防腐层 |
3.1 类类型 → 包:落点判据(唯一权威表)
本表是包落点的唯一来源。其他篇(含 推荐项目结构)只允许指向本表作导览,不得复制清单——两份清单并存必然漂移。
判定采用双条件:对象类型(含标记接口)+ 所在层。不看调用方,可机械执行。
| 对象类型 | 识别特征 | 落点 | 不得落 |
|---|---|---|---|
| 聚合根 | extends AggregateRoot<ID> | domain/{agg}/model/ | — |
| 子实体 | extends AbstractEntity<ID> / implements ITrackable<ID> | domain/{agg}/model/ | — |
| 枚举值对象 | implements IEnumValue<..> | domain/{agg}/model/enums/ | model/ 平铺 |
| 值对象 | extends ValueObject / implements IValueObject | domain/{agg}/model/valueobject/ | model/ 平铺、param/ |
| 参数对象 | implements IParamObject 且位于 domain/ 下,命名 {Agg}InitData / {Agg}{Action}Data | domain/{agg}/param/ | model/ |
| 领域事件 | extends BaseDomainEvent / BaseDataSyncEvent | domain/{agg}/event/ | model/ |
| 操作注册表 | extends OperationRegistry | domain/{agg}/operation/ | — |
| 规则容器 / 规则注册表 | extends EntityRule / extends BrokenRuleRegistry | domain/{agg}/rule/ | — |
| 领域服务契约 | extends IDomainService | domain/{agg}/service/ | application/ |
| 属性计算契约 | extends IDomainService 且命名 {Agg}{Prop}Calculator | domain/{agg}/calculator/ | service/ |
| 仓储抽象 | extends AbstractRepository<ID, T> | domain/{agg}/repository/ | — |
| 投影契约 | I{Agg}{Store}Source / {Agg}{View}Projection | domain/{agg}/projection/ | infrastructure/ |
| 应用层 Input | @Data,命名 {Action}{Agg}Input,位于 application/ 下 | application/{agg}/input/ | 即使实现 IParamObject 也不入 domain/ |
| 应用写服务 | extends AbstractApplicationService 且 implements ICommandApplicationService | application/{agg}/ | service/ |
| 应用读服务 | implements IQueryApplicationService(无基类) | application/{agg}/ | service/ |
| 领域服务实现 | 实现 I{Agg}{X}Service / I{Agg}{X}Handle 且契约带 @DomainService | application/{agg}/service/ | 根层 |
| 订阅注册表 | @Configuration + 构造器注入 IEventRegistry,命名 {Agg}EventSubscriberRegistry | application/{agg}/subscriber/ | service/(实现类同禁) |
| 应用层工厂 / 修改器 / 适配器 / 规则装配 | EntityFactory / EntityUpdater / resolver / {Agg}RuleConfig | application/{agg}/ 下 factory / updater / resolver / rule | — |
| 可补偿动作 / 兜底处理器 | ICompensableAction / ICompensationHandler | application/{agg}/ 下 action / compensation | — |
| 外部需求声明 | record implements IExternalRequirement | domain/{agg}/requirement/ | param/ |
| 查询条件对象 | {Agg}{X}Query(sealed 三族) | domain/{agg}/projection/query/ | model/ |
| 仓储实现 | extends Abstract{Agg}Repository | infrastructure/persistent/{agg}/repository/ | domain/ |
| 投影构件 | Projector / Source / Reducer / Replica / 版本 / 对账 | infrastructure/persistent/{agg}/projection/… | domain/ |
| 依赖适配器 | 实现 I{Agg}{X}Dependency | infrastructure/dependency/{agg}/(共享 shared/) | application/ |
| 装配配置 | @Configuration | infrastructure/config/(聚合级 config/{agg}/) | domain/ |
两条硬说明
- 判据不得简化成「只看标记接口」:应用层 Input 与领域层参数对象可以实现同一个
IParamObject,但一个落application/{agg}/input/、一个落domain/{agg}/param/。把 Input 按接口搬进领域层会同时破坏领域层零基础设施依赖与 Input 的协议适配定位。 - 参数对象命名口径钉死为
*Data:{Agg}InitData/{Agg}{Action}Data(如OrderInitData、OrderAddItemData),不用*Param。
存量降级规则
本表对新建类与本轮新增类强制生效。存量类位置与本表不符时:不强制迁移,评审按建议项(Advisory)登记为待迁移;项目若决定长期保留现状,记入该项目的判决名单 docs/design/aggregates/{agg}/accepted.md,后续生成与评审按判决写,不重议。
4. 四层职责速记
| 层 | 职责 | 不要放 |
|---|---|---|
| 领域层 Domain | 业务原子零件与契约 | SQL/ORM、RPC、MQ 发送、事务、Input |
| 应用服务层 Application | 编排领域逻辑、汇聚依赖 | 直接 new 基础设施实现、聚合根业务行为 |
| 基础设施层 Infrastructure | 技术实现,落地领域层契约 | 业务逻辑、领域规则、状态判定 |
| 用户接口层 UI | 协议适配与参数转换 | 业务编排、聚合调用、仓储直连 |
5. 关键机制与避坑
- 依赖方向:
UI → Application → Domain ← Infrastructure(基础设施实现领域层接口,依赖倒置)。 - 领域层零基础设施依赖:
domain/{agg}下不出现 Spring / MyBatis / MQ 导入;依赖外部能力用dependency声明 + 领域服务契约,由应用 / 基础设施层实现。 - 聚合间不共享:不同聚合目录独立,通信优先领域事件,不跨聚合直接 new 仓储 / 服务。
- 目录名即语义:
service只放领域服务契约(领域层)或实现(应用 / 基础设施层),不要混放业务逻辑类。
6. 常见反模式
| 反模式 | 问题 | 正确做法 |
|---|---|---|
领域/应用层目录以技术分层为第一级(如 domain/repository/、application/service/) | 单个聚合的契约与编排散落各目录、难整体搬移 | 领域/应用层以聚合 {agg} 为第一级 |
基础设施层以聚合 {agg} 为第一级并在其下重复通用配置 | 通用数据源/适配器在每个聚合下各放一份、难复用 | 基础设施层类型优先:persistent / dependency / config 为一级、聚合为二级,通用放 config/、共享放 dependency/shared/ |
domain/{agg} 里出现 Spring / Mapper / MQ 导入 | 破坏领域层零基础设施依赖 | 依赖外部能力用契约 + 依赖声明 |
| 不同聚合共享包 / 实体 | 聚合边界模糊、事件驱动失效 | 聚合目录独立,通信走领域事件 |
service 包混放业务逻辑类 | 目录语义失真、难维护 | 契约 / 实现按层分离,业务逻辑内聚聚合根 |
| 跳过目录骨架直接写代码 | 结构散落、后续难以按模式填充 | 先初始化目录,再按图索骥填充 |