DDD Architecture — Onion (洋葱架构)

基于 Jeffrey Palermo（2008）提出的同心圆架构模型，以 Domain 为圆心，依赖方向严格指向内层。

Workflow

Step 1: 适用性检查 — 判断项目是否适合洋葱架构 | 参考：SKILL.md When to Use

Step 2: 搭建目录骨架 — 创建四层模块 core/infrastructure/api/composition | 参考：references/04

Step 3: 编写 Domain 核心 — 聚合根、值对象、Repository 接口、领域事件（零框架依赖）| 参考：references/01

Step 4: 编写 Application 接口 — 应用服务接口契约，纯编排不含业务逻辑 | 参考：references/02

Step 5: 编写 Infrastructure 实现 — 实现 Domain 层 Repository/MQ/外部客户端 | 参考：references/03

Step 6: 编写 API 适配器 — Controller、DTO、Assembler、全局异常处理 | 参考：references/04

Step 7: 配置 DI 组装 — composition 模块集中装配 | 参考：references/05

Step 8: 编写测试 — Domain 层单测 → Application Mock → Infra 集成测试 | 参考：references/06

Step 9: Gotchas 检查 — 对照常见陷阱逐条验证 | 参考：各 references 陷阱章节

Step 10: 迁移（如适用） — 三层→洋葱渐进迁移 | 参考：references/07

When to Read (触发条件)

When to Use

Boundary

Audience

This skill is designed for: Backend developers (implementing DDD architectures), Software architects (evaluating and selecting patterns), Tech leads (reviewing team implementations), and DDD beginners (learning domain-driven design fundamentals).

核心原理：同心圆依赖规则

所有依赖关系指向圆心（Domain），内层定义接口，外层实现接口。

Infrastructure → API/Adapters → Application → Domain Core ★
所有依赖指向圆心，内层零框架依赖。

Jeffrey Palermo 四原则

1. 应用核心独立于基础设施 — Domain 层不 import 任何框架/数据库类
2. 内层定义接口，外层实现 — 如 OrderRepository 接口在 Domain，实现在 Infrastructure
3. 依赖指向圆心 — Infrastructure → Application → Domain，不允许逆向
4. 外层知道内层，内层不知道外层 — Domain 对 Infrastructure 一无所知

Rules

详见 [references/08-comparison.md](references/08-comparison.md) 了解洋葱 vs 六边形 vs 整洁架构的详细对比。

目录结构

{project}/
├── {project}-core/domain/          # 领域模型（零框架依赖）
├── {project}-core/application/     # 应用服务接口
├── {project}-infrastructure/       # Repository 实现、MQ、外部集成
├── {project}-api/                  # Controller、DTO、Assembler
└── {project}-composition/          # DI 组装

模块依赖规则

开发规范（详见各 references）

Gotchas — (详见各 references 陷阱章节)

15 条核心陷阱：Domain 层框架泄露 / Repository 接口位置 / Application 过厚 / 过度抽象 / Composition Root 分散 / 值对象可变 / 聚合根过大 / 跨聚合直接引用 / Controller 含业务逻辑 / DTO 泄露 / PO 注解 / 缺少事件 / 事务跨聚合 / Infra 侵入测试

FAQ — (详见 references/08-comparison.md 和各层 references)

涵盖：洋葱 vs 六边形、Domain 框架限制、值对象 vs 实体、Repository 接口位置、聚合大小、迁移策略、CQRS 兼容、测试层次、微服务适配、事件跨服务等。

Keywords

onion architecture, 洋葱架构, Jeffrey Palermo, domain-centric architecture,
layered isolation, dependency inversion, 依赖倒置, concentric layers,
core/domain, application interfaces, infrastructure implementation,
API adapters, composition root, DI assembly, domain model,
repository pattern, aggregate root, value object, domain service,
DDD layered, clean architecture comparison, hexagonal comparison

References

Examples

业务场景示例

项目规模示例

Primary Sources: Onion Architecture Part 1-4 — Jeffrey Palermo (2008) · DDD Blue Book — Eric Evans (2003) · Implementing DDD — Vaughn Vernon (2013)

Implementation: Microsoft DDD Microservice · Testcontainers

Output

回答始终包含：适用性判断 → 目录结构 → 每层代码模板 → DI 装配 → 测试骨架 → Gotchas 合规检查。详细参考 references/ 和 examples/ 文件。

技能旅程

📍 当前：洋葱架构落地

← 上一步：hand off to the ddd-architecture-selector skill(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector) → 下一步：hand off to the ddd-domain-designer skill(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer) 🔗 相关：hand off to ddd-cqrs-architecture skill(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture) | ddd-code-reviewer skill(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer) 🏠 首页：hand off to ddd-architecture-awesome skill(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-awesome)

核心口诀：内层定义接口，外层实现接口，依赖指向圆心。

Security & Safety

This skill is pure documentation. It contains no executable scripts, collects no user data, accesses no external services or networks.

验证清单

• Domain 层无框架 import
• Repository 接口在 Domain 层
• Repository 实现在 Infrastructure 层
• Application 层无业务 if/else
• 值对象不可变
• 跨聚合通过 ID 引用
• DTO 只定义在 API 层
• DI 集中在 composition 模块
• 领域事件已发布