# DDDExample **Repository Path**: chenyx119/dddexample ## Basic Information - **Project Name**: DDDExample - **Description**: 这是一个基于领域驱动设计（Domain-Driven Design，DDD）的示例项目，实现了一个简单的订单管理系统。本项目旨在帮助开发者理解如何在实践中应用DDD的核心概念和最佳实践。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-07-09 - **Last Updated**: 2025-07-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DDD示例项目这是一个基于领域驱动设计（Domain-Driven Design，DDD）的示例项目，实现了一个简单的订单管理系统。本项目旨在帮助开发者理解如何在实践中应用DDD的核心概念和最佳实践。 ## 项目架构本项目采用六边形架构（也称为端口和适配器架构），并实现了CQRS（命令查询职责分离）模式，分为以下几个主要模块： ### 1. 领域层（Domain Layer）位于 `ddd-example-domain` 模块，是DDD架构的核心，包含所有业务逻辑和规则： - **实体（Entity）**：具有唯一标识的业务对象，如 `Order`（订单）、`OrderItem`（订单项） - **值对象（Value Object）**：不可变的业务概念，如 `Money`（金额）、`OrderStatus`（订单状态） - **聚合根（Aggregate Root）**：聚合的入口点，确保业务一致性，如 `Order` 聚合根 - **领域服务（Domain Service）**：处理跨聚合的业务逻辑，如 `OrderDomainService` - **仓储接口（Repository Interface）**：定义持久化契约，如 `OrderRepository` - **领域事件（Domain Event）**：记录重要的业务发生，如 `OrderCreatedEvent` **职责**：封装核心业务逻辑，不依赖任何外部技术，保持领域模型的纯粹性。 ### 2. 应用层（Application Layer）位于 `ddd-example-application` 模块，负责业务流程的编排和用例实现： - **应用服务（Application Service）**：编排领域对象完成业务用例，如 `OrderApplicationService` - **命令对象（Command）**：封装应用服务的输入参数，如 `CreateOrderCommand`、`PayOrderCommand` - **DTO对象（Data Transfer Object）**：在层间传递数据，隔离领域对象，如 `OrderDTO`、`OrderItemDTO` - **装配器（Assembler）**：处理DTO与领域对象之间的转换，如 `OrderAssembler` - **事件处理器（Event Handler）**：处理领域事件，实现跨聚合的业务逻辑 - **命令服务（Command Service）**：专门处理写操作，如创建、修改、删除订单 - **查询服务（Query Service）**：专门处理读操作，如查询订单、统计信息等 **职责**：协调领域对象完成业务用例，处理事务边界，不包含业务规则。 ### 3. 基础设施层（Infrastructure Layer）位于 `ddd-example-infrastructure` 模块，提供技术实现和外部系统集成： - **仓储实现（Repository Implementation）**：实现领域层定义的仓储接口，如 `OrderRepositoryImpl` - **数据对象（DO）**：对应数据库表结构的持久化对象，如 `OrderDO`、`OrderItemDO` - **对象转换器（Converter）**：处理DO与领域对象之间的转换，如 `OrderConverter` - **外部服务适配器**：集成第三方系统，如支付网关、消息队列等 - **配置管理**：数据库连接、缓存配置等技术配置 - **技术工具类**：日志、监控、安全等基础设施组件 **职责**：提供技术实现，隐藏技术细节，支持领域层和应用层的需求。 ### 4. 接口层（Interfaces Layer）位于 `ddd-example-interfaces` 模块，提供对外API接口和用户界面： - **Facade**：封装复杂的业务接口，提供简化的API，如 `OrderFacade` - **请求/响应对象**：定义API的输入输出格式，如 `CreateOrderRequest`、`OrderResponse` - **统一响应对象**：标准化API响应格式，如 `Result` - **参数验证**：API输入参数的校验和转换 - **API文档配置**：Swagger配置，自动生成API文档 - **异常处理**：统一的异常处理和错误响应 **职责**：对外提供标准化的API接口，处理用户交互，不包含业务逻辑。 ### 5. 启动模块（Starter）位于 `ddd-example-starter` 模块，负责应用程序的组装、配置和启动： - **启动类**：Spring Boot应用程序入口，如 `DddExampleApplication` - **全局异常处理**：统一处理未捕获的异常，如 `GlobalExceptionHandler` - **配置文件**：各环境的配置文件，如 `application.yml`、`application-dev.yml` - **依赖注入配置**：Bean的装配和依赖关系配置 - **中间件配置**：数据库、缓存、消息队列等中间件配置 - **监控和日志配置**：应用监控、日志记录等配置 **职责**：组装各个模块，配置运行环境，启动应用程序。 ## 项目目录结构 ``` DDDExample/ ├── README.md # 项目说明文档 ├── pom.xml # 父级Maven配置 ├── mvnw # Maven Wrapper脚本 ├── mvnw.cmd # Maven Wrapper脚本(Windows) ├── .gitignore # Git忽略文件配置 ├── .gitattributes # Git属性配置 ├── HELP.md # 帮助文档 ├── sql/ # 数据库脚本目录 │ └── example.sql # 示例数据库初始化脚本 │ ├── ddd-example-domain/ # 领域层模块 │ ├── pom.xml # 领域层Maven配置 │ └── src/main/java/cyx/example/ddd/domain/ │ ├── shared/ # 共享领域组件 │ │ ├── DomainEvent.java # 领域事件接口 │ │ ├── AggregateRoot.java # 聚合根基类 │ │ └── Entity.java # 实体基类 │ │ │ ├── order/ # 订单限界上下文 │ │ ├── event/ # 领域事件定义 │ │ │ ├── OrderCreatedEvent.java │ │ │ ├── OrderPaidEvent.java │ │ │ └── OrderCancelledEvent.java │ │ │ │ │ ├── model/ # 领域模型 │ │ │ ├── aggregate/ # 聚合根 │ │ │ │ └── Order.java # 订单聚合根 │ │ │ ├── entity/ # 实体 │ │ │ │ └── OrderItem.java # 订单项实体 │ │ │ └── valueobject/ # 值对象 │ │ │ ├── Money.java # 金额值对象 │ │ │ └── OrderStatus.java # 订单状态值对象 │ │ │ │ │ ├── repository/ # 仓储接口 │ │ │ └── OrderRepository.java │ │ │ │ │ └── service/ # 领域服务 │ │ └── OrderDomainService.java │ │ │ └── product/ # 商品限界上下文 │ └── ... # 商品相关领域模型 │ ├── ddd-example-application/ # 应用层模块 │ ├── pom.xml # 应用层Maven配置 │ └── src/main/java/cyx/example/ddd/application/ │ ├── config/ # 应用层配置 │ │ └── AsyncConfig.java # 异步处理配置 │ │ │ └── order/ # 订单应用服务 │ ├── command/ # 命令服务 │ │ ├── CreateOrderCommand.java │ │ ├── PayOrderCommand.java │ │ ├── CancelOrderCommand.java │ │ ├── OrderCommandService.java # 订单命令服务接口 │ │ └── OrderCommandServiceImpl.java # 订单命令服务实现 │ │ │ ├── dto/ # 数据传输对象 │ │ ├── OrderDTO.java │ │ └── OrderItemDTO.java │ │ │ ├── assembler/ # 对象转换器 │ │ └── OrderAssembler.java │ │ │ ├── service/ # 应用服务（历史遗留，已拆分为命令/查询服务） │ │ └── OrderApplicationService.java │ │ │ ├── query/ # 查询服务 │ │ ├── OrderQueryService.java # 订单查询服务接口 │ │ ├── OrderQueryServiceImpl.java # 订单查询服务实现 │ │ ├── OrderQuery.java # 查询条件对象 │ │ ├── OrderPageQuery.java # 分页查询对象 │ │ ├── OrderPageResult.java # 分页结果对象 │ │ └── OrderQueryRepository.java # 查询仓储接口 │ │ │ └── event/ # 事件处理 │ ├── OrderEventHandler.java # 事件处理器 │ ├── OrderEventPublisher.java # 事件发布器 │ └── MessageQueueEventPublisher.java # 消息队列发布器 │ ├── ddd-example-infrastructure/ # 基础设施层模块 │ ├── pom.xml # 基础设施层Maven配置 │ └── src/main/java/cyx/example/ddd/infrastructure/ │ └── order/ # 订单基础设施实现 │ ├── entity/ # 数据实体(DO) │ │ ├── OrderDO.java # 订单数据对象 │ │ └── OrderItemDO.java # 订单项数据对象 │ │ │ ├── converter/ # 对象转换器 │ │ └── OrderConverter.java │ │ │ └── repository/ # 仓储实现 │ └── OrderRepositoryImpl.java │ ├── ddd-example-interfaces/ # 接口层模块 │ ├── pom.xml # 接口层Maven配置 │ └── src/main/java/cyx/example/ddd/interfaces/ │ ├── common/ # 公共组件 │ │ ├── Result.java # 统一响应对象 │ │ └── GlobalExceptionHandler.java # 全局异常处理 │ │ │ └── order/ # 订单接口 │ ├── facade/ # 外观模式 │ │ └── OrderFacade.java # 订单外观类 │ │ │ └── dto/ # 接口层DTO │ ├── CreateOrderRequest.java │ ├── PayOrderRequest.java │ └── CancelOrderRequest.java │ └── ddd-example-starter/ # 启动模块 ├── pom.xml # 启动模块Maven配置 └── src/main/java/cyx/example/ddd/ ├── DddExampleApplication.java # Spring Boot启动类 └── exception/ # 异常处理 └── BusinessException.java # 业务异常类 ``` ### 目录结构设计原则 #### 1. **按DDD分层架构组织** - 每个模块对应DDD的一个层 - 清晰的依赖关系：接口层 → 应用层 → 领域层 ← 基础设施层 - 避免跨层依赖，保持架构的清晰性 #### 2. **按限界上下文组织** - 每个限界上下文在领域层有独立的包结构 - 相关的领域模型、事件、服务组织在一起 - 便于理解和维护业务边界 #### 3. **按DDD概念组织** - **aggregate/**: 聚合根，确保业务不变性 - **entity/**: 实体，具有唯一标识的对象 - **valueobject/**: 值对象，不可变的对象 - **event/**: 领域事件，记录重要的业务发生 - **service/**: 领域服务，处理跨聚合的业务逻辑 - **repository/**: 仓储接口，定义持久化契约 #### 4. **按功能职责组织** - **command/**: 命令对象，封装输入参数 - **dto/**: 数据传输对象，用于层间数据传递 - **assembler/**: 对象转换器，处理对象转换 - **facade/**: 外观模式，简化接口调用 - **converter/**: 数据转换器，处理DO与领域对象转换 #### 5. **配置和资源分离** - **config/**: 配置类，如异步处理、数据库配置等 - **sql/**: 数据库脚本，与代码分离 - **resources/**: 配置文件，如application.yml等 #### 6. **测试代码组织** - 每个模块都有对应的测试目录 - 测试代码结构与主代码结构保持一致 - 便于查找和维护测试用例 ### 模块依赖关系 ``` ddd-example-starter ├── ddd-example-interfaces │ ├── ddd-example-application │ │ ├── ddd-example-domain │ │ └── ddd-example-infrastructure │ │ └── ddd-example-domain │ └── ddd-example-application └── ddd-example-infrastructure └── ddd-example-domain ``` - **启动模块**：依赖所有其他模块，负责组装和启动 - **接口层**：依赖应用层，提供API接口 - **应用层**：依赖领域层，编排业务逻辑 - **基础设施层**：依赖领域层，提供技术实现 - **领域层**：不依赖其他层，保持纯粹性 ## 核心领域模型 ### 订单聚合（Order Aggregate） - **聚合根**：`Order` - **实体**：`OrderItem` - **值对象**：`Money`、`OrderStatus` 订单聚合实现了完整的订单生命周期管理： 1. 创建订单 2. 添加订单项 3. 支付订单 4. 确认订单 5. 配送订单 6. 完成订单 7. 取消订单 ### 领域事件（Domain Events） - **事件接口**：`DomainEvent` - **事件基类**：`AggregateRoot`（提供事件收集功能） - **具体事件**： - `OrderCreatedEvent`：订单创建事件 - `OrderPaidEvent`：订单支付事件 - `OrderCancelledEvent`：订单取消事件 - **事件处理**：`OrderEventHandler`（支持同步和异步处理） - **事件发布**：`OrderEventPublisher`（事务后发布） ## API接口 ### 订单管理接口 - POST `/api/orders`：创建订单 - GET `/api/orders/{orderId}`：查询订单 - GET `/api/orders/user/{userId}`：查询用户订单列表 - POST `/api/orders/{orderId}/pay`：支付订单 - POST `/api/orders/{orderId}/cancel`：取消订单 ## 快速开始 ### 环境要求 - JDK 11+ - Maven 3.6+ - MySQL 8.0+ ### 数据库配置 1. 创建数据库： ```sql CREATE DATABASE test DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` 2. 配置数据库连接：修改 `ddd-example-infrastructure/src/main/resources/application-infrastructure.yml`： ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/test?serverTimezone=Asia/Shanghai username: your_username password: your_password ``` ### 构建和运行 1. 构建项目： ```bash mvn clean install ``` 2. 运行项目： ```bash cd ddd-example-starter mvn spring-boot:run ``` 3. 访问接口文档： - http://localhost:8080/ddd-example/swagger-ui/ ## 项目总结本项目完整展示了基于DDD的订单管理系统实现，特别在领域事件方面提供了生产级别的解决方案： ### 🎯 核心特性 - **完整的DDD分层架构**：领域层、应用层、基础设施层、接口层清晰分离 - **事件驱动架构**：基于Spring Events的领域事件实现 - **事务一致性保证**：使用`@TransactionalEventListener`确保事件处理的事务安全 - **异步处理支持**：配置专门的线程池处理异步事件 - **微服务就绪**：提供消息队列集成示例，便于微服务架构迁移 ### 🏗️ 架构优势 - **高内聚低耦合**：通过事件实现模块间的松耦合 - **可扩展性强**：新功能可通过事件处理器无侵入添加 - **可测试性好**：各层职责清晰，便于单元测试 - **可维护性高**：业务逻辑集中在领域层，技术实现隔离在外层 - **可演进性强**：支持从单体到微服务的平滑迁移 ### 🚀 技术亮点 - **Spring Events + @TransactionalEventListener**：企业级事件处理方案 - **异步线程池配置**：高性能的事件异步处理 - **消息队列集成**：支持RabbitMQ、Kafka、Redis Stream - **完整的事件生命周期**：从事件定义、发布、处理到监控的全流程 - **生产级最佳实践**：包含错误处理、幂等性、监控告警等 ### 📚 学习价值本项目不仅是一个可运行的示例，更是一个学习DDD和事件驱动架构的完整教程，涵盖了： - DDD核心概念的实际应用 - 领域事件的设计和实现 - 企业级架构的最佳实践 - 微服务架构的演进路径通过本项目的学习和实践，开发者可以深入理解DDD的精髓，掌握事件驱动架构的实现技巧，为构建高质量的企业级应用打下坚实基础。