DDD Hexagonal Architecture

Design and implement software using Domain-Driven Design with Hexagonal Architecture. This skill provides patterns, templates, and best practices for building maintainable domain-centric applications.

Scripts

创建 DDD 项目

当用户说"创建 DDD 项目"、"新建项目"、"创建项目"、"创建ddd项目"时，必须使用 scripts/create-ddd-project.sh 脚本。

脚本支持系统: Windows (Git Bash/MSYS2)、Mac (macOS)、Linux，自动检测并适配。

⚠️ 环境提醒: 建议提前安装 JDK 17+ 和 Maven 3.8.*，脚本启动时会自动检测并给出各平台安装指引，未安装也可继续但可能导致生成失败。

⚠️ 重要提醒：必须询问用户项目创建地址

在创建项目前，如果用户没有明确给出工程创建地址，必须询问用户在哪里创建项目。 不能随意创建到默认目录，必须获得用户确认。

示例对话：
CODEBLOCK0

流程:

必须询问用户，如果用户未指定，列出可选项供用户选择。

示例：
CODEBLOCK1

2. 第二步：填写项目配置（逐一询问，直接回车使用默认值）

| 参数 | 说明 | 默认值 | 示例 |
|------|------|--------|------|
| GroupId | Maven 坐标 groupId，标识组织或公司 | com.yourcompany | cn.bugstack |
| ArtifactId | 项目模块唯一标识名称 | your-project-name | order-system |
| Version | 项目版本号 | 1.0.0-SNAPSHOT | 1.0.0-RELEASE |
| Package | Java 代码根包名 | 自动从 GroupId + ArtifactId 推导 | cn.bugstack.order |
| Archetype 版本 | 脚手架模板版本 | 1.8 | - |

3. 第三步：确认并生成

显示所有配置，确认后执行 Maven Archetype 生成项目。

脚本执行方式（在 xfg-ddd-skills 项目根目录下运行）:
CODEBLOCK2

⚠️ 必须先 cd 到 xfg-ddd-skills 项目目录下再执行，脚本会自动定位自身路径。
AI 负责引导用户选择目录、填写参数，无需手动拼凑 Maven 命令。
⚠️ 再次强调：创建项目前必须询问用户项目创建地址，不能随意创建！

Quick Reference

Task	Reference
Architecture overview	references/architecture.md
Entity design

Architecture Layers

CODEBLOCK3

Dependency Rule: INLINECODE11

⚠️ Domain 层设计自检清单

在生成 Domain 层代码前，必须逐项检查：

1. 是否有多种处理方式（if-else 判断类型）？
→ 是：使用策略模式（IXxxStrategy 接口 + 实现类 + Map<String, IXxxStrategy> 注入）

2. 是否有多个独立的校验/过滤步骤（3步以上）？
→ 是：使用责任链模式（IXxxFilter 接口 + Factory 组装链）

3. Service 方法是否超过 60 行？
→ 是：拆分为过滤器（校验）+ 策略（执行）+ 私有方法（保存）

4. Infrastructure 层是否包含业务判断逻辑？
→ 是：将业务校验移到 Domain 层的过滤器中，Infrastructure 只做数据读写

5. 是否跨域直接依赖另一个 Domain 的 Repository？
→ 是：通过 Case 层编排，或在本域 Repository 接口中聚合所需数据

6. Infrastructure 包名是否正确？
→ Repository 实现：adapter/repository/（❌ 不是 persistent/repository/）
→ DAO 操作：dao/（❌ 不是 scenario/dao/ 或其他包）
→ Redis 操作：redis/（❌ 不是 config/）

Domain Layer 目录结构

CODEBLOCK4

⚠️ 注意：model/ 下没有单独的 command/ 包，命令实体统一放在 entity/ 包下。

🔄 新功能开发完整流程

当用户需要实现一个新功能时，必须按照以下分层调用流程进行开发：

调用链路图

CODEBLOCK5

分层职责速查表

层级	职责	禁止做的事	依赖方向
Trigger	接收请求、参数校验、路由转发	业务逻辑、直接操作数据库	→ API/Case/Domain
Case

开发流程检查清单

当用户说"帮我实现一个 XXX 功能"时，按以下顺序检查：

Step 1: 确定入口方式（Trigger）

询问用户或根据需求判断：

CODEBLOCK6

Step 2: 判断是否需要 Case 层

CODEBLOCK7

Step 3: Domain 层设计

CODEBLOCK8

