ddd-architecture-onion
Comprehensive guidance for Onion Architecture (洋葱架构) — Jeffrey Palermo's onion architecture with domain-centric layered isolation, dependency inversion from outer to inner rings. Covers domain core, application interfaces, infrastructure implementation, and API adapters with full Java/Spring Boot examples. Use when user asks about onion architecture, 洋葱架构, Jeffrey Palermo, concentric architecture, or needs layered domain isolation.
- Installs
- 128
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/full-stack-skills/ddd-skills --skill ddd-architecture-onion- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads ddd-architecture-onion automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 四原则
- 应用核心独立于基础设施 — Domain 层不 import 任何框架/数据库类
- 内层定义接口，外层实现 — 如
OrderRepository接口在 Domain，实现在 Infrastructure - 依赖指向圆心 — Infrastructure → Application → Domain，不允许逆向
- 外层知道内层，内层不知道外层 — Domain 对 Infrastructure 一无所知
Rules
| # | 规则 | 检测方式 | 级别 |
|---|---|---|---|
| 1 | Domain 层零框架依赖 | 搜索 Domain 包中的框架 import | P0 |
| 2 | Repository 接口在 Domain，实现在 Infra | 检查接口/实现位置 | P0 |
| 3 | Application 层纯编排，不含业务 if/else | 代码审查 | P0 |
| 4 | 值对象不可变（final 字段，无 setter） | ValueObject 类检查 | P1 |
| 5 | 跨聚合通过 ID 引用 | 聚合根字段类型检查 | P1 |
| 6 | DTO 在 API 层定义，不泄露到 Domain | 检查 Domain 中 DTO import | P0 |
| 7 | Composition 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/application | domain | infrastructure, api |
| infrastructure | core | api |
| api | core, infrastructure | — |
| composition | 所有模块 | — |
开发规范（详见各 references）
| # | 规范 | 违规示例 |
|---|---|---|
| 1 | Domain 零框架依赖 | import org.springframework.stereotype.Service |
| 2 | Repository 接口在 Domain | 接口和实现都在 Infra |
| 3 | Application 只编排不实现 | AppService 包含业务判断 |
| 4 | 事务边界在 Application | Controller 或 Repository 开事务 |
| 5 | 跨聚合通过领域事件 | 聚合 A 直接引用聚合 B |
| 6 | 值对象不可变 | ValueObject 有 setter |
| 7 | 实体充血模型 | 实体只有 getter/setter |
| 8 | DTO 在 API 层定义 | Domain 中有 DTO import |
| 9 | Composition 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.md | API 适配层：Controller、DTO、Assembler |
| references/05-di-composition.md | DI 组装：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.md | CQRS + 洋葱融合示例（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 模块
- 领域事件已发布
FAQ
What does the ddd-architecture-onion skill do?
Comprehensive guidance for Onion Architecture (洋葱架构) — Jeffrey Palermo's onion architecture with domain-centric layered isolation, dependency inversion from outer to inner rings. Covers domain core, application interfaces, infrastructure implementation, and API adapters with full Java/Spring Boot examples. Use when user asks about onion architecture, 洋葱架构, Jeffrey Palermo, concentric architecture, or needs layered domain isolation.
How do I install ddd-architecture-onion?
Run npx skills add https://github.com/full-stack-skills/ddd-skills --skill ddd-architecture-onion in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ddd-architecture-onion/ (personal) or .claude/skills/ddd-architecture-onion/ (project).
Which AI agents can use ddd-architecture-onion?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is ddd-architecture-onion safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains ddd-architecture-onion?
It is published by full-stack-skills in full-stack-skills/ddd-skills. It has 128 recorded installs.
More from full-stack-skills/ddd-skills
ddd-domain-designer
full-stack-skills/ddd-skills
Domain-driven design complete workflow — event-storming-driven 6-step domain modeling process, aggregate design 5-principles + 6-rules, bounded context identification, entity/value object design patterns, domain event catalog, and code mapping. Use when user asks about domain modeling, 领域建模, aggregate design, 聚合设计, bounded context, 限界上下文, or needs to design DDD domain model.
ddd-code-reviewer
full-stack-skills/ddd-skills
DDD code review and anti-pattern detection — anemia model detection, layered compliance checking, aggregate design review, rich model verification, scoring system (5 dimensions), and ArchUnit automated validation. Use when user asks about code review, 代码审查, DDD review, 架构审查, anti-pattern detection, 反模式检测, or needs to check if code follows DDD.
ddd-event-storming
full-stack-skills/ddd-skills
Event Storming workshop facilitation guide — collaborative domain exploration methodology with 6-step process (chaos exploration/timeline/pivotal events/commands & actors/aggregate discovery/bounded context), standardized sticky note color conventions (orange/blue/yellow/green/pink/purple), workshop preparation and facilitation tips, and digital tool recommendations. Use when user asks about event storming, 事件风暴, workshop, 工作坊, domain exploration, collaborative modeling, or needs to organize a DDD discovery workshop.
ddd-api-designer
full-stack-skills/ddd-skills
API design from domain model — CQRS command/query separation, REST API endpoint design, data object conversion chain (PO→DO→DTO→VO), unified response format, OpenAPI/Swagger generation, BFF pattern, API versioning, and security design. Use when user asks about API design, REST API, OpenAPI, BFF, DTO design, 接口设计, or data object conversion.
ddd-architecture-clean
full-stack-skills/ddd-skills
Comprehensive guidance for Clean Architecture (整洁架构) — Robert C. Martin's Clean Architecture with Enterprise Business Rules, Use Cases, Interface Adapters, and Frameworks layers. Covers core entities, use case interactors, dependency rules, and full implementation steps with Java/Spring Boot examples. Use when user asks about Clean Architecture, 整洁架构, Robert Martin, Uncle Bob, use case driven architecture, or needs to implement DDD with clean architecture.
ddd-architecture-layered
full-stack-skills/ddd-skills
Comprehensive guidance for DDD Layered Architecture (DDD 四层架构) — Traditional 3-layer to DDD 4-layer transformation with Interface/Application/Domain/Infrastructure layers. Covers complete directory structure, dependency inversion, ArchUnit validation, Spring Boot integration, and step-by-step migration guide. Use when user asks about layered architecture, DDD four-layer, 分层架构, traditional layering with DDD, or needs a simple DDD entry point for small to medium teams.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.