ddd-architecture-awesome

# DDD Architecture Awesome The **entry point** to the DDD Skills ecosystem. This skill provides everything needed to understand DDD, decide if it's right for your project, and chart your learning path — all in one place. ## When to Use (and When NOT to) | ✅ Use When | ❌ Skip When | |------------|-------------| | Complex business domain with many rules | Simple CRUD, few business rules | | Long-lived system (years of maintenance) | Prototype, MVP, throwaway code | | Team of 5+ developers | Solo developer or small team (1-2) | | Multiple entry points (API, CLI, events) | Single entry point, simple API | | Need to swap infrastructure (DB, broker) | Fixed infrastructure, unlikely to change | | High test coverage required | Quick scripts, internal tools | | Chinese enterprise Spring Boot + MyBatis stack | Already using established architecture that works | **Start simple. Evolve complexity only when needed.** Most systems don't need full CQRS or Event Sourcing. ## When to trigger this skill **ALWAYS use this skill when the user mentions:** - "What is DDD", "Explain DDD", "DDD 是什么", "介绍一下 DDD" - "Domain-Driven Design", "领域驱动设计" - "DDD basics", "DDD fundamentals", "DDD 基础", "DDD 入门" - "Should I use DDD", "DDD 适用场景", "DDD 是否适合" - "DDD vs CRUD", "DDD vs traditional", "DDD 对比" - "DDD concepts", "DDD 概念" - "Strategic design DDD", "Tactical design DDD", "DDD 战略设计", "DDD 战术设计" - "When to apply DDD", "When DDD is appropriate" - Questions about DDD architecture types and their differences - New to DDD and seeking guidance on where to start --- ## 1. DDD Definition > Domain-Driven Design is a development methodology that brings complex business rules into domain models: first define business boundaries (Strategic Design), then encode rules into models (Tactical Design). **Key insight**: DDD is not about technology — it's about aligning your code with how the business thinks. --- ## 2. DDD Applicability Decision Tree **Evaluate along these dimensions and provide a "Suitable / Cautious / Not Recommended" conclusion:** | Dimension | Suitable (✓) | Cautious (~) | Not Recommended (✗) | |-----------|-------------|-------------|---------------------| | **Business Complexity** | Complex rules, state machines, cross-team coordination | Some business rules, mostly simple | Pure CRUD, data entry | | **Lifecycle** | Long-lived, continuous evolution | Medium-term, some iteration | Short-term, disposable | | **Team Maturity** | Dedicated domain expert, stable PM | General business knowledge | No domain knowledge | | **Engineering Capability** | Strong test/observability, event-driven ready | Basic CI/CD, some testing | No testing infrastructure | ### Decision Flowchart ``` 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. Complexity Ladder — Don't Skip Levels **Each level adds real complexity. Move up only when you've proven the current level insufficient.** ``` 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. Pattern Boundaries — What Each Pattern IS and IS NOT This table solves the most common DDD confusion: "What's the difference between these patterns, and when should I use each one?" | Pattern | Primary Question | Use It For | Do NOT Treat As | |---------|-----------------|------------|-----------------| | **DDD** | How do we model a complex business domain? | Ubiquitous language, bounded contexts, aggregates, value objects | A folder structure by itself | | **Hexagonal Architecture** | How does the application interact with the outside world? | Ports, driver adapters, driven adapters, testable application core | A mandate for six sides or one exact package layout | | **Clean Architecture** | Which direction should dependencies point? | Inward dependency rule, use case boundaries, framework independence | A universal four-folder template | | **Onion Architecture** | How do we keep the domain model central? | Domain-centered layers and dependency inversion | A separate requirement when Clean/Hexagonal already solve the problem | | **COLA v5** | How do we standardize DDD in enterprise Java teams? | Diamond architecture, scaffolding, automated architecture validation | A silver bullet for all projects | | **Layered Architecture** | How do we introduce DDD incrementally? | 4-layer separation, minimal disruption to existing 3-layer projects | A permanent destination (evolve when ready) | | **CQRS** | Do reads and writes need different models? | Bounded contexts with divergent read/write workloads | A default application architecture | | **Event Sourcing** | Do we need state from a complete event history? | Audit trails, temporal queries, replayable workflows | A persistence default for CRUD systems | --- ## 5. DDD Architecture Landscape Overview ``` 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 ``` ### Architecture Visual Comparison ``` Layered Onion Hexagonal Clean COLA v5 ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │Interf. │ │ Infra │ │ Adapter │ │ Frame. │ │ Adapter │ ├────────┤ │ ┌──────┐ │ ├──────────┤ ├──────────┤ ├──────────┤ │ App │ │ │ App │ │ │ Ports │ │ Adapter │ │ App │ ├────────┤ │ │┌────┐│ │ ├──────────┤ ├──────────┤ ├──────────┤ │ Domain │ │ ││Dom.││ │ │ Domain ★ │ │ Domain ★ │ │ Domain ★ │ ├────────┤ │ ││ ★ ││ │ └──────────┘ └──────────┘ ├──────────┤ │ Infra │ │ │└────┘│ │ │ Infra │ └────────┘ │ └──────┘ │ └──────────┘ └──────────┘ ``` --- ## 6. Core DDD Concepts Quick Reference ### 6.1 Strategic Design (战略设计) | Concept | Definition | Key Point | |---------|-----------|-----------| | **Bounded Context** | A boundary within which a domain model is consistent | Each context has its own ubiquitous language | | **Ubiquitous Language** | A shared language between developers and domain experts | Used in code, conversations, and documentation | | **Context Mapping** | Relationships between bounded contexts | Partnership, Shared Kernel, Customer-Supplier, ACL, OHS | | **Core Domain** | The most important part of the business | Invest the most effort here | | **Subdomain** | Supporting or generic business capabilities | Core / Supporting / Generic | ### 6.2 Tactical Design (战术设计) | Pattern | Purpose | Key Rule | |---------|---------|----------| | **Entity** | Object with identity that persists | Equality by ID, not attributes | | **Value Object** | Immutable data defined by attributes | Equality by value, no setters | | **Aggregate** | Consistency boundary | One aggregate = one transaction | | **Aggregate Root** | Single entry point to aggregate | Only root referenced externally | | **Repository** | Persistence abstraction | One repository per aggregate | | **Domain Service** | Stateless cross-entity logic | When logic doesn't fit any entity | | **Domain Event** | Record of meaningful change | Past tense naming (OrderPaid) | | **Factory** | Complex object creation | When constructor isn't enough | | **Specification** | Composable business rule | AND/OR/NOT combinable | ### 6.3 Quick Decision Trees #### "Where does this code go?" ``` 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?" ``` 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) ``` #### "Should this be its own Aggregate?" ``` 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 ``` **Rule:** One aggregate per transaction. Cross-aggregate consistency via domain events (eventual consistency). --- ## 7. Rich Domain Model vs Anemic CRUD (Critical Distinction) ```java // ❌ 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)); } } ``` ### Aggregate Sizing Heuristics | Metric | Healthy | Warning | Action | |--------|---------|---------|--------| | Entities per aggregate | 1-5 | 6-10 | >10: Split | | Lines of code (root) | <500 | 500-1000 | >1000: Split | | Transaction lock time | <100ms | 100-500ms | >500ms: Split | | Concurrent modification conflicts | Rare | Occasional | Frequent: Split | --- ## 8. Anti-Patterns (CRITICAL — with Fixes) | Anti-Pattern | Problem | Fix | |-------------|---------|-----| | **Anemic Domain Model** | Entities are data bags, logic in services | Move behavior INTO entities | | **Repository per Table** | Breaks aggregate boundaries | One repository per AGGREGATE | | **Leaking Infrastructure** | Domain imports DB/HTTP libraries | Domain has ZERO external dependencies | | **God Aggregate** | Too many entities, slow transactions | Split into smaller aggregates | | **Skipping Use Cases** | Controllers call repositories directly | Route through application use cases | | **CRUD Thinking** | Modeling data, not behavior | Model business operations | | **Premature CQRS** | Adding complexity before needed | Start simple, evolve | | **Cross-Aggregate TX** | Multiple aggregates in one transaction | Use domain events for consistency | | **DDD without Domain Expert** | Architecture without business insight | DDD without experts = complex code | | **Framework-First Thinking** | Choosing tech before understanding domain | Domain first, technology second | --- ## 9. Implementation Order (Universal) ``` 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. How to Use This Skill ### Step 1: Understand user context Ask about: project nature, business complexity, team structure, current state. ### Step 2: Assess DDD applicability Run through the decision tree (Section 2) and output: - **Suitable**: Proceed to architecture selection - **Cautious**: Recommend selective adoption - **Not Recommended**: Explain why, prevent over-engineering ### Step 3: Recommend learning path | User Type | Recommended Path | |-----------|-----------------| | **DDD Novice** | awesome → selector → (architecture Skill) → code-reviewer | | **Architect/Tech Lead** | selector → (architecture Skill) → domain-designer → doc | | **Migrating to DDD** | awesome → selector → (architecture Skill) → reviewer → evaluator | | **Layered** | selector → architecture-layered → domain-designer | | **Onion** | selector → architecture-onion → domain-designer | | **Hexagonal** | selector → architecture-hexagonal → domain-designer + api-designer | | **Clean** | selector → architecture-clean → domain-designer | | **COLA** | selector → architecture-cola → domain-designer → api-designer | | **Needs CQRS** | selector → cqrs-architecture (standalone or embedded in architecture) | | **Microservices + Events** | selector → (architecture Skill) → cqrs-architecture → api-designer | | **Code Review** | code-reviewer (standalone) | | **Architecture Eval** | evaluator (periodic) | | **Architecture Doc** | doc (standalone, read existing code) | | **Event Storming Workshop** | event-storming (standalone or paired with domain-designer) | | **Testing Strategy** | testing-strategist (standalone or paired with architecture Skill) | | **DevOps Integration** | devops-integration (paired with CI/CD pipeline) | ### Step 4: Output format Always structure response with: 1. **适用性评估** (Applicability Assessment) — clear conclusion + reasoning per dimension 2. **DDD 核心概念速览** (Core Concepts Quick Reference) — tailored to context 3. **推荐学习路径** (Recommended Learning Path) — which skills, what order --- ## 11. Sources 完整来源清单（原著/模式参考/实施指南/中文资源/各语言参考实现）见 [`references/00-sources.md`](references/00-sources.md)，按需加载。 --- ## Reference Library（按需加载）