ddd-best-practices

DDD Best Practices

Overview

面向 Java / Spring Boot 项目的 DDD 落地指南，提供分层决策、领域建模、代码模板、测试策略、审查清单与重构路线图。

Core principle: 先判断复杂度与边界 -> 先收紧依赖与模型 -> 先补关键测试 -> 再按真实信号演进分层与模式。

Announce at start: "正在使用 ddd-best-practices skill 为你提供 DDD 架构指导。"

Prerequisites

• 目标项目为 Java / Spring Boot 技术栈
• 非 Java 项目（Go / Python / Node）请勿使用本 skill

Workflow

Phase 1: 判断当前阶段，选择对应参考

根据用户的问题类型，读取对应的 reference 文档：

用户场景	读取文档
初始化 / 新模块设计	layering-decision-matrix.md → project-structure.md
领域建模 / 聚合 / ACL 设计	domain-modeling.md
快速落地查模板	code-templates.md（~1100 行，用顶部对照表定位）
命名拿不准	naming-conventions.md
测试策略 / TDD 落地	testing-strategy.md
代码审查 / 边界收紧	code-review-checklist.md → boundary-smells.md
MVC → DDD 渐进重构	refactoring-guide.md
复杂规则建模 / 流程编排	design-patterns.md（~900 行，按目录跳转）

Phase 2: 确保最小闭环

在给出建议时，优先检查这 5 条基线是否满足，再考虑引入更多抽象：

1. domain 纯净，依赖方向正确
2. trigger 不直接依赖 repository / mapper / 外部客户端
3. repository 接口不暴露 refreshCache / evictCache / cacheXxx 等技术语义
4. ACL / 外部适配器返回领域对象，而不是把外部 DTO 直接带进领域
5. 关键不变量有领域单元测试，并按职责边界补齐各层测试

Phase 3: 按场景执行

场景 A: 新项目 / 新模块

1. 用 layering-decision-matrix.md 判断最小可行分层
2. 用 project-structure.md 选择目录结构与 POM 多模块依赖
3. 用 domain-modeling.md 设计实体 / 值对象 / 聚合 / 仓储 / Port
4. 用 code-templates.md 按层拷贝代码骨架
5. 命名拿不准时查 naming-conventions.md
6. 用 testing-strategy.md 规划测试分层
7. 只在规则明显膨胀时，再引入 design-patterns.md 中的模式

场景 B: 测试策略与 TDD 落地

1. 先判断当前要验证的是领域规则、用例编排、HTTP 契约，还是持久化/外部集成风险
2. 领域规则优先写纯单测，不启动 Spring；关键不变量在 Entity / VO / DomainService 层锁住
3. application / use case 只测编排、事务边界、幂等与跨聚合协调；可 mock 仓储接口、Port，不要 mock Entity / VO
4. Controller 默认使用 @WebMvcTest + MockMvc；默认 mock 应用服务 / use case
5. Repository / Adapter / 复杂 Mapper 通过集成测试验证，必要时使用 Testcontainers
6. 仅保留少量 @SpringBootTest 烟雾测试验证关键全链路 wiring

场景 C: 审查与边界收紧

1. 用 code-review-checklist.md 做结构化检查
2. 用 boundary-smells.md 对照常见反模式
3. 检查测试边界：是否用 controller 测试兜底领域规则、是否大量 mock mapper、是否缺少集成测试
4. 先修"依赖方向、边界绕过、DTO 穿透、缓存语义泄漏、测试边界错位"
5. 修完后立刻补领域测试与关键集成测试，锁住行为

场景 D: MVC 到 DDD 重构

1. 先识别限界上下文与用例边界
2. 先封装 Repository / Port，再重构模型
3. 先做最小模块拆分，避免一次性把 application / api / querys 全预埋
4. 优先把关键规则沉回模型或领域服务
5. 每次边界收紧前后，优先补 domain 与 application 层的保护性测试

Phase 4: 判断是否继续演进

只有当出现真实信号时，再建议引入：

信号	引入
多入口共用同一用例编排、跨聚合编排膨胀	application 层
需要对外发布/复用 RPC 契约	api 模块
出现独立读模型、CQRS、报表/搜索等读侧复杂性	querys 模块
跨聚合一致性问题已真实出现	领域事件 / MQ

Common Mistakes

• 为了"像 DDD"而盲目补层：模块数量不是成熟度的代名词，先满足当前复杂度
• Domain 层混入技术细节：不要在 domain 中放 Spring / MyBatis / Redis / HTTP 客户端
• 先上模式再有场景：两个 if-else 不值得上责任链 / 决策树
• 用一种测试覆盖所有：领域规则、编排、HTTP 契约和持久化风险应按责任边界分层测试
• @SpringBootTest 当默认：Controller 默认使用切片测试，Repository / Adapter 默认使用真实集成测试
• 大量 mock mapper：若 application / domain 测试必须 mock mapper，优先回看职责划分是否混乱

References

• layering-decision-matrix.md — 分层增减决策矩阵
• project-structure.md — 渐进式项目结构与 Maven 多模块 POM
• domain-modeling.md — 领域建模指南 + 速查模板
• code-templates.md — 按层代码模板速查 + 端到端示例（~1100 行，用顶部对照表定位）
• naming-conventions.md — 包/类/接口/方法/数据库命名速查
• design-patterns.md — 领域层模式落地范式（~900 行，按目录跳转）
• testing-strategy.md — DDD 测试分层与 Mock 边界
• code-review-checklist.md — DDD 代码审查清单
• boundary-smells.md — 常见边界异味与修复策略
• refactoring-guide.md — MVC 到 DDD 渐进重构指南