ddd-architecture-awesome

DDD 架构精选

DDD 技能生态的入口。这项技能提供了理解 DDD、判断它是否适合你的项目，以及规划学习路径所需的一切，尽在一处。

何时使用（以及何时不使用）

✅ 适用场景	❌ 不适用场景
业务领域复杂，规则繁多	简单的 CRUD，业务规则很少
长期运行的系统（需维护多年）	原型、MVP、一次性代码
5 名以上开发人员的团队	独立开发者或小型团队（1-2 人）
有多个入口（API、CLI、事件）	只有一个入口，API 简单
需要更换基础设施（数据库、消息代理）	基础设施固定，不太可能变更
要求较高的测试覆盖率	快速脚本、内部工具
中国企业级 Spring Boot + MyBatis 技术栈	已采用成熟且有效的架构

从简单开始，仅在需要时逐步增加复杂度。 大多数系统不需要完整的 CQRS 或事件溯源。

何时触发此技能

当用户提到以下内容时，始终使用此技能：

• “什么是 DDD”、“解释一下 DDD”、“DDD 是什么”、“介绍一下 DDD”
• “Domain-Driven Design”、“领域驱动设计”
• “DDD 基础”、“DDD 基本概念”、“DDD 基础”、“DDD 入门”
• “我应该使用 DDD 吗”、“DDD 适用场景”、“DDD 是否适合”
• “DDD 与 CRUD 对比”、“DDD 与传统方式对比”、“DDD 对比”
• “DDD 概念”
• “DDD 战略设计”、“DDD 战术设计”
• “何时应用 DDD”、“何时适合使用 DDD”
• 关于 DDD 架构类型及其差异的问题
• 刚接触 DDD，并希望了解从何处开始

---

1. DDD 定义

领域驱动设计是一种开发方法，它将复杂的业务规则融入领域模型：先定义业务边界（战略设计），再将规则编码到模型中（战术设计）。

关键见解：DDD 与技术无关，而是要让代码与业务思维方式保持一致。

---

2. DDD 适用性决策树

从以下维度进行评估，并给出“适合 / 谨慎 / 不建议”的结论：

维度	适合（✓）	谨慎（~）	不建议（✗）
业务复杂度	规则复杂、状态机、跨团队协作	有一些业务规则，大多较简单	纯 CRUD、数据录入
生命周期	长期运行、持续演进	中期运行、会进行一些迭代	短期项目、可丢弃
团队成熟度	有专门的领域专家，产品经理稳定	具备一般业务知识	不具备领域知识
工程能力	测试和可观测性能力强，已准备好采用事件驱动	具备基本 CI/CD，有一些测试	没有测试基础设施

决策流程图

Is business logic complex (rules, state machines, constraints)?
├── NO → Is system long-lived (> 2 years)?
│         ├── NO → ✗ DDD NOT RECOMMENDED (Use simple CRUD + Service)
│         └── YES → ~ Cautious: adopt tactical patterns selectively
│
└── YES → Is there a domain expert or stable product owner?
          ├── NO → ~ Cautious: DDD without domain expert = complex code for nothing
          └── YES → Is the team familiar with DDD or willing to learn?
                    ├── NO → ~ Cautious: start with Layered, evolve later
                    └── YES → Do you need to swap infrastructure (DB, MQ)?
                              ├── NO → ✓ DDD RECOMMENDED (COLA or Layered)
                              └── YES → ✓ DDD STRONGLY RECOMMENDED (Hexagonal/Clean)

---

3. 复杂度阶梯——不要跳级

每个级别都会增加实际复杂度。只有在证明当前级别不足时，才升到更高级别。

Level 1: Simple Layered (Controller → Service → Repository)
   ↓ When business rules grow complex and need explicit modeling
Level 2: DDD 4-Layer with Rich Domain Model (Layered)
   ↓ When need multiple entry points (REST + CLI + MQ + gRPC)
Level 3: Ports & Adapters (Hexagonal Architecture)
   ↓ When read/write patterns diverge significantly
Level 4: CQRS — Separate Read/Write Models
   ↓ When need complete audit trail / temporal queries