Step 4: Infrastructure 层实现

CODEBLOCK9

代码示例：完整调用链

以"订单支付"功能为例，展示完整分层调用：

1. Trigger 层（HTTP Controller）

CODEBLOCK10

2. Case 层（业务编排）

CODEBLOCK11

3. Domain 层（领域服务）

CODEBLOCK12

4. Infrastructure 层（技术实现）

CODEBLOCK13

常见问题与纠正

❌ 错误1：Trigger 层直接调用 Repository

CODEBLOCK14

纠正：Trigger 层只负责接收请求和路由，业务逻辑应下沉到 Domain 层。

❌ 错误2：Domain Service 直接依赖 DAO

CODEBLOCK15

纠正：Domain 层应依赖 Repository 接口，由 Infrastructure 层实现。

❌ 错误3：Infrastructure 层包含业务逻辑

CODEBLOCK16

纠正：业务判断应在 Domain 层完成，Infrastructure 层只负责数据读写。

❌ 错误4：跨域直接调用 Repository

CODEBLOCK17

纠正：跨域操作应通过 Case 层编排，或调用目标领域的 Service 接口。

总结口诀

CODEBLOCK18

📦 新功能开发规范

当用户需要增加新功能时，按照以下决策流程进行开发：

决策流程图

CODEBLOCK19

决策指南

问题	答案	处理方式
现有领域能否支持新功能？	✅ 是	在现有 Service 中添加方法
是否需要跨多个领域？

场景一：扩展现有领域服务

判断条件：新功能属于现有领域的业务范围。

开发步骤：

1. 检查现有领域服务

- 查看 domain/{domain}/service/ 目录 - 确认是否有相关的 Service 接口

2. 扩展现有 Service

- 在现有接口中添加新方法 - 在实现类中实现新方法

示例：在交易域添加一个"查询订单列表"功能

CODEBLOCK20

场景二：创建新的领域

判断条件：新功能涉及全新的业务领域，与现有领域无关。

开发步骤：

1. 创建完整的领域结构

CODEBLOCK21

2. 定义 Adapter 接口

CODEBLOCK22

3. 定义 Model

CODEBLOCK23

4. 实现 Service

   public interface I{Xxx}Service {
       void process(XxxEntity entity) throws Exception;
   }
   
   @Slf4j
   @Service
   public class XxxServiceImpl implements I{Xxx}Service {
       
       @Resource
       private I{Xxx}Repository repository;
       
       @Resource
       private I{Xxx}Port port;
       
       @Override
       public void process(XxxEntity entity) throws Exception {
           log.info("处理业务:{}", entity.getId());
           // 业务逻辑
           repository.save(entity);
           port.notify(entity);
       }
   }

场景三：创建 Case 层

判断条件：业务涉及多个领域协作，或需要编排多个领域服务。

开发步骤：

1. 创建 Case 模块结构

CODEBLOCK25

2. 定义 Case 接口

CODEBLOCK26

3. 实现 Case 编排

CODEBLOCK27

Case 层命名规范：

- 接口命名：INLINECODE25
实现类命名：INLINECODE26

场景四：Trigger 直接调用 Domain

判断条件：轻量工程，业务简单，不需要 Case 层编排。

开发步骤：

1. 在 Trigger 层直接调用 Domain

CODEBLOCK28

2. Trigger 层职责

- 接收请求参数 - 参数校验 - 调用 Domain 层 - 处理异常 - 返回响应

场景五：Trigger 复杂化后重构为 Case 层

判断条件：Trigger 层代码越来越复杂，包含大量业务逻辑。

警告信号：

- Controller 代码超过 100 行
Controller 中有大量 if-else 判断
Controller 依赖多个 Domain Service
业务逻辑难以测试

重构步骤：

1. 询问用户

CODEBLOCK29

2. 创建 Case 层

- 按照场景三的方式创建 Case 模块 - 将 Controller 中的业务逻辑移到 Case 层

3. 简化 Trigger 层

   // 重构前
   @RestController
   public class XxxController {
       @Resource private IDomain1Service d1;
       @Resource private IDomain2Service d2;
       @Resource private IDomain3Service d3;
       
       public Response process(Request req) {
           // 100+ 行业务逻辑...
       }
   }
   
   // 重构后
   @RestController
   public class XxxController {
       @Resource private I{Xxx}Case xxxCase;
       
       public Response process(Request req) {
           xxxCase.execute(req);
           return Response.success();
       }
   }

