# ddd-lite-docs **Repository Path**: lgy081300/ddd-lite-docs ## Basic Information - **Project Name**: ddd-lite-docs - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-05-26 - **Last Updated**: 2025-05-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Hyperf 领域驱动设计(DDD)框架 本项目是基于 Hyperf 框架的领域驱动设计(DDD)实现，提供了一套完整的 DDD 架构、工具和最佳实践指南。 ## 1. 项目概述 本框架旨在帮助开发者使用 DDD 方法论构建复杂的企业应用程序，特别适合以下场景： - 业务逻辑复杂的企业应用 - 需要长期维护和演进的系统 - 团队协作开发的大型项目 - 对代码质量和可维护性有较高要求的项目 通过采用领域驱动设计，本框架帮助开发者将业务复杂性转化为清晰的领域模型，实现业务逻辑与技术实现的分离，提高代码的可维护性和可扩展性。 ## 2. 文档索引 ### 2.1 架构与设计 1. [架构概述](docs/ddd/architecture_overview.md) - 提供框架整体架构的高层次视图，包括分层架构、依赖规则和通信模式 2. [目录结构](docs/ddd/directory_structure.md) - 详细说明项目的目录组织和文件布局，帮助开发者快速定位和理解代码 3. [分层架构以及职责边界](docs/ddd/layer_architecture.md) - 解释各层的职责和它们之间的交互，确保关注点分离 4. [核心概念与澄清](docs/ddd/core_concepts.md) - 阐述DDD中的核心概念及其在框架中的实现，澄清常见误解 ### 2.2 流程与机制 5. [请求链路分析](docs/ddd/call_flow.md) - 分析请求从接收到响应的完整流程，帮助理解系统的工作原理 6. [事件链路分析](docs/ddd/event_flow.md) - 详细说明事件的发布、传播和处理流程，展示事件驱动架构的实现 7. [事务管理](docs/ddd/transaction_management.md) - 介绍事务管理机制、职责边界和最佳实践，确保数据一致性 ### 2.3 组件与实现 8. [核心组件分析](docs/ddd/component_analysis.md) - 深入分析框架中的核心组件及其设计意图，包括： - [接口层组件分析](docs/ddd/component_analysis_interfaces.md) - 控制器、中间件、请求验证器等 - [应用层组件分析](docs/ddd/component_analysis_application.md) - 应用服务、DTO、事件监听器等 - [领域层组件分析](docs/ddd/component_analysis_domain.md) - 实体、值对象、聚合根、领域服务等 - [基础设施层组件分析](docs/ddd/component_analysis_infrastructure.md) - 仓储实现、事件分发器等 - [共享内核组件分析](docs/ddd/component_analysis_shared_kernel.md) - 通用工具、异常处理等 ### 2.4 开发指南 9. [单元测试指南](docs/ddd/testing_guide.md) - 提供编写和运行单元测试的详细指南，确保代码质量 10. [代码生成工具使用指南](docs/ddd/code_generation.md) - 说明如何使用代码生成工具提高开发效率 11. [新增模块开发指南](docs/ddd/module_development_guide.md) - 为开发人员提供快速创建和开发新业务模块的简明指南 ### 2.5 实践与应用 12. [示例应用说明](docs/ddd/example_application.md) - 介绍示例应用的功能和实现细节，展示DDD在实际项目中的应用 13. [最佳实践与实际应用建议](docs/ddd/best_practices.md) - 提供DDD实践中的最佳实践和建议，帮助避免常见陷阱 14. [DDD实践指南（针对新团队）](docs/ddd/ddd_guide_for_new_teams.md) - 为新接触DDD的团队提供实践指南和学习路径 15. [常见问题与解答 (FAQ)](docs/ddd/faq.md) - 解答DDD实践中的常见问题和疑惑 ## 3. 架构概述 项目遵循标准的 DDD 分层架构： 1. **领域层(Domain)**: 包含业务核心概念，如实体、值对象、聚合根、领域事件和领域服务 2. **应用层(Application)**: 协调领域对象完成用户用例，包含应用服务、命令/查询处理器和 DTO 3. **基础设施层(Infrastructure)**: 提供技术实现，如持久化、消息传递和外部服务集成 4. **接口层(Interfaces)**: 处理与外部系统的交互，如 API 控制器、命令行界面等 5. **共享内核(Shared)**: 在多个有界上下文之间共享的组件和工具 详细架构说明请参考 [架构概述文档](docs/ddd/architecture_overview.md)。 ## 4. 核心概念与组件 ### 4.1 数据传输对象(DTO) 数据传输对象(Data Transfer Object, DTO)是在不同层之间传输数据的简单对象，用于将领域对象转换为适合外部消费的格式。 ```php // 示例: 使用DTO返回账户信息 $accountDTO = AccountDTO::fromEntity($account); return $this->success($accountDTO->toArray()); ``` DTO在应用层和接口层之间起着重要的桥梁作用，避免了领域对象直接暴露给外部，保护了领域模型的完整性。 更多关于DTO的详细说明，包括其作用、实现、使用流程和最佳实践，请参考[核心概念与澄清文档](docs/ddd/core_concepts.md#22-数据传输对象-dto)。 ### 4.2 值对象(Value Objects) 值对象是通过其属性值而非身份标识定义的不可变对象。 ```php // 示例: Money值对象 $money = Money::fromFloat(100.00); $newMoney = $money->add(Money::fromFloat(50.00)); // 返回新实例，值为150.00 ``` ### 4.3 实体(Entities) 实体是具有唯一标识和生命周期的对象。 ```php // 示例: 获取账户实体 $account = $accountRepository->findById(Identity::fromString($id)); ``` ### 4.4 聚合根(Aggregate Roots) 聚合根是实体的特殊类型，负责维护聚合内部一致性并管理领域事件。 ```php // 示例: 创建账户聚合根 $account = Account::create( Identity::generate(), 'username', Email::create('user@example.com'), AccountType::personal() ); ``` ### 4.5 领域事件(Domain Events) 领域事件表示领域中发生的重要事件，用于解耦和通知。 ```php // 示例: 账户实体中记录领域事件 $this->recordEvent(new AccountCreatedEvent($this->id, $this->username, $this->email)); // 示例: 分发领域事件 $this->eventDispatcher->dispatchAll($account->popEvents()); ``` ### 4.6 领域服务(Domain Services) 领域服务处理不属于单个实体的业务逻辑，协调多个聚合根之间的操作。 ```php // 示例: 使用领域服务转账 $transferService->transfer($sourceAccount, $targetAccount, Money::fromFloat(100.00)); ``` ### 4.7 仓储(Repositories) 仓储负责持久化和检索聚合根，隐藏持久化细节。 ```php // 示例: 保存账户 $accountRepository->save($account); // 示例: 查找账户 $account = $accountRepository->findByEmail(Email::create('user@example.com')); ``` 更多核心概念详情请参考 [核心概念与澄清文档](docs/ddd/core_concepts.md)。 ## 5. 目录结构 项目采用清晰的目录结构，反映 DDD 分层架构： ``` app/ ├── Application/ # 应用层 │ ├── DTO/ # 数据传输对象 │ │ └── {Module}/ # 按模块组织的DTO │ │ ├── {Module}DTO.php # 模块主DTO │ │ └── {Detail}DTO.php # 详细信息DTO │ ├── Event/ # 应用事件 │ │ ├── {Module}/ # 按模块组织的应用事件 │ │ │ └── {Event}.php # 应用事件类 │ │ └── Listener/ # 应用事件监听器 │ │ └── {Module}/ # 按模块组织的事件监听器 │ │ └── {Event}Listener.php # 事件监听器类 │ ├── Service/ # 应用服务 │ │ ├── AbstractApplicationService.php # 应用服务抽象基类 │ │ └── {Module}/ # 按模块组织的应用服务 │ │ ├── {Module}ServiceInterface.php # 应用服务接口 │ │ └── Impl/ # 应用服务实现 │ │ └── {Module}Service.php # 应用服务实现类 ├── Domain/ # 领域层 │ └── {Module}/ # 领域模块（聚合） │ ├── Entity/ # 实体 │ │ └── {Entity}.php # 实体类（如Product.php） │ ├── Event/ # 领域事件 │ │ └── {Event}.php # 领域事件类（如ProductCreatedEvent.php） │ ├── Repository/ # 仓储接口 │ │ └── {Entity}RepositoryInterface.php # 仓储接口 │ ├── Service/ # 领域服务 │ │ ├── {Module}DomainServiceInterface.php # 领域服务接口 │ │ └── Impl/ # 领域服务实现 │ │ └── {Module}DomainService.php # 领域服务实现类 │ └── ValueObject/ # 值对象 │ └── {ValueObject}.php # 值对象类（如ProductDetail.php） ├── Infrastructure/ # 基础设施层 │ ├── Adapter/ # 外部服务适配器 │ │ └── {Service}/ # 按服务类型组织的适配器 │ │ └── {Adapter}.php # 适配器实现类 │ ├── Event/ # 事件基础设施 │ │ ├── DomainEventDispatcherImpl.php # 领域事件分发器实现 │ │ ├── DomainEventJob.php # 领域事件异步任务 │ │ └── DomainEventStore.php # 领域事件存储 │ ├── Model/ # 数据模型（ORM实体） │ │ └── {Module}/ # 按模块组织的数据模型 │ │ └── {Entity}.php # 数据模型类（如Product.php） │ └── Repository/ # 仓储实现 │ ├── AbstractRepository.php # 仓储抽象基类 │ └── {Module}/ # 按模块组织的仓储实现 │ └── {Entity}Repository.php # 仓储实现类 ├── Interfaces/ # 接口层 │ ├── Console/ # 命令行接口 │ │ ├── AbstractCommand.php # 命令抽象基类 │ │ └── Command/ # 命令实现 │ │ └── {Command}.php # 命令实现类（如InitProjectCommand.php） │ ├── Event/ # 接口层事件 │ │ ├── Listener/ # 事件监听器 │ │ │ └── {Module}/ # 按模块组织的事件监听器 │ │ │ └── {Event}Listener.php # 事件监听器类 │ │ └── Subscriber/ # 事件订阅者 │ │ └── {Module}EventSubscriber.php # 事件订阅者类 │ └── Http/ # HTTP接口 │ ├── Controller/ # 控制器 │ │ ├── AbstractController.php # 控制器抽象基类 │ │ ├── IndexController.php # 首页控制器 │ │ └── v1/ # API版本（小写v） │ │ └── {Module}/ # 按模块组织的控制器 │ │ └── {Module}Controller.php # 控制器实现类 │ ├── Middleware/ # 中间件 │ │ ├── AuthMiddleware.php # 认证中间件 │ │ └── CorsMiddleware.php # 跨域中间件 │ └── Request/ # 请求验证 │ ├── AbstractRequest.php # 请求抽象基类 │ └── {Module}/ # 按模块组织的请求验证 │ ├── Create{Entity}Request.php # 创建请求 │ ├── Update{Entity}Request.php # 更新请求 │ └── {Action}Request.php # 其他操作请求 └── Shared/ # 共享层 ├── Constants/ # 常量和枚举 │ ├── AbstractEnum.php # 枚举抽象基类 │ ├── ErrorCode.php # 错误码常量 │ └── ResultCode.php # 结果码常量 ├── Context/ # 上下文对象 │ ├── AppContext.php # 应用上下文 │ ├── UserCollection.php # 用户集合 │ └── UserContext.php # 用户上下文 ├── Exception/ # 异常类 │ ├── BusinessException.php # 业务异常 │ └── Handler/ # 异常处理器 │ ├── AbstractHandler.php # 处理器抽象基类 │ ├── AppExceptionHandler.php # 应用异常处理器 │ ├── BusinessExceptionHandler.php # 业务异常处理器 │ └── {Exception}Handler.php # 其他异常处理器 ├── Kernel/ # 核心组件 │ ├── AggregateRoot/ # 聚合根 │ │ └── AbstractAggregateRoot.php # 聚合根抽象基类 │ ├── DTO/ # DTO基类 │ │ ├── AbstractDTO.php # DTO抽象基类 │ │ └── Traits/ # DTO特性 │ │ ├── DTOMapperTrait.php # DTO映射特性 │ │ ├── DTONamingConverterTrait.php # DTO命名转换特性 │ │ ├── DTOSerializerTrait.php # DTO序列化特性 │ │ └── DTOTypeConverterTrait.php # DTO类型转换特性 │ ├── Entity/ # 实体基类 │ │ └── AbstractEntity.php # 实体抽象基类 │ ├── Event/ # 事件基类 │ │ ├── AbstractEvent.php # 事件抽象基类 │ │ ├── DomainEvent.php # 领域事件基类 │ │ └── DomainEventDispatcher.php # 领域事件分发器接口 │ ├── Repository/ # 仓储基类 │ │ └── RepositoryInterface.php # 仓储接口 │ ├── Service/ # 服务基类 │ │ ├── AbstractDomainService.php # 领域服务抽象基类 │ │ └── DomainServiceInterface.php # 领域服务接口 │ └── ValueObject/ # 值对象基类 │ ├── AbstractValueObject.php # 值对象抽象基类 │ └── Identity.php # 标识值对象 ├── Listener/ # 共享监听器 │ ├── DbQueryExecutedListener.php # 数据库查询监听器 │ ├── DeleteCacheListener.php # 缓存删除监听器 │ └── QueueHandleListener.php # 队列处理监听器 ├── Traits/ # 共享特性 │ ├── LoggableTrait.php # 日志特性 │ └── TransactionTrait.php # 事务管理特性 └── Util/ # 工具类 ├── ArrayUtil.php # 数组工具 ├── Env.php # 环境变量工具 ├── HttpClient.php # HTTP客户端工具 ├── Logger.php # 日志工具 ├── Paginator.php # 分页工具 ├── RedLock.php # 分布式锁工具 ├── Result.php # 结果包装工具 └── UUID.php # UUID生成工具 ``` 完整目录结构请参考 [目录结构文档](docs/ddd/directory_structure.md)。 ## 6. 分层架构与职责边界 DDD架构中的每一层都有明确的职责和边界： 1. **领域层**：封装业务规则和核心逻辑，不依赖其他层 2. **应用层**：协调领域对象完成用例，管理事务和安全 3. **基础设施层**：提供技术实现，如数据库访问、消息队列等 4. **接口层**：处理外部请求，转换为应用层可以处理的格式 详细的分层架构说明请参考 [分层架构以及职责边界文档](docs/ddd/layer_architecture.md)。 ## 7. 请求链路分析 ### 7.1 HTTP 请求处理流程 HTTP请求从接口层的控制器开始，经过应用层的服务，到领域层的实体和值对象，最后通过基础设施层的仓储持久化数据。 ```mermaid sequenceDiagram participant Client as 前端请求 participant Controller as 控制器 participant AppService as 应用服务 participant DomainService as 领域服务 participant Entity as 实体/聚合根 participant Repository as 仓储 participant DB as 数据模型 Client->>Controller: HTTP请求 Controller->>Controller: 验证请求参数 Controller->>AppService: 调用应用服务 AppService->>DB: 开始事务 AppService->>Repository: 获取聚合根 Repository->>DB: 查询数据 DB-->>Repository: 返回数据 Repository-->>AppService: 返回聚合根 AppService->>DomainService: 调用领域服务 DomainService->>Entity: 调用实体方法 Entity->>Entity: 执行业务逻辑 Entity->>Entity: 记录领域事件 Entity-->>DomainService: 返回结果 DomainService-->>AppService: 返回结果 AppService->>Repository: 保存聚合根 Repository->>DB: 持久化数据 Repository->>EventDispatcher: 分发领域事件 DB-->>Repository: 确认保存 Repository-->>AppService: 确认保存 AppService->>DB: 提交事务 DB-->>AppService: 确认提交 AppService-->>Controller: 返回结果 Controller-->>Client: HTTP响应 ``` 更多调用链路分析请参考 [请求链路分析文档](docs/ddd/call_flow.md)。 ## 8. 事件链路分析 领域事件是DDD中的重要概念，用于在聚合之间进行通信和解耦。 ### 8.1 事件处理流程 Hyperf DDD框架中的事件处理流程遵循以下路径： ``` 聚合根记录事件 → 仓储保存聚合根 → 事件分发器分发事件 → 事件存储持久化事件 → 事件监听器处理事件 ``` 下面是一个完整的事件处理流程图： ```mermaid sequenceDiagram participant Entity as 聚合根 participant Repository as 仓储 participant EventDispatcher as 事件分发器 participant EventStore as 事件存储 participant EventListener as 事件监听器 participant OtherAggregate as 其他聚合根 Entity->>Entity: 执行业务逻辑 Entity->>Entity: 记录领域事件 Repository->>Repository: 保存聚合根 Repository->>EventDispatcher: 分发领域事件 EventDispatcher->>EventStore: 存储事件 EventStore-->>EventDispatcher: 确认存储 EventDispatcher->>EventListener: 通知监听器 EventListener->>OtherAggregate: 更新其他聚合根 OtherAggregate-->>EventListener: 确认更新 EventListener-->>EventDispatcher: 确认处理 EventDispatcher-->>Repository: 确认分发 ``` ### 8.2 领域事件示例 ```php // 在聚合根中记录领域事件 public function addPrice( int $id, string $priceType, float $amount, string $currency = 'CNY' ): void { // 创建价格值对象 $price = new ProductPrice($id, $priceType, $amount, $currency); // 添加到价格列表 $this->prices[] = $price; // 记录领域事件 $this->recordEvent(new ProductPriceChangedEvent($this->id, $price)); } ``` ### 8.3 事件类型与分类 在Hyperf DDD框架中，事件可以分为以下几种类型： 1. **领域事件**：表示领域中发生的重要事件，如账户创建、产品价格变更等 2. **应用事件**：表示应用层面的事件，如用户登录、请求处理完成等 3. **集成事件**：表示跨系统边界的事件，用于不同系统之间的通信和集成 详细的事件链路分析请参考 [事件链路分析文档](docs/ddd/event_flow.md)。 ## 9. 核心组件分析 本框架包含多个核心组件，每个组件都有特定的职责和设计意图： - **控制器(Controller)**: 处理HTTP请求，调用应用服务 - **应用服务(Application Service)**: 协调领域对象完成用户用例 - **领域事件分发器(Domain Event Dispatcher)**: 负责分发领域事件 - **事件存储(Event Store)**: 存储领域事件 - **领域服务(Domain Service)**: 处理跨实体的业务逻辑 - **实体与聚合根(Entity & Aggregate Root)**: 封装业务规则和行为 - **仓储(Repository)**: 持久化和检索聚合根 - **领域事件(Domain Event)**: 表示领域中发生的重要事件 - **值对象(Value Object)**: 表示没有身份的概念 详细组件分析请参考 [核心组件分析文档](docs/ddd/component_analysis.md)。 ## 10. 单元测试指南 DDD架构的测试策略应该反映系统的分层结构，每一层都有其特定的测试方法和关注点。 ### 10.1 测试金字塔 ``` /\ / \ / \ / E2E \ /--------\ / 集成测试 \ /----------\ / 单元测试 \ /------------\ ``` - **单元测试**：测试最小的可测试单元，通常是一个类或方法 - **集成测试**：测试多个组件之间的交互 - **端到端测试**：测试整个系统的功能 详细的测试指南请参考 [单元测试指南文档](docs/ddd/testing_guide.md)。 ## 11. 代码生成工具 本框架提供了一系列命令行工具，用于自动生成符合DDD架构的代码模板，包括领域模型、应用服务、仓储实现等。 ### 11.1 可用的代码生成命令 ```bash # 初始化项目 php bin/hyperf.php init:project # 初始化模块 php bin/hyperf.php init:module {module_name} # 生成领域模型 php bin/hyperf.php gen:domain {name} # 生成应用服务 php bin/hyperf.php gen:app {name} # 生成测试 php bin/hyperf.php generate:test {name} ``` 详细的代码生成工具使用指南请参考 [代码生成工具使用指南文档](docs/ddd/code_generation.md)。 ## 12. 示例应用 本框架包含一个示例应用，展示了如何在实际项目中应用DDD架构。示例应用是一个简单的账户管理系统，实现了账户的创建、查询、存款、取款和转账等基本功能。 ### 12.1 功能列表 1. 创建账户 2. 查询账户信息 3. 账户存款 4. 账户取款 5. 账户间转账 6. 查询账户交易历史 详细的示例应用说明请参考 [示例应用说明文档](docs/ddd/example_application.md)。 ## 13. 最佳实践与实际应用建议 ### 13.1 分层架构与职责分离 - 保持层次边界清晰 - 管理依赖方向（外层依赖内层） - 确保领域层的独立性 ### 13.2 领域模型设计 - 保持领域模型的纯净 - 合理使用值对象 - 设计适当大小的聚合 - 正确区分实体和值对象 - 合理使用领域服务 ### 13.3 事件驱动设计 - 使用领域事件表达业务变更 - 通过事件实现聚合间的解耦 - 利用事件监听器响应业务变化 ### 13.4 事件驱动架构 - 使用领域事件进行解耦 - 考虑事件溯源 - 利用异步处理提高系统响应性 更多最佳实践请参考 [最佳实践与实际应用建议文档](docs/ddd/best_practices.md)。 ## 14. DDD实践指南（针对新团队） ### 14.1 DDD学习路径 1. 基础概念阶段（1-2周） 2. 战略设计阶段（2-3周） 3. 战术设计阶段（3-4周） 4. 架构整合阶段（2-3周） 5. 高级主题阶段（4-6周） ### 14.2 常见误区与陷阱 1. 过度设计 2. 贫血模型 3. 忽视通用语言 4. 聚合边界模糊 5. 忽视领域事件 6. 技术驱动而非领域驱动 ### 14.3 渐进式采用策略 1. 从有界上下文开始 2. 从通用语言开始 3. 从值对象开始 4. 逐步引入聚合 5. 引入领域事件 6. 重构现有代码 更多实践指南请参考 [DDD实践指南文档](docs/ddd/ddd_guide_for_new_teams.md)。 ## 15. 常见问题与解答 (FAQ) 在DDD实践过程中，开发团队常常会遇到各种问题和挑战。本节列出了一些最常见的问题及其解答： ### 15.1 架构相关问题 - **为什么事务要在应用层中使用？** 事务是应用层的职责，因为它涉及到用例的原子性，而不是领域逻辑的一部分。 - **领域事件为什么在应用层监听而不是接口层？** 领域事件表示领域状态的变化，应该由了解领域的应用层来处理，而不是接口层。 - **如何处理跨聚合的业务规则？** 可以使用领域服务协调多个聚合，或者使用领域事件实现聚合间的解耦通信。 ### 15.2 设计相关问题 - **如何确定聚合的边界？** 聚合边界应该基于业务不变性规则和事务一致性需求来确定。 - **值对象和实体之间如何选择？** 如果对象主要由其属性值定义，且不需要跟踪其生命周期，则应使用值对象；否则使用实体。 - **如何处理大型聚合的性能问题？** 可以考虑拆分聚合、使用懒加载、实现CQRS模式等策略。 更多常见问题解答请参考 [常见问题与解答文档](docs/ddd/faq.md)。