# OrderCraft

**Repository Path**: HotJavaEn/order-craft

## Basic Information

- **Project Name**: OrderCraft
- **Description**: 领域驱动设计电商订单管理模块示例
- **Primary Language**: Unknown
- **License**: 0BSD
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-12
- **Last Updated**: 2025-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ddd, Java, Order

## README

# 领域驱动设计(DDD)电商订单管理系统

## 项目简介

这是一个基于领域驱动设计(DDD)理念构建的电商订单管理系统示例。项目采用 Spring Boot + MyBatis-Plus + MySQL 技术栈，通过实际业务场景展示了 DDD 的核心概念、分层架构和实现方法。

## 项目目标

- 深入理解并实践 DDD 的核心概念和原则
- 展示 DDD 分层架构在实际项目中的应用
- 演示实体、值对象、聚合、领域服务、仓储和领域事件等概念
- 提供一个可运行的参考实现，帮助理解 DDD 如何应用于电商系统

## 技术栈

- **核心框架**: Spring Boot 2.7.5
- **ORM 框架**: MyBatis-Plus 3.5.2
- **数据库**: MySQL 8.0
- **构建工具**: Maven
- **工具库**: Lombok, MapStruct
- **开发语言**: Java 11

## DDD 分层架构

项目严格遵循 DDD 的分层架构，各层职责明确：

### 接口层 (Interface Layer)
- 处理外部请求，如 HTTP 请求和响应
- 控制器 (Controller) 处理 API 接口
- 视图对象 (VO) 面向前端的数据结构
- 装配器 (Assembler) 实现 VO 与 DTO 的转换

### 应用层 (Application Layer)
- 协调领域对象完成用户用例
- 应用服务 (Application Service) 实现用例流程
- DTO (Data Transfer Object) 跨层数据传输
- 命令对象 (Command) 封装用例输入参数

### 领域层 (Domain Layer)
- 包含业务核心逻辑和规则
- 实体 (Entity) 具有唯一标识的对象
- 值对象 (Value Object) 无标识、不可变的对象
- 聚合 (Aggregate) 以及聚合根 (Aggregate Root)
- 领域服务 (Domain Service) 处理跨实体业务逻辑
- 领域事件 (Domain Event) 表示业务事件
- 仓储接口 (Repository Interface) 持久化的抽象

### 基础设施层 (Infrastructure Layer)
- 提供技术实现和支持
- 仓储实现 (Repository Implementation)
- 持久化对象 (PO) 与数据库表映射
- ORM 映射 (Mapper) 支持数据库操作
- 事件处理机制 (Event Processing)
- 外部服务集成 (External Service Integration)

## 核心领域模型

### 订单聚合 (Order Aggregate)
- **订单 (Order)**: 聚合根，包含订单基本信息和状态
- **订单项 (OrderItem)**: 订单中的商品项，包含产品信息、数量和金额

### 产品聚合 (Product Aggregate)
- **产品 (Product)**: 产品信息，包括名称、编码、价格等

### 值对象 (Value Objects)
- **Money**: 表示金额的值对象，封装货币金额
- **OrderNo**: 订单编号值对象
- **OrderStatus**: 订单状态值对象

## 领域事件系统

项目实现了完整的领域事件机制，包括：

### 事件定义
- OrderCreatedEvent: 订单创建事件
- OrderPaidEvent: 订单支付事件
- OrderCancelledEvent: 订单取消事件

### 事件发布
使用 DomainEventPublisher 接口和 Spring 的 ApplicationEventPublisher 发布事件：
```java
// 聚合根注册事件
order.registerEvent(new OrderCreatedEvent(order));

// 应用服务发布事件
order.getDomainEvents().forEach(eventPublisher::publish);
```

### 事件监听
通过 @EventListener 注解实现事件监听和处理：
```java
@EventListener
public void handleOrderCreatedEvent(OrderCreatedEvent event) {
    // 处理订单创建事件
}
```

### 事件持久化
支持将领域事件持久化到数据库，用于审计、重放或事件溯源。

## 业务流程

系统支持完整的订单生命周期管理：

1. **创建订单**: 用户选择商品和数量，指定收货地址
2. **支付订单**: 用户完成订单支付，修改订单状态
3. **订单发货**: 商家发货，更新订单状态
4. **完成订单**: 用户确认收货，订单完成
5. **取消订单**: 在符合条件时取消订单

## 项目结构

```
src/main/java/com/sakyamuni/ddd/
├── application              # 应用层
│   ├── dto                  # 数据传输对象
│   │   └── command          # 命令对象
│   └── service              # 应用服务
├── domain                   # 领域层
│   ├── order                # 订单领域
│   │   ├── entity           # 订单实体
│   │   ├── enums            # 订单相关枚举
│   │   ├── event            # 订单领域事件
│   │   ├── repository       # 订单仓储接口
│   │   ├── service          # 订单领域服务
│   │   └── valueobject      # 订单值对象
│   ├── product              # 产品领域
│   └── shared               # 共享领域概念
│       ├── entity           # 基础实体类
│       ├── event            # 领域事件基类
│       └── valueobject      # 共享值对象
├── infrastructure           # 基础设施层
│   ├── config               # 配置类
│   ├── event                # 事件基础设施
│   │   └── listener         # 事件监听器
│   └── persistence          # 持久化基础设施
│       ├── assembler        # PO-领域对象转换
│       ├── mapper           # MyBatis映射器
│       ├── po               # 持久化对象
│       └── repository       # 仓储实现
└── interfaces               # 接口层
    ├── assembler            # VO-DTO转换
    ├── controller           # 控制器
    ├── exception            # 异常处理
    └── vo                   # 视图对象
        └── request          # 请求对象
```