完整开发流程示例

需求：在拼团系统中添加"订单超时取消"功能

步骤 1：检查现有领域
CODEBLOCK31

步骤 2：决策

- 现有领域（trade）已有相关服务
需要扩展现有 Service
不需要创建新领域

步骤 3：实现

CODEBLOCK32

步骤 4：添加 Trigger

@Component
public class OrderTimeoutJob {
    
    @Resource
    private ITradeLockOrderService tradeLockOrderService;
    
    @Scheduled(cron = "0 */5 * * * ?")  // 每5分钟执行
    public void execute() {
        try {
            tradeLockOrderService.handleTimeoutOrders();
        } catch (Exception e) {
            log.error("订单超时处理异常", e);
        }
    }
}

规范速查表

场景	判断条件	实现位置
扩展现有服务	功能属于现有领域	INLINECODE27
创建新领域

全新业务领域 | 创建完整的 domain/{new}/ 结构 |
| 创建 Case 层 | 多领域协作、复杂业务 | case/{domain}/{capability}/ |
| Trigger 调用 | 轻量工程、简单业务 | trigger/{domain}/controller/ |
| 重构为 Case | Trigger 越来越复杂 | 询问用户后重构 |

核心原则：

1. 优先复用：先检查现有领域是否能支持
单一职责：新功能归到对应领域，不随意扩张
适度分层：简单场景直接调用，复杂场景创建 Case
持续演进：Trigger 复杂化时，询问用户是否重构

Quick Templates

Aggregate 聚合对象

CODEBLOCK34

Entity 普通实体

CODEBLOCK35

Entity 命令实体（放在 entity 包）

CODEBLOCK36

Value Object 值对象

CODEBLOCK37

EnumVO 枚举值对象（可包含策略逻辑）

CODEBLOCK38

Domain Service 完整编码

CODEBLOCK39

策略模式实现

CODEBLOCK40

Core Principles

Principle	Description
Dependency Inversion	Domain defines interfaces, Infrastructure implements
Rich Domain Model

When to Use DDD

Use DDD when:

- Complex business domain with rich rules
Need to capture domain knowledge in code
Long-lived project with evolving requirements
Team needs shared domain language

Don't use DDD when:

- Simple CRUD operations
Prototype or throwaway code
Domain logic is trivial
Team unfamiliar with DDD concepts

Example Projects

- group-buy-market - E-commerce domain
ai-mcp-gateway - API gateway domain

🚀 DevOps 部署完整流程

📋 部署检查清单

当用户需要部署 DDD 项目时，按照以下流程执行：

1. 确认项目信息

- [ ] 项目名称（artifactId）
[ ] 项目路径（代码根目录）
[ ] 部署环境（开发/测试/生产）
[ ] 基础依赖（MySQL/Redis/RabbitMQ）

2. 打包构建

CODEBLOCK41

3. 基础镜像拉取（加速）

CODEBLOCK42

4. 数据库部署

CODEBLOCK43

5. 应用容器构建

CODEBLOCK44

6. 应用启动

CODEBLOCK45

7. 验证部署

# 查看容器状态
docker ps -a | grep {artifactId}

# 查看应用日志
docker logs -f {artifactId}

# 健康检查
curl http://localhost:{port}/actuator/health

📁 标准部署目录结构

CODEBLOCK47

🐳 Dockerfile 标准模板

CODEBLOCK48

📦 docker-compose-app.yml 标准模板

CODEBLOCK49

🗄️ docker-compose-environment-aliyun.yml 标准模板

CODEBLOCK50

🚀 快速启动/停止脚本

start.sh

CODEBLOCK51

stop.sh

#!/bin/bash

CONTAINER_NAME={artifactId}

echo "停止容器 ${CONTAINER_NAME}"
docker stop ${CONTAINER_NAME}
docker rm ${CONTAINER_NAME}

echo "容器已停止"

🔧 application-prod.yml 标准配置

CODEBLOCK53

📊 阿里云镜像加速仓库

所有镜像已同步到阿里云，使用前缀 INLINECODE31

📦 镜像来源：docker-image-pusher
添加新镜像：在 images.txt 添加镜像名，等待1分钟同步

常用镜像速查表

原始镜像	阿里云加速地址	用途
JDK/Java
openjdk:8-jre-slim

拉取镜像示例

CODEBLOCK54

⚠️ 常见问题处理

1. MySQL 8.0 认证问题