Level 5: Event Sourcing — Store events, derive state

Your project Level: ___ (Recommend with reasoning)

---

4. 模式边界——每种模式是什么，以及不是什么

此表用于解决最常见的 DDD 困惑：“这些模式有什么区别？我应该在什么时候使用它们？”

模式	核心问题	适用场景	不要将其视为
DDD	如何对复杂的业务领域进行建模？	通用语言、限界上下文、聚合、值对象	单纯的文件夹结构
六边形架构	应用程序如何与外部世界交互？	端口、驱动适配器、被驱动适配器、可测试的应用核心	必须有六条边，或必须采用某种特定的包布局
整洁架构	依赖关系应该指向哪个方向？	依赖向内规则、用例边界、框架无关性	通用的四文件夹模板
洋葱架构	如何让领域模型处于核心位置？	以领域为中心的分层和依赖反转	Clean/Hexagonal 已经解决问题时仍需单独引入的要求
COLA v5	如何在企业 Java 团队中规范 DDD？	菱形架构、脚手架、自动化架构验证	适用于所有项目的万能方案
分层架构	如何逐步引入 DDD？	4 层分离、尽量减少对现有 3 层项目的影响	永久的最终形态（准备好后再演进）
CQRS	读写是否需要不同的模型？	读写工作负载差异明显的限界上下文	默认的应用架构
事件溯源	是否需要完整事件历史中的状态？	审计跟踪、时态查询、可重放的工作流	CRUD 系统的默认持久化方式

---

5. DDD 架构概览

DDD Architecture Family:

  Foundational (Learning cost: Low → Medium):
  ├── Layered Architecture (分层架构)
  │   └── Classic 4-layer: Interface → Application → Domain ← Infrastructure
  │       1-5 people | CRUD-friendly | Spring Boot native
  │
  ├── Onion Architecture (洋葱架构)
  │   └── Domain core, concentric dependency rings, inner defines interface
  │       5-15 people | High testability | Frequent infra changes
  │
  ├── Hexagonal Architecture (六边形架构 / Ports & Adapters)
  │   └── Domain at center, ports define contracts, adapters implement
  │       5-15 people | Multi-entry systems | Best testability
  │
  Advanced (Learning cost: Medium → High):
  ├── Clean Architecture (整洁架构)
  │   └── Entities → Use Cases → Interface Adapters → Frameworks
  │       15-50 people | Enterprise systems | Strict module isolation
  │
  └── COLA Architecture (COLA v5 架构)
      └── Diamond pattern: Adapter → App → Domain ← Infrastructure
          5-50 people | Chinese enterprise | Best tooling & community

  Complementary Patterns:
  ├── CQRS — Separate read/write models (L1: Model only / L2: DB separation / L3: Event Sourcing)
  ├── Domain Events — Cross-aggregate eventual consistency
  └── Event Sourcing — Store events as source of truth

架构可视化对比

Layered        Onion        Hexagonal      Clean          COLA v5
┌────────┐   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│Interf. │   │ Infra    │  │ Adapter  │  │ Frame.   │  │ Adapter  │
├────────┤   │ ┌──────┐ │  ├──────────┤  ├──────────┤  ├──────────┤
│  App   │   │ │ App  │ │  │  Ports   │  │ Adapter  │  │   App    │
├────────┤   │ │┌────┐│ │  ├──────────┤  ├──────────┤  ├──────────┤
│ Domain │   │ ││Dom.││ │  │ Domain ★ │  │ Domain ★ │  │ Domain ★ │
├────────┤   │ ││ ★  ││ │  └──────────┘  └──────────┘  ├──────────┤
│ Infra  │   │ │└────┘│ │                              │ Infra    │
└────────┘   │ └──────┘ │                              └──────────┘
             └──────────┘

---

6. DDD 核心概念速查

6.1 战略设计（战略设计）

