# ddd-archetype

**Repository Path**: roylion/ddd-archetype

## Basic Information

- **Project Name**: ddd-archetype
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DDD-Archetype

DDD 领域驱动设计骨架项目，基于 Java 17 + Spring Boot 3.2 构建，采用分层架构 + 事件驱动设计，支持 DDD 传统四层架构与三层 Service 架构的混合模式。

---

## 技术栈

| 技术 | 版本 |
|------|------|
| Java | 17 |
| Spring Boot | 3.2.0 |
| Maven | 3.x |
| Lombok | 1.18.30 |
| MapStruct | 1.5.5.Final |
| Guava | 33.5.0-jre |

---

## 模块结构

```
ddd-archetype
├── ddd-common          # 公共模块 - 跨层共享的技术契约
├── ddd-domain          # 领域层 - 核心业务逻辑
├── ddd-application     # 应用层 - 业务编排与流程控制
├── ddd-infrastructure  # 基础设施层 - 技术实现
├── ddd-service         # 服务层 - 传统三层架构服务
├── ddd-interfaces      # 接口层 - REST API / 消息消费
└── ddd-starter         # 启动模块 - Spring Boot 入口
```

### 模块依赖关系

```
ddd-interfaces
    ├── ddd-application       (DDD 复杂业务编排)
    ├── ddd-service           (简单业务 / 通用查询)
    └── Spring Web / Validation

ddd-application
    └── ddd-domain

ddd-service
    └── ddd-infrastructure

ddd-infrastructure
    ├── ddd-domain
    └── ddd-common

ddd-domain
    └── ddd-common

ddd-common
    └── Lombok / SLF4J / Guava

ddd-starter
    ├── ddd-interfaces
    └── ddd-infrastructure
```

---

## 分层规范

### ddd-common（公共模块）

**职责**：提供跨层共享的基础组件和技术契约，不含业务语义。

**包含内容**：
- `event/` - 事件基类与事件总线接口（`Event`, `DomainEvent`, `ApplicationEvent`, `IntegrationEvent`, `EventBus`）
- `file/` - 文件存储网关接口（`FileStorage`）
- `event/` - 事件序列化器接口（`EventSerializer`）
- `exception/` - 业务异常（`BusinessException`）
- `result/` - 统一返回结果（`Result<T>`）
- `constant/` - 公共常量（`CommonConstants`, `Topics`）

**设计原则**：
- 纯技术性契约，可被所有上层模块依赖
- 后续可抽取为独立的外部 common 包

---

### ddd-domain（领域层）

**职责**：核心业务逻辑，包含聚合根、实体、值对象、领域服务、领域事件、仓储接口。

**包结构**（以 example 模块为例）：

```
domain/example/
├── entity/          # 聚合根、实体、值对象
├── event/           # 领域事件定义
├── gateway/         # 领域网关接口（防腐层）
├── repository/      # 仓储接口（定义在 domain，实现在 infrastructure）
└── service/         # 领域服务（跨实体业务逻辑）
```

**关键规范**：
- 领域事件定义在 `domain/event`，处理在 `application/event/domain`
- 仓储接口只负责聚合根的持久化生命周期
- 禁止直接依赖基础设施

---

### ddd-application（应用层）

**职责**：业务编排、流程控制、事务管理。协调领域层完成用例。

**包结构**（以 example 模块为例）：

```
application/example/
├── dto/             # Command / Query / DTO
├── event/
│   ├── app/         # 应用事件定义 + 处理器
│   ├── domain/      # 领域事件处理器（监听 domain 事件 → 转 Command/集成事件）
│   └── integration/ # 集成事件发布 / 消费
└── service/         # 应用服务（AppService）
```

**关键规范**：
- `AppService` 是应用层的入口，一个用例对应一个方法
- Command 表示写操作，Query 表示读操作
- 领域事件处理器负责将领域事件转换为应用层可处理的 Command 或集成事件

---

### ddd-infrastructure（基础设施层）

**职责**：技术实现，包括数据持久化、消息队列、外部服务调用、序列化等。

**包结构**（以 example 模块为例）：

```
infrastructure/example/
├── gateway/         # 领域网关实现（调用第三方服务）
├── persistence/     # 仓储实现、PO、Mapper
│   ├── entity/      # JPA Entity / PO
│   ├── mapper/      # 领域对象 ↔ PO 转换器
│   └── repository/  # Repository 实现类
└── config/          # 配置类（JacksonConfig 等）

infrastructure/event/              # 事件基础设施
├── EventBusImpl.java              # 事件总线实现
├── EventSerializer.java           # 序列化器接口（common 层定义）
├── JacksonEventSerializer.java    # Jackson 实现
└── IntegrationEventMixin.java     # Jackson Mixin（屏蔽 topic 序列化）
```

**关键规范**：
- `IntegrationEvent.topic` 是内部路由字段，通过 Mixin 屏蔽序列化，不写入消息体
- `sourceService` 由基础设施层自动填充（读取 `spring.application.name`）
- 序列化/反序列化能力统一封装在 `JacksonEventSerializer`

---

### ddd-service（服务层）

**职责**：传统三层架构的服务层，处理不需要领域模型的简单业务逻辑。

**适用场景**：
- 简单 CRUD、文件操作、缓存操作
- 通用查询、数据统计、报表
- 外部 API 代理
- 不涉及聚合根状态变更的轻量级业务

**与 application 层的区别**：

| 维度 | ddd-service | ddd-application |
|------|-------------|-----------------|
| 业务复杂度 | 简单 | 复杂 |
| 是否依赖 domain | 否 | 是 |
| 是否操作聚合根 | 否 | 是 |
| 典型场景 | 文件上传、通用查询 | 订单创建、支付流程 |

---

### ddd-interfaces（接口层）