CODEBLOCK55

2. 容器网络不通

确保所有容器在同一个网络： CODEBLOCK56

3. 端口冲突

修改 docker-compose.yml 中的端口映射： CODEBLOCK57

4. 应用无法连接数据库

检查环境变量配置和健康检查依赖：

depends_on:
  mysql:
    condition: service_healthy

📝 部署操作流程示例

当用户说"帮我部署 ai-mcp-gateway"时，执行：

1. 确认项目信息

- 项目路径：/Users/fuzhengwei/Documents/project/ddd-demo/ai-mcp-gateway - 端口：8091 - 镜像：INLINECODE74

2. 执行部署

CODEBLOCK59

3. 部署完成检查

- 容器状态正常 - 日志无报错 - 健康检查通过

DDD 六边形架构

使用领域驱动设计与六边形架构来设计和实现软件。该技能提供了构建可维护的、以领域为中心的应用程序的模式、模板和最佳实践。

脚本

创建 DDD 项目

当用户说创建 DDD 项目、新建项目、创建项目、创建ddd项目时，必须使用 scripts/create-ddd-project.sh 脚本。

脚本支持系统: Windows (Git Bash/MSYS2)、Mac (macOS)、Linux，自动检测并适配。

⚠️ 环境提醒: 建议提前安装 JDK 17+ 和 Maven 3.8.*，脚本启动时会自动检测并给出各平台安装指引，未安装也可继续但可能导致生成失败。

⚠️ 重要提醒：必须询问用户项目创建地址

在创建项目前，如果用户没有明确给出工程创建地址，必须询问用户在哪里创建项目。 不能随意创建到默认目录，必须获得用户确认。

示例对话：

用户：帮我创建一个 DDD 项目
AI：好的，我来帮您创建 DDD 项目。请问您希望将项目创建在哪个目录？
例如：
1) /Users/xxx/projects
2) /Users/xxx/Documents
3) /home/xxx/workspace
4) 其他路径（请直接输入）

用户：创建在 /Users/xxx/projects 下
AI：确认在 /Users/xxx/projects 下创建项目，开始执行...

流程:

必须询问用户，如果用户未指定，列出可选项供用户选择。

示例：

📂 选择项目生成目录
──────────────────────────────
1) /Users/xxx/projects
2) /Users/xxx/Documents
3) /home/xxx/workspace
4) 自定义路径（直接输入路径）

直接回车 = 选择 [1]

2. 第二步：填写项目配置（逐一询问，直接回车使用默认值）

| 参数 | 说明 | 默认值 | 示例 |
|------|------|--------|------|
| GroupId | Maven 坐标 groupId，标识组织或公司 | com.yourcompany | cn.bugstack |
| ArtifactId | 项目模块唯一标识名称 | your-project-name | order-system |
| Version | 项目版本号 | 1.0.0-SNAPSHOT | 1.0.0-RELEASE |
| Package | Java 代码根包名 | 自动从 GroupId + ArtifactId 推导 | cn.bugstack.order |
| Archetype 版本 | 脚手架模板版本 | 1.8 | - |

3. 第三步：确认并生成

显示所有配置，确认后执行 Maven Archetype 生成项目。

脚本执行方式（在 xfg-ddd-skills 项目根目录下运行）:
bash
bash scripts/create-ddd-project.sh

⚠️ 必须先 cd 到 xfg-ddd-skills 项目目录下再执行，脚本会自动定位自身路径。
AI 负责引导用户选择目录、填写参数，无需手动拼凑 Maven 命令。
⚠️ 再次强调：创建项目前必须询问用户项目创建地址，不能随意创建！

快速参考

任务	参考
架构概览	references/architecture.md
实体设计

架构层次

┌─────────────────────────────────────────────────────────────┐
│ 触发层 │
│ (HTTP 控制器 / MQ 监听器 / 任务) │
└─────────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ API 层 │
│ (DTO / 请求 / 响应) │
└─────────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Case 层 │
│ (编排 / 业务流程) │
└─────────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ 领域层 │
│ (实体 / 聚合 / 值对象 / 领域服务) │
└─────────────────────────┬───────────────────────────────────┘
▲
┌─────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ (仓储实现 / 端口适配器 / DAO / PO) │
└─────────────────────────────────────────────────────────────┘

依赖规则: 触发层 → API 层 → Case 层 → 领域层 ← 基础设施层

⚠️ 领域层设计自检清单

在生成领域层代码前，必须逐项检查：