概念	定义	要点
限界上下文	领域模型保持一致的边界	每个上下文都有自己的通用语言
通用语言	开发人员与领域专家共享的语言	用于代码、交流和文档
上下文映射	限界上下文之间的关系	合作关系、共享内核、客户-供应商、防腐层、开放主机服务
核心域	业务中最重要的部分	在此投入最多精力
子域	支撑性或通用的业务能力	核心 / 支撑 / 通用

6.2 战术设计（战术设计）

模式	用途	核心规则
实体	具有持久身份的对象	按 ID 判断相等，而非按属性
值对象	由属性定义的不可变数据	按值判断相等，不提供 setter
聚合	一致性边界	一个聚合 = 一个事务
聚合根	聚合的唯一入口	外部只能引用聚合根
仓储	持久化抽象	每个聚合对应一个仓储
领域服务	无状态的跨实体逻辑	逻辑不适合放入任何实体时使用
领域事件	有意义变更的记录	使用过去时命名（OrderPaid）
工厂	创建复杂对象	构造函数不足以满足需求时使用
规约	可组合的业务规则	可组合使用 AND/OR/NOT

6.3 快速决策树

“这段代码应该放在哪里？”

Where does this code go?
├─ Pure business logic, no I/O           → domain/
├─ Orchestrates domain + has side effects → application/
├─ Talks to external systems              → infrastructure/
├─ Defines HOW to interact (interface)    → port (domain or application)
└─ Implements a port                      → adapter (infrastructure)

“实体还是值对象？”

Entity or Value Object?
├─ Has unique identity that persists → Entity
├─ Defined only by its attributes    → Value Object
├─ "Is this THE same thing?"         → Entity (identity comparison)
└─ "Does this have the same value?"  → Value Object (structural equality)

“它应该成为独立的聚合吗？”

Aggregate boundaries?
├─ Must be consistent together in a transaction → Same aggregate
├─ Can be eventually consistent                 → Separate aggregates
├─ Referenced by ID only                        → Separate aggregates
└─ >10 entities in aggregate                    → Split it

规则： 每个事务只涉及一个聚合。跨聚合一致性通过领域事件实现（最终一致性）。

---

7. 充血领域模型与贫血 CRUD（关键区别）

// ❌ Anemic Model (Anti-Pattern) — Data bag + Service
@Entity
public class Order {
    private Long id;
    private String status;       // String instead of Value Object
    // Only getters/setters, NO behavior
}

@Service
public class OrderService {       // God Service with all logic
    @Transactional
    public void pay(Long orderId) {
        Order order = orderRepo.findById(orderId);
        if ("DRAFT".equals(order.getStatus())) {  // Raw string comparison
            order.setStatus("PAID");
            orderRepo.save(order);
        }
    }
}

// ✅ Rich Domain Model (DDD) — Behavior WITH data
public class Order extends AggregateRoot<OrderId> {
    private OrderStatus status;      // Value Object
    private Money totalAmount;
    private List<OrderItem> items;

    public void pay() {              // Behavior in entity
        if (!status.canPay()) {
            throw new OrderException("Cannot pay in current status");
        }
        this.status = OrderStatus.PAID;
        addDomainEvent(new OrderPaidEvent(this.id));
    }
}

聚合设计规模启发式

指标	健康	警告	操作
每个聚合的实体数	1-5	6-10	>10：拆分
代码行数（根）	<500	500-1000	>1000：拆分
事务锁定时间	<100ms	100-500ms	>500ms：拆分
并发修改冲突	罕见	偶尔	频繁：拆分

---

8. 反模式（重要——附修复方法）

反模式	问题	修复方法
贫血领域模型	实体只是数据包，逻辑放在服务中	将行为移入实体
每张表对应一个仓储	破坏聚合边界	每个聚合只设一个仓储
基础设施泄漏	领域导入数据库/HTTP 库	领域不依赖任何外部依赖
巨型聚合	实体过多，事务缓慢	拆分为更小的聚合
跳过用例	控制器直接调用仓储	通过应用层用例进行调用
CRUD 思维	对数据建模，而非行为	对业务操作建模
过早采用 CQRS	在尚不需要时增加复杂性	从简单开始，逐步演进
跨聚合事务	在一个事务中处理多个聚合	使用领域事件保持一致性
没有领域专家的 DDD	缺乏业务洞见的架构	没有专家的 DDD = 复杂代码
框架优先思维	未理解领域就选择技术	领域优先，技术其次

