mcpField
D
ddd-architecture-onion

ddd-architecture-onion

github.com/full-stack-skillsDevelopment17116 installsUpdated 4w ago
Repository

About ddd-architecture-onion

An onion architecture guide for backend developers, software architects, tech leads, and DDD beginners. It explains inward-facing dependencies around the Domain core and provides guidance for design, testing, dependency injection, and migration.

Key features

  1. 01Concentric dependency rules
  2. 02Domain and Repository design conventions
  3. 03Infrastructure and API layer guidance
  4. 04Centralized dependency-injection assembly
  5. 05Layered testing strategy
  6. 06Migration guidance and architecture examples

Use cases

  1. 01Planning layers for systems with complex business rules
  2. 02Isolating the Domain as infrastructure changes
  3. 03Designing multi-entry services with dependencies directed inward
  4. 04Gradually migrating from a three-layer architecture

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/full-stack-skills/ddd-skills --skill ddd-architecture-onion

After installing, type/ddd-architecture-onionin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
examples/
01-order-payment.md
02-product-catalog.md
03-multi-entry.md
04-cqrs-onion.md
05-user-registration.md
06-monolith-simple.md
07-monolith-complex.md
08-monolith-multi-module.md
09-microservice-simple.md
10-microservice-complex.md
11-microservice-multi-module.md
12-microservice-complex-multi.md
references/
01-domain-model.md
02-application-interfaces.md
03-infrastructure-implementation.md
04-api-adapters.md
05-di-composition.md
06-testing.md
07-migration-from-layered.md
08-comparison.md
references/guides/
.gitkeep
references/patterns/
.gitkeep

Details

From the project README

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 (触发条件)

用户问题加载动作
"帮我用洋葱架构搭建项目"打开 SKILL.md + references/01-05
"Repository 接口应该放哪？"打开 references/01-domain-model
"洋葱架构怎么测试？"打开 references/06-testing
"从三层怎么迁到洋葱？"打开 references/07-migration-from-layered
"洋葱和六边形有什么区别？"打开 references/08-comparison
"洋葱支持 CQRS 吗？"打开 examples/example-04-cqrs-onion
"多入口怎么设计？"打开 examples/example-03-multi-entry
"DI 怎么配置 Spring Boot？"打开 references/05-di-composition

When to Use

✅ 适用场景❌ 不适用
基础设施频繁变更（DB/MQ/缓存厂商更换）简单 CRUD 项目（过度设计）
单元测试覆盖率要求 > 80%两周交付的原型/PoC
多入口系统（REST + CLI + MQ + gRPC）单入口 + 单数据库的简单服务
团队有接口抽象和 DI 设计能力团队不熟悉依赖倒置
业务规则复杂，需要严格隔离三层架构够用
Boundary
区域归属
三层→洋葱迁移✅ 本 Skill（references/07-migration）
洋葱 vs 六边形 vs 整洁对比✅ 本 Skill（references/08-comparison）
选型决策❌ 用 ddd-architecture-selector
领域建模❌ 用 ddd-domain-designer
代码审查❌ 用 ddd-code-reviewer
COLA 项目❌ 用 ddd-architecture-cola

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

#规则检测方式级别
1Domain 层零框架依赖搜索 Domain 包中的框架 importP0
2Repository 接口在 Domain，实现在 Infra检查接口/实现位置P0
3Application 层纯编排，不含业务 if/else代码审查P0
4值对象不可变（final 字段，无 setter）ValueObject 类检查P1
5跨聚合通过 ID 引用聚合根字段类型检查P1
6DTO 在 API 层定义，不泄露到 Domain检查 Domain 中 DTO importP0
7Composition Root 集中管理 DI检查各层是否有 new 依赖P1

详见 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 组装
模块依赖规则
模块可依赖不可依赖
core/domain无（纯 Java）Spring/JPA/MyBatis
core/applicationdomaininfrastructure, api
infrastructurecoreapi
apicore, infrastructure—
composition所有模块—

开发规范（详见各 references）

#规范违规示例
1Domain 零框架依赖import org.springframework.stereotype.Service
2Repository 接口在 Domain接口和实现都在 Infra
3Application 只编排不实现AppService 包含业务判断
4事务边界在 ApplicationController 或 Repository 开事务
5跨聚合通过领域事件聚合 A 直接引用聚合 B
6值对象不可变ValueObject 有 setter
7实体充血模型实体只有 getter/setter
8DTO 在 API 层定义Domain 中有 DTO import
9Composition Root 最外层各层自己 new 依赖
10严格分层API 直接调用 Infrastructure

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

文件用途
references/01-domain-model.md领域层设计详解：聚合根、值对象、领域服务
references/02-application-interfaces.md应用层接口设计：服务编排与事务边界
references/03-infrastructure-implementation.md基础设施层实现：Repository、MQ、外部集成
references/04-api-adapters.mdAPI 适配层：Controller、DTO、Assembler
references/05-di-composition.mdDI 组装：Composition Root 配置
references/06-testing.md测试策略：单元测试、集成测试、契约测试
references/07-migration-from-layered.md从三层架构迁移到洋葱架构的完整路径
references/08-comparison.md洋葱 vs 六边形 vs 整洁架构详细对比

Examples

业务场景示例
示例说明
examples/example-01-order-payment.md订单支付完整示例（含 Domain/Application/Infra/API）
examples/example-02-product-catalog.md产品目录管理示例（含多聚合协作）
examples/example-03-multi-entry.md多入口系统示例（REST + MQ + CLI 三种适配器）
examples/example-04-cqrs-onion.mdCQRS + 洋葱融合示例（Command/Query 分离）
examples/example-05-user-registration.md用户注册 + 邮件验证示例
项目规模示例
示例说明
examples/06-monolith-simple.md单体简单：单模块项目，一个限界上下文
examples/07-monolith-complex.md单体复杂：单模块多限界上下文，内部隔离
examples/08-monolith-multi-module.md单体多模块：Maven 多模块强制分层
examples/09-microservice-simple.md微服务简单：单服务单上下文洋葱
examples/10-microservice-complex.md微服务复杂：单服务多上下文内部隔离
examples/11-microservice-multi-module.md微服务多模块：单服务 Maven 多模块洋葱
examples/12-microservice-complex-multi.md微服务复杂多模块：多上下文 Maven 多模块

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 模块
  • 领域事件已发布

Comments

Markdown supported