1. 是否有多种处理方式（if-else 判断类型）？
→ 是：使用策略模式（IXxxStrategy 接口 + 实现类 + Map 注入）

2. 是否有多个独立的校验/过滤步骤（3步以上）？
→ 是：使用责任链模式（IXxxFilter 接口 + Factory 组装链）

3. Service 方法是否超过 60 行？
→ 是：拆分为过滤器（校验）+ 策略（执行）+ 私有方法（保存）

4. 基础设施层是否包含业务判断逻辑？
→ 是：将业务校验移到领域层的过滤器中，基础设施层只做数据读写

5. 是否跨域直接依赖另一个领域的仓储？
→ 是：通过 Case 层编排，或在本域仓储接口中聚合所需数据

6. 基础设施包包名是否正确？
→ 仓储实现：adapter/repository/（❌ 不是 persistent/repository/）
→ DAO 操作：dao/（❌ 不是 scenario/dao/ 或其他包）
→ Redis 操作：redis/（❌ 不是 config/）

领域层目录结构

model/
├── aggregate/ # 聚合对象
│ └── XxxAggregate.java
├── entity/ # 实体对象
│ ├── XxxEntity.java # 普通实体
│ └── XxxCommandEntity.java # 命令实体
└── valobj/ # 值对象
├── XxxVO.java # 普通值对象
└── XxxEnumVO.java # 枚举值对象

⚠️ 注意：model/ 下没有单独的 command/ 包，命令实体统一放在 entity/ 包下。

🔄 新功能开发完整流程

当用户需要实现一个新功能时，必须按照以下分层调用流程进行开发：

调用链路图

┌─────────────────────────────────────────────────────────────────────────┐
│ 新功能开发流程 │
└─────────────────────────────────────────────────────────────────────────┘

外部请求
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. 触发层（触发层） │
│ 职责：接收外部请求，路由转发，参数校验，不含业务逻辑 │
│ │
│ • HTTP 控制器 → 接收 HTTP 请求

xfg-ddd-skillsDDD六边形架构

xfg-ddd-skills

DDD Hexagonal Architecture

Scripts

创建 DDD 项目

Quick Reference

Architecture Layers

⚠️ Domain 层设计自检清单

Domain Layer 目录结构

🔄 新功能开发完整流程

调用链路图

分层职责速查表

开发流程检查清单

Step 1: 确定入口方式（Trigger）

Step 2: 判断是否需要 Case 层

Step 3: Domain 层设计

Step 4: Infrastructure 层实现

代码示例：完整调用链

1. Trigger 层（HTTP Controller）

2. Case 层（业务编排）

3. Domain 层（领域服务）

4. Infrastructure 层（技术实现）

常见问题与纠正

❌ 错误1：Trigger 层直接调用 Repository

❌ 错误2：Domain Service 直接依赖 DAO

❌ 错误3：Infrastructure 层包含业务逻辑

❌ 错误4：跨域直接调用 Repository

总结口诀

📦 新功能开发规范

决策流程图

决策指南

场景一：扩展现有领域服务

场景二：创建新的领域

场景三：创建 Case 层

场景四：Trigger 直接调用 Domain

场景五：Trigger 复杂化后重构为 Case 层

完整开发流程示例

规范速查表

Quick Templates

Aggregate 聚合对象

Entity 普通实体

Entity 命令实体（放在 entity 包）

Value Object 值对象

EnumVO 枚举值对象（可包含策略逻辑）

Domain Service 完整编码

策略模式实现

Core Principles

When to Use DDD

Example Projects

🚀 DevOps 部署完整流程

📋 部署检查清单

1. 确认项目信息

2. 打包构建

3. 基础镜像拉取（加速）

4. 数据库部署

5. 应用容器构建

6. 应用启动

7. 验证部署

📁 标准部署目录结构

🐳 Dockerfile 标准模板

📦 docker-compose-app.yml 标准模板

🗄️ docker-compose-environment-aliyun.yml 标准模板

🚀 快速启动/停止脚本

start.sh

stop.sh

🔧 application-prod.yml 标准配置

📊 阿里云镜像加速仓库

常用镜像速查表

拉取镜像示例

⚠️ 常见问题处理

1. MySQL 8.0 认证问题

2. 容器网络不通

3. 端口冲突

4. 应用无法连接数据库

📝 部署操作流程示例

DDD 六边形架构

脚本

创建 DDD 项目

快速参考

架构层次