---

9. 实施顺序（通用）

1. Discover the Domain — Event Storming, conversations with domain experts
2. Model the Domain — Entities, value objects, aggregates (NO infrastructure)
3. Define Ports — Repository interfaces, external service interfaces
4. Implement Use Cases — Application services coordinating domain
5. Add Adapters LAST — HTTP, database, messaging implementations

DDD is collaborative. Modeling sessions with domain experts are as important as code patterns.

---

10. 如何使用此技能

步骤 1：了解用户背景

询问：项目性质、业务复杂度、团队结构、当前状态。

步骤 2：评估 DDD 的适用性

按照决策树（第 2 节）进行判断，并输出：

• 适用：继续选择架构
• 谨慎采用：建议选择性采用
• 不建议：说明原因，避免过度设计

步骤 3：推荐学习路径

用户类型	推荐路径
DDD 新手	awesome → selector → (architecture Skill) → code-reviewer
架构师/技术负责人	selector → (architecture Skill) → domain-designer → doc
迁移到 DDD	awesome → selector → (architecture Skill) → reviewer → evaluator
分层架构	selector → architecture-layered → domain-designer
洋葱架构	selector → architecture-onion → domain-designer
六边形架构	selector → architecture-hexagonal → domain-designer + api-designer
整洁架构	selector → architecture-clean → domain-designer
COLA	selector → architecture-cola → domain-designer → api-designer
需要 CQRS	selector → cqrs-architecture（独立使用或嵌入架构中）
微服务 + 事件	selector → (architecture Skill) → cqrs-architecture → api-designer
代码审查	code-reviewer（独立使用）
架构评估	evaluator（定期进行）
架构文档	doc（独立使用，读取现有代码）
事件风暴研讨会	event-storming（独立使用或与 domain-designer 配合）
测试策略	testing-strategist（独立使用或与 architecture Skill 配合）
DevOps 集成	devops-integration（与 CI/CD 流水线配合）

步骤 4：输出格式

始终按以下结构组织回复：

1. 适用性评估（Applicability Assessment）——清晰的结论，以及各维度的理由
2. DDD 核心概念速览（Core Concepts Quick Reference）——针对具体背景
3. 推荐学习路径（Recommended Learning Path）——推荐哪些技能及其顺序

---

11. 来源

完整来源清单（原著/模式参考/实施指南/中文资源/各语言参考实现）见 references/00-sources.md，按需加载。

---

参考资料库（按需加载）

此技能附带一个按学习路径组织的结构化参考资料库。每个文件都仅按需加载——当 Agent 判断有此需要时加载。

如何使用这些参考资料

当用户提出问题时，请在下方找到匹配的类别并阅读相关文件。请勿一次性加载所有参考资料。