## 数据库表结构

系统包含以下核心表：

- **t_order**: 订单主表
- **t_order_item**: 订单项表
- **t_product**: 产品表
- **t_inventory**: 库存表
- **t_customer**: 客户表
- **t_address**: 地址表
- **t_payment**: 支付表
- **t_domain_event**: 领域事件表

## 如何运行项目

### 环境准备
- JDK 11+
- Maven 3.6+
- MySQL 8.0

### 数据库初始化
1. 创建数据库:
```sql
CREATE DATABASE order_craft DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

2. 导入初始化脚本:
```bash
mysql -u root -p order_craft < src/main/resources/db/schema.sql
```

### 修改配置
编辑 `application.yml` 文件，更新数据库连接信息:
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/order_craft?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password
```

### 构建和运行
```bash
# 编译项目
mvn clean package

# 运行项目
java -jar target/*.jar
```

## API 文档

### 创建订单
```
POST /api/orders
```
请求示例:
```json
{
  "customerId": 1,
  "shippingAddressId": 1,
  "productIds": [1, 2],
  "quantities": [2, 1]
}
```

### 支付订单
```
POST /api/orders/{orderNo}/payment
```
请求示例:
```json
{
  "paymentId": 100
}
```

### 查询订单
```
GET /api/orders/{orderNo}
```

### 取消订单
```
POST /api/orders/{orderNo}/cancellation
```
请求示例:
```json
{
  "reason": "客户取消订单"
}
```

## DDD 关键概念实现说明

### 值对象 (Value Object)
值对象是无标识、按属性值比较相等性的不可变对象:

```java
// Money值对象 - 不可变
public class Money {
    private final BigDecimal amount;
    
    // 操作返回新实例，保持不可变性
    public Money add(Money other) {
        return new Money(this.amount.add(other.amount));
    }
}
```

### 实体 (Entity)
实体具有唯一标识，生命周期贯穿整个系统:

```java
public class OrderItem extends Entity<OrderItemId> {
    // 实体具有ID
    private OrderItemId id;
    private Long productId;
    private int quantity;
    
    // 实体包含行为
    public void updateQuantity(int newQuantity) {
        this.quantity = newQuantity;
        this.subtotal = this.price.multiply(newQuantity);
    }
}
```

### 聚合 (Aggregate)
聚合是业务和一致性的边界，通过聚合根访问:

```java
public class Order extends AggregateRoot<OrderId> {
    // 聚合根管理内部实体
    private List<OrderItem> orderItems;
    
    // 聚合根保证一致性
    public void addOrderItem(OrderItem item) {
        orderItems.add(item);
        recalculateTotalAmount();
    }
}
```

### 领域事件 (Domain Event)
领域事件表示领域中发生的、领域专家关心的事情:

```java
public class OrderCreatedEvent extends DomainEvent {
    private final Order order;
    
    @Override
    public String getAggregateType() {
        return "Order";
    }
    
    @Override
    public String getAggregateId() {
        return order.getId().getValue().toString();
    }
}
```

### 防腐层 (Anti-corruption Layer)
防腐层隔离不同上下文，保持模型纯净:

```java
// 通过Assembler实现防腐层
public class OrderAssembler {
    // 将持久化对象转换为领域对象
    public Order toOrder(OrderPO po, List<OrderItemPO> itemPOs) {
        // 转换逻辑
    }
    
    // 将领域对象转换为持久化对象
    public OrderPO toOrderPO(Order order) {
        // 转换逻辑
    }
}
```

## 项目特色

1. **完整的DDD实现**: 涵盖DDD所有核心概念
2. **清晰的分层架构**: 严格遵循DDD分层原则
3. **领域事件机制**: 实现完整的事件发布-订阅
4. **丰富的业务规则**: 在领域模型中封装业务规则
5. **完善的异常处理**: 全局异常处理机制
6. **详细的代码注释**: 每个类和方法都有清晰说明

## 扩展方向

1. **引入CQRS模式**: 分离命令和查询职责
2. **实现事件溯源**: 基于事件重建状态
3. **微服务拆分**: 将系统拆分为多个有界上下文
4. **集成消息队列**: 使用RabbitMQ或Kafka处理领域事件
5. **添加API网关**: 使用Spring Cloud Gateway

## 参考资料

- 《实现领域驱动设计》- Vaughn Vernon
- 《领域驱动设计》- Eric Evans
- 《实现领域驱动设计》- https://www.jdon.com/ddd.html

## 贡献

欢迎贡献代码或提出建议。请先fork项目，创建feature分支，然后提交PR。

## 许可证

MIT License