**职责**：系统对外交互的入口，包括 REST API 和消息消费。

**包结构**（以 example 模块为例）：

```
interfaces/example/
├── controller/      # REST Controller + Request/Response/Assembler
└── consumer/        # MQ 消费者（接收外部集成事件）
```

**关键规范**：
- Controller 负责参数校验、调用 AppService/Service、返回 Result
- MQ Consumer 接收外部事件后，优先采用轻量模式：转 Command → 调 AppService
- 全局异常处理在 `interfaces/common/GlobalExceptionHandler`

---

### ddd-starter（启动模块）

**职责**：Spring Boot 应用入口，负责模块组装与启动。

---

## 事件规范

### 事件分类

本项目定义了 4 类核心事件：

| 事件类型 | 定义位置 | 作用范围 | 通信方式 |
|----------|---------|---------|---------|
| **领域事件** | `domain/event` | 进程内 | Spring `ApplicationEventPublisher` |
| **应用事件** | `application/event/app` | 进程内 | Spring `ApplicationEventPublisher` |
| **集成事件（发布）** | `application/event/integration/publish` | 跨服务 | MQ（Kafka/RocketMQ/RabbitMQ） |
| **集成事件（消费）** | `application/event/integration/consume` | 跨服务 | MQ 监听 |

### 事件基类体系

所有事件基类定义在 `ddd-common/event`，采用继承体系：

```
Event (eventId, eventTime)
├── DomainEvent (aggregateId, aggregateType)
├── ApplicationEvent (operationType)
└── IntegrationEvent (topic, sourceService)
```

#### Event（事件基类）

- `eventId`: UUID，自动生成，用于幂等和链路追踪
- `eventTime`: 事件发生时间，自动填充

#### DomainEvent（领域事件）

- 记录聚合根状态变更的事实
- 特点：不可变、可追溯、最终一致性
- 由聚合根在业务操作中产生，通过 `EventBus` 发布

#### ApplicationEvent（应用事件）

- 应用服务操作完成后的进程内通知
- 用于日志、统计、缓存刷新等横切逻辑
- 仅在 `application` 层内部广播

#### IntegrationEvent（集成事件）

- 用于跨服务通信，通过消息中间件发布和消费
- `topic`: 消息路由键（内部使用，**不序列化到消息体**）
- `sourceService`: 来源服务名，由基础设施层自动填充

### 事件总线（EventBus）

```java
public interface EventBus {
    void publish(Event event);
}
```

实现类 `EventBusImpl` 的分发逻辑：

| 事件类型 | 处理方式 |
|----------|---------|
| `DomainEvent` | 通过 `ApplicationEventPublisher` 进程内广播 |
| `ApplicationEvent` | 通过 `ApplicationEventPublisher` 进程内广播 |
| `IntegrationEvent` | 根据 `topic` 路由到对应 MQ 生产者 |

### 事件序列化

- 序列化器接口：`EventSerializer`（定义在 common 层）
- Jackson 实现：`JacksonEventSerializer`（定义在 infrastructure 层）
- `IntegrationEvent.topic` 通过 `IntegrationEventMixin` + `JacksonConfig` 屏蔽序列化

### 消费端事件规范

- 消费端的外部事件类**不需要继承** `IntegrationEvent`
- 推荐用纯 POJO，或最多继承 `Event` 获取 `eventId`/`eventTime`
- 消费流转：`MQ Listener` → `反序列化` → `转 Command` → `调 AppService`

---

## 文件存储规范

文件存储网关接口 `FileStorage` 定义在 `ddd-common/file`：

```java
public interface FileStorage {
    void upload(InputStream inputStream, String relativePath);
    InputStream download(String relativePath);
    void delete(String relativePath);
    boolean exists(String relativePath);
    void copy(String sourceRelativePath, String targetRelativePath);
    String getUrl(String relativePath);
    String getMd5(String relativePath);
}
```

**路径设计原则**：
- 接口只处理**相对路径**（如 `2026/04/24/xxx.jpg`）
- 完整 URL 由实现类根据存储类型拼接（OSS 拼 CDN 域名，本地拼 `file://`）
- 存储层不感知外部 CDN 配置

---

## 快速开始

### 1. 编译项目

```bash
mvn clean install
```

### 2. 启动应用

```bash
cd ddd-starter
mvn spring-boot:run
```

或执行 `DddArchetypeApplication.main()`。

### 3. 访问服务

默认端口：`8080`

---

## 扩展指南

### 新增业务模块

以 `order` 模块为例，在各层创建对应的包结构：

```
domain/order/          # 聚合根、实体、值对象、领域事件、仓储接口、领域服务
application/order/     # AppService、Command/Query/DTO、事件处理器
infrastructure/order/  # 仓储实现、PO、Mapper、网关实现
interfaces/order/      # Controller、Request/Response、MQ Consumer
service/order/         # 简单业务 Service（可选）
```

### 新增集成事件

1. 在 `application/event/integration/publish` 定义事件类，继承 `IntegrationEvent`
2. 在 `Topics` 常量类中添加 topic
3. 在 `EventBusImpl.publishActions` 中注册 MQ 生产者
4. 消费端在 `interfaces/consumer` 中创建 MQ Listener

---

## 设计原则总结

1. **依赖方向**：上层依赖下层，`common` 被所有模块依赖
2. **领域纯净**：`domain` 层不依赖 Spring、不依赖具体数据库
3. **事件分层**：领域事件在 domain 定义，处理在 application；集成事件发布在 application，消费在 interfaces
4. **查询分离**：复杂查询（ES、时序库）不走 domain 层，直接在 service/application → infrastructure 完成
5. **防腐层**：外部服务调用通过 `domain/gateway` 定义接口，`infrastructure/gateway` 实现