用户询问……	加载此文件
“为什么使用 DDD？”、“我应该使用 DDD 吗？”、“DDD 与 CRUD 的区别”	references/01-strategic/01-why-ddd.md
“什么是领域／子域？”、“核心域与通用域、支撑域的区别”	references/01-strategic/02-domain-and-subdomain.md
“什么是限界上下文？”、“如何划分限界上下文？”、“上下文映射”	references/01-strategic/03-bounded-context.md
“实体与值对象的区别”、“何时使用实体／值对象？”、“相等性模式”	references/02-tactical/01-entity-and-value-object.md
“如何设计聚合？”、“聚合设计原则”、“聚合边界”	references/02-tactical/02-aggregate-design.md
“深入了解：聚合设计流程”、“从事件风暴到聚合的 5 个步骤”	references/02-tactical/03-aggregate-deep-dive.md
“领域事件详解”、“如何利用事件解耦”、“事件总线、事件溯源”	references/02-tactical/04-domain-events.md
“DDD 构件”、“命名约定”、“聚合大小度量指标”	references/02-tactical/05-building-blocks.md
“DDD 战术模式详解”、“Repository、Factory、Specification 模式”	references/02-tactical/06-tactical-concepts.md
“整洁架构战术参考（原始来源）”	references/02-tactical/07-clean-tactical-reference.md
“比较 DDD 架构”、“应该选择哪种架构？”、“分层架构与六边形架构、整洁架构的区别”	references/03-architecture/01-comparison.md
“DDD 适合我的项目吗？”、“DDD 适用性决策矩阵”、“现实场景”	references/03-architecture/02-decision-matrix.md
“DDD 分层架构详解”、“4 层的职责、严格分层与松散分层”、“从三层架构迁移到 DDD”	references/03-architecture/03-layered-architecture-detail.md
“深入了解架构”、“深入讲解 DDD + 六边形架构 + 整洁架构 + COLA”	references/03-architecture/04-architecture-deep-dive.md
“四层架构参考”、“领域层／应用层／基础设施层／表示层代码模板”	references/03-architecture/05-clean-layers-reference.md
“六边形架构参考”、“端口与适配器代码示例”	references/03-architecture/06-clean-hexagonal-reference.md
“战略 DDD 参考（原始来源）”、“限界上下文、上下文映射”	references/03-architecture/07-clean-strategic-reference.md
“快速速查表”、“模式边界、分层概览、决策树”	references/04-quick-ref/01-cheatsheet.md
“DDD 思维导图——完整知识体系全景”、“战略、战术、架构、流程、原则、实施”	references/04-quick-ref/02-ddd-mindmap.md
“事件风暴研讨会方法论”、“6 步研讨会流程、引导者指南”、“如何开展 DDD 探索”	references/05-implementation/01-event-storming-workshop.md
“领域对象到代码对象的映射”、“如何将领域对象映射到代码对象”、“映射表模板”	references/05-implementation/02-domain-to-code-mapping.md
“微服务代码模型结构”、“目录布局、包约定、分层代码”	references/05-implementation/03-code-model-structure.md
“各层中的服务与数据协作”、“DO/DTO/VO/PO 转换链”、“严格分层下的服务调用”	references/05-implementation/04-service-data-collaboration.md
“微服务边界与演进”、“逻辑／物理／代码边界”、“如何安全地演进架构”	references/05-implementation/05-boundaries-and-evolution.md
“使用 DDD 设计中台”、“平台与中台的区别、5 步建模”、“自顶向下与自底向上策略”	references/06-enterprise/01-middle-platform-design.md
“微服务设计原则与策略”、“绞杀者模式与修复者模式”、“4 项设计原则”	references/06-enterprise/02-microservice-design-principles.md
“分布式架构常见问题”、“10 个关键问题：分片、CDC、缓存、BFF、多数据中心”	references/06-enterprise/03-distributed-architecture-faq.md

端到端示例

示例与参考资料不同：参考资料讲解概念和原则；示例则展示如何在具体业务场景中应用，并提供真实代码。当用户想了解如何将 DDD 应用到真实场景时，请加载这些示例。

业务场景	展示内容	何时加载
考勤系统	完整工作流：事件风暴 → 聚合设计 → 服务识别 → 代码结构。包含非典型聚合的处理方式。	“给我看一个完整的 DDD 示例”、“演示 DDD 端到端流程”、“考勤 DDD 案例”
电商订单	核心订单领域：Order/OrderItem 的聚合设计、值对象（Money、OrderStatus）、领域事件，以及完整的分层代码。	“电商 DDD 示例”、“订单聚合设计”、“电商 DDD 案例”
保险保单	复杂聚合设计：实体与值对象的取舍、不变量强制执行，以及处理跨实体逻辑的领域服务。	“保险 DDD 示例”、“复杂聚合设计”、“保险 DDD 案例”

原则：“不要处处应用 DDD，只在重要之处应用。”

接下来，使用 ddd-architecture-selector 选择合适的架构模式，然后通过 ddd-domain-designer 深入领域建模，并使用相应的架构技能进行实现。

---

易错点 — 常见陷阱

• “DDD = COLA”的误解：DDD 并不等于 COLA 框架。COLA 只是阿里体系中的一种落地方案。还有 Layered、Onion、Hexagonal、Clean 等多种架构可选。请根据项目的实际需求进行选择。
• 一上来就搞 CQRS + Event Sourcing：绝大多数项目不需要 Event Sourcing。先评估是否真的需要完整的审计追踪和时间旅行查询。从最简单的分层架构开始。
• 把 DDD 当作银弹：DDD 适合复杂业务领域，对于简单的 CRUD 项目反而是过度设计。判断标准：业务规则多于 CRUD 操作、有领域专家参与、需要长期维护。
• 先做战术设计，后做战略设计：直接编写 Entity/ValueObject，却没有先划分 Bounded Context。缺乏战略边界的战术设计会导致上下文混乱和模型冲突。
• 领域专家参与不足：DDD 需要领域专家持续参与。如果开发人员仅凭自己对业务的理解来建模，产出的模型很可能偏离真实业务。

何时不使用此技能

❌ 跳过	✅ 改用
已经熟悉 DDD	直接使用 architecture-selector
只需要比较架构	使用 architecture-selector（更快）
想立刻获取代码，而不是了解概念	直接选择一种架构技能
正在构建简单的原型	跳过 DDD，使用简单的 Spring Boot MVC
现有项目已有可用的架构	使用 architecture-evaluator（评估是否需要 DDD）

安全性与稳定性

• 所有代码示例和概念说明均用于教学目的，不包含真实凭据或敏感数据。
• 此技能讲解 DDD 方法论和模式，不会执行代码、访问外部系统或修改任何项目文件。
• DDD 的有界上下文隔离机制会自然地促进系统不同部分之间的安全边界。
• 不附带可执行脚本。此技能是纯学习和参考资源。

🧭 DDD 技能之旅

📍 你在这里：ddd-architecture-awesome — 第 1 步：DDD 入门与全景

flowchart LR
    S1["⭐ Step 1<br/>awesome<br/>入门与全景"] --> S2["Step 2<br/>selector<br/>架构选型"]
    S2 --> S3A["Step 3<br/>layered<br/>分层架构"]
    S2 --> S3B["Step 3<br/>onion<br/>洋葱架构"]
    S2 --> S3C["Step 3<br/>hexagonal<br/>六边形架构"]
    S2 --> S3D["Step 3<br/>clean<br/>整洁架构"]
    S2 --> S3E["Step 3<br/>cola<br/>COLA v5"]
    S3A & S3B & S3C & S3D & S3E --> S4A["Step 4<br/>domain-designer<br/>领域建模"]
    S3A & S3B & S3C & S3D & S3E --> S4B["Step 4<br/>cqrs-architecture<br/>CQRS"]
    S3A & S3B & S3C & S3D & S3E --> S4C["Step 4<br/>api-designer<br/>API设计"]
    S4A & S4B & S4C --> S5["Step 5<br/>code-reviewer<br/>代码审查"]
    S5 --> S6A["Step 6<br/>event-storming<br/>事件风暴"]
    S5 --> S6B["Step 6<br/>testing-strategist<br/>测试策略"]
    S5 --> S6C["Step 6<br/>devops-integration<br/>DevOps"]
    S5 --> S6D["Step 6<br/>evaluator<br/>架构评估"]
    S6A & S6B & S6C & S6D --> S7["🏁 Step 7<br/>architecture-doc<br/>架构文档"]

    style S1 fill:#10b981,stroke:#059669,color:white,stroke-width:3px

← 上一步：你已站在 DDD 旅程的起点 🚀 → 下一步：转交给 ddd-architecture-selector 技能 — 选择适合你项目的架构模式（安装：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector）。 🔗 相关：转交给 ddd-domain-designer 技能 — 直接开始领域建模（安装：npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer） | ddd-event-storming 技能 — 先开展事件风暴工作坊（安装：npx skills add full-stack-skills/ddd-skills --skill ddd-event-storming）。 🏠 首页：你在起点

💡 你是第一次接触 DDD？读完第 4 节的模式边界表和第 6 节的核心概念速查，然后前往 selector 选择架构。