|
|
@@ -1,29 +1,589 @@
|
|
|
# Test 模块
|
|
|
|
|
|
-## 模块说明
|
|
|
-Test 模块是一个示例模块，用于展示模块化开发的最佳实践。
|
|
|
-
|
|
|
-## 目录结构
|
|
|
-```
|
|
|
-├── AdminControllers/ # 后台控制器
|
|
|
-├── Commands/ # 命令目录
|
|
|
-├── Config/ # 配置目录
|
|
|
-├── Database/ # 数据库目录
|
|
|
-│ └── create.sql # 创建数据表的SQL
|
|
|
-└── Enums/ # 枚举（枚举的名和Case全大写）
|
|
|
-├── Models/ # 模型目录
|
|
|
-├── Providers/ # Providers
|
|
|
-├── Events/ # 事件目录
|
|
|
-├── Logic/ # Logic目录/逻辑目录
|
|
|
-├── Listeners/ # 监听器目录
|
|
|
-├── Queues/ # 队列目录
|
|
|
-├── Repositorys/ # 仓库目录（后台控制器专用，其他场景不要用）
|
|
|
-├── Services/ # 服务目录（供其他模块使用）
|
|
|
-│ └── TestService.php # 服务之一
|
|
|
-├── Validations/ # Validation 目录（不是Laravel的Validation规则）
|
|
|
-├── Validators/ # Validator目录
|
|
|
-└── Tests/ # 测试目录
|
|
|
-```
|
|
|
-
|
|
|
-## 注意事项
|
|
|
+> 示例模块 - 展示模块化开发的最佳实践和标准架构
|
|
|
+
|
|
|
+## 目录
|
|
|
+
|
|
|
+1. [模块概述](#1-模块概述)
|
|
|
+2. [目录结构](#2-目录结构)
|
|
|
+3. [架构设计](#3-架构设计)
|
|
|
+4. [开发规范](#4-开发规范)
|
|
|
+5. [最佳实践](#5-最佳实践)
|
|
|
+6. [参考示例](#6-参考示例)
|
|
|
+
|
|
|
+## 1. 模块概述
|
|
|
+
|
|
|
+### 1.1 功能与目的
|
|
|
+
|
|
|
+Test模块是一个标准的示例模块，用于展示项目中模块化开发的最佳实践。它提供了完整的模块架构参考，包括数据层、业务逻辑层、服务层、控制器层等各个层次的标准实现方式。
|
|
|
+
|
|
|
+### 1.2 主要特点
|
|
|
+
|
|
|
+- **标准架构**：遵循项目统一的分层架构设计
|
|
|
+- **完整示例**：包含所有必要的目录和文件结构
|
|
|
+- **最佳实践**：展示代码组织、命名规范、设计模式等最佳实践
|
|
|
+- **参考模板**：为新模块开发提供标准模板
|
|
|
+
|
|
|
+## 2. 目录结构
|
|
|
+
|
|
|
+### 2.1 完整目录树
|
|
|
+
|
|
|
+```
|
|
|
+app/Module/Test/
|
|
|
+├── AdminControllers/ # 后台管理控制器
|
|
|
+│ ├── Helper/ # 控制器辅助类
|
|
|
+│ │ ├── TestGridHelper.php # 表格辅助类
|
|
|
+│ │ ├── TestFormHelper.php # 表单辅助类
|
|
|
+│ │ └── TestFilterHelper.php # 筛选辅助类
|
|
|
+│ ├── Actions/ # 控制器动作类
|
|
|
+│ │ └── TestExportAction.php # 导出动作
|
|
|
+│ └── TestController.php # 主控制器
|
|
|
+├── Commands/ # 命令行工具
|
|
|
+│ └── TestCommand.php # 示例命令
|
|
|
+├── Config/ # 配置文件
|
|
|
+│ └── test.php # 模块配置
|
|
|
+├── Databases/ # 数据库相关
|
|
|
+│ ├── GenerateSql/ # SQL文件
|
|
|
+│ │ ├── test_items.sql # 创建数据表的SQL
|
|
|
+│ │ └── test_logs.sql # 日志表SQL
|
|
|
+│ └── Repositories/ # 数据仓库（后台专用）
|
|
|
+│ └── TestRepository.php # 测试仓库
|
|
|
+├── Docs/ # 文档目录
|
|
|
+│ ├── README.md # 模块文档索引
|
|
|
+│ ├── 设计文档.md # 设计文档
|
|
|
+│ └── 开发指南.md # 开发指南
|
|
|
+├── Dtos/ # 数据传输对象
|
|
|
+│ └── TestDto.php # 测试DTO
|
|
|
+├── Enums/ # 枚举类型定义
|
|
|
+│ ├── TEST_STATUS.php # 状态枚举
|
|
|
+│ └── TEST_TYPE.php # 类型枚举
|
|
|
+├── Events/ # 事件类
|
|
|
+│ └── TestCreatedEvent.php # 测试创建事件
|
|
|
+├── Exceptions/ # 自定义异常
|
|
|
+│ └── TestException.php # 测试异常
|
|
|
+├── Listeners/ # 事件监听器
|
|
|
+│ └── TestCreatedListener.php # 测试创建监听器
|
|
|
+├── Logics/ # 业务逻辑类（内部使用）
|
|
|
+│ └── Test.php # 测试逻辑
|
|
|
+├── Models/ # 数据模型
|
|
|
+│ ├── TestItem.php # 测试项目模型
|
|
|
+│ └── TestLog.php # 测试日志模型
|
|
|
+├── Providers/ # 服务提供者
|
|
|
+│ └── TestServiceProvider.php # 测试服务提供者
|
|
|
+├── Services/ # 服务类（对外接口）
|
|
|
+│ └── TestService.php # 测试服务
|
|
|
+├── Validations/ # 验证类（业务验证）
|
|
|
+│ └── TestCreateValidation.php # 创建验证
|
|
|
+├── Validators/ # 验证器（单一验证逻辑）
|
|
|
+│ └── TestStatusValidator.php # 状态验证器
|
|
|
+└── Tests/ # 测试目录
|
|
|
+ ├── TestServiceTest.php # 服务测试
|
|
|
+ └── test_manual.php # 手动测试脚本
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 目录说明
|
|
|
+
|
|
|
+| 目录 | 用途 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| **AdminControllers/** | 后台管理界面 | 继承自UCore\DcatAdmin\AdminController |
|
|
|
+| **Commands/** | 命令行工具 | 定时任务、数据处理等命令 |
|
|
|
+| **Config/** | 配置文件 | 模块相关配置参数 |
|
|
|
+| **Databases/** | 数据库相关 | SQL文件和Repository类 |
|
|
|
+| **Docs/** | 文档目录 | 模块设计和开发文档 |
|
|
|
+| **Dtos/** | 数据传输对象 | 继承自UCore\Dto\BaseDto |
|
|
|
+| **Enums/** | 枚举定义 | 使用PHP enum语法，避免魔法数字 |
|
|
|
+| **Events/** | 事件类 | 模块间通信事件 |
|
|
|
+| **Exceptions/** | 自定义异常 | 业务异常处理 |
|
|
|
+| **Listeners/** | 事件监听器 | 处理事件响应 |
|
|
|
+| **Logics/** | 业务逻辑 | 内部业务处理，不对外暴露 |
|
|
|
+| **Models/** | 数据模型 | 继承自UCore\ModelCore，无业务逻辑 |
|
|
|
+| **Providers/** | 服务提供者 | 注册服务和事件 |
|
|
|
+| **Services/** | 服务接口 | 对外提供功能，调用Logics层 |
|
|
|
+| **Validations/** | 验证类 | 复合验证逻辑 |
|
|
|
+| **Validators/** | 验证器 | 单一验证逻辑 |
|
|
|
+| **Tests/** | 测试文件 | 单元测试和手动测试 |
|
|
|
+
|
|
|
+## 3. 架构设计
|
|
|
+
|
|
|
+### 3.1 分层架构
|
|
|
+
|
|
|
+Test模块采用标准的分层架构设计：
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────┐
|
|
|
+│ Controllers │ ← HTTP请求处理
|
|
|
+├─────────────────┤
|
|
|
+│ Services │ ← 对外服务接口
|
|
|
+├─────────────────┤
|
|
|
+│ Logics │ ← 内部业务逻辑
|
|
|
+├─────────────────┤
|
|
|
+│ Models │ ← 数据模型层
|
|
|
+└─────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+### 3.2 设计原则
|
|
|
+
|
|
|
+1. **单一职责原则**：每个类只负责一个功能领域
|
|
|
+2. **关注点分离**：模型只负责数据结构，业务逻辑由Logic类处理
|
|
|
+3. **依赖注入**：通过构造函数注入依赖，提高可测试性
|
|
|
+4. **事务完整性**：涉及多个操作的功能使用数据库事务
|
|
|
+5. **日志记录**：关键操作记录详细日志
|
|
|
+
|
|
|
+### 3.3 模块交互
|
|
|
+
|
|
|
+- **服务层对外**：其他模块只能通过Services层访问功能
|
|
|
+- **逻辑层内部**：Logic类处理具体业务规则
|
|
|
+- **事件通信**：模块间通过事件进行松耦合通信
|
|
|
+- **数据访问**：Repository层仅供后台管理使用
|
|
|
+
|
|
|
+## 4. 开发规范
|
|
|
+
|
|
|
+### 4.1 命名规范
|
|
|
+
|
|
|
+#### 4.1.1 类命名
|
|
|
+- **模型类**：继承自`\UCore\ModelCore`，如`TestItem`
|
|
|
+- **服务类**：以`Service`结尾，如`TestService`
|
|
|
+- **逻辑类**：简单类名，如`Test`
|
|
|
+- **验证类**：以`Validation`结尾，如`TestCreateValidation`
|
|
|
+- **验证器**：以`Validator`结尾，如`TestStatusValidator`
|
|
|
+- **枚举类**：全大写，如`TEST_STATUS`
|
|
|
+- **DTO类**：以`Dto`结尾，如`TestDto`
|
|
|
+
|
|
|
+#### 4.1.2 数据库命名
|
|
|
+- **表名前缀**：使用模块前缀，如`test_`
|
|
|
+- **全局前缀**：所有表都有`kku_`前缀
|
|
|
+- **完整表名**：`kku_test_items`、`kku_test_logs`
|
|
|
+
|
|
|
+#### 4.1.3 命名空间
|
|
|
+- **基础命名空间**：`App\Module\Test`
|
|
|
+- **Handler命名空间**：`App\Module\AppGame\Handler`（接口层）
|
|
|
+
|
|
|
+### 4.2 代码规范
|
|
|
+
|
|
|
+#### 4.2.1 模型设计
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Models;
|
|
|
+
|
|
|
+use UCore\ModelCore;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试项目模型
|
|
|
+ *
|
|
|
+ * field start
|
|
|
+ * @property int $id 主键ID
|
|
|
+ * @property string $name 项目名称
|
|
|
+ * @property int $status 状态
|
|
|
+ * @property \Carbon\Carbon $created_at 创建时间
|
|
|
+ * @property \Carbon\Carbon $updated_at 更新时间
|
|
|
+ * field end
|
|
|
+ */
|
|
|
+class TestItem extends ModelCore
|
|
|
+{
|
|
|
+ // attrlist start
|
|
|
+ protected $fillable = [
|
|
|
+ 'name',
|
|
|
+ 'status',
|
|
|
+ ];
|
|
|
+ // attrlist end
|
|
|
+
|
|
|
+ /**
|
|
|
+ * 状态访问器
|
|
|
+ */
|
|
|
+ public function getStatusNameAttribute(): string
|
|
|
+ {
|
|
|
+ return TEST_STATUS::getName($this->status);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 4.2.2 服务层设计
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Services;
|
|
|
+
|
|
|
+use App\Module\Test\Dtos\TestDto;
|
|
|
+use App\Module\Test\Logics\Test as TestLogic;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试服务类
|
|
|
+ *
|
|
|
+ * 对外提供测试相关功能接口
|
|
|
+ */
|
|
|
+class TestService
|
|
|
+{
|
|
|
+ /**
|
|
|
+ * 创建测试项目
|
|
|
+ *
|
|
|
+ * @param array $data 项目数据
|
|
|
+ * @return TestDto
|
|
|
+ */
|
|
|
+ public static function createTest(array $data): TestDto
|
|
|
+ {
|
|
|
+ $result = TestLogic::createTest($data);
|
|
|
+ return TestDto::fromModel($result);
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * 获取测试项目列表
|
|
|
+ *
|
|
|
+ * @param array $filters 筛选条件
|
|
|
+ * @return array
|
|
|
+ */
|
|
|
+ public static function getTestList(array $filters = []): array
|
|
|
+ {
|
|
|
+ return TestLogic::getTestList($filters);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 4.2.3 枚举设计
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Enums;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试状态枚举
|
|
|
+ */
|
|
|
+enum TEST_STATUS: int
|
|
|
+{
|
|
|
+ case PENDING = 1; // 待处理
|
|
|
+ case PROCESSING = 2; // 处理中
|
|
|
+ case COMPLETED = 3; // 已完成
|
|
|
+ case FAILED = 4; // 失败
|
|
|
+
|
|
|
+ /**
|
|
|
+ * 获取状态名称
|
|
|
+ */
|
|
|
+ public function getName(): string
|
|
|
+ {
|
|
|
+ return match ($this) {
|
|
|
+ self::PENDING => '待处理',
|
|
|
+ self::PROCESSING => '处理中',
|
|
|
+ self::COMPLETED => '已完成',
|
|
|
+ self::FAILED => '失败',
|
|
|
+ };
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * 获取所有状态
|
|
|
+ */
|
|
|
+ public static function getAll(): array
|
|
|
+ {
|
|
|
+ return [
|
|
|
+ self::PENDING->value => self::PENDING->getName(),
|
|
|
+ self::PROCESSING->value => self::PROCESSING->getName(),
|
|
|
+ self::COMPLETED->value => self::COMPLETED->getName(),
|
|
|
+ self::FAILED->value => self::FAILED->getName(),
|
|
|
+ ];
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 4.3 验证机制
|
|
|
+
|
|
|
+#### 4.3.1 Validation类
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Validations;
|
|
|
+
|
|
|
+use UCore\Validation\ValidationCore;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试创建验证类
|
|
|
+ */
|
|
|
+class TestCreateValidation extends ValidationCore
|
|
|
+{
|
|
|
+ public function rules($rules = []): array
|
|
|
+ {
|
|
|
+ return [
|
|
|
+ ['name', 'required'],
|
|
|
+ ['name', 'string', 'max' => 255],
|
|
|
+ ['status', 'integer', 'min' => 1],
|
|
|
+ ];
|
|
|
+ }
|
|
|
+
|
|
|
+ public function default(): array
|
|
|
+ {
|
|
|
+ return [
|
|
|
+ 'status' => TEST_STATUS::PENDING->value,
|
|
|
+ ];
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 4.3.2 Validator类
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Validators;
|
|
|
+
|
|
|
+use UCore\Validation\ValidatorCore;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试状态验证器
|
|
|
+ */
|
|
|
+class TestStatusValidator extends ValidatorCore
|
|
|
+{
|
|
|
+ public function validate($value, $arg = null): bool
|
|
|
+ {
|
|
|
+ if (!in_array($value, array_keys(TEST_STATUS::getAll()))) {
|
|
|
+ $this->addError($arg, '状态值无效');
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+ return true;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 5. 最佳实践
|
|
|
+
|
|
|
+### 5.1 数据库设计
|
|
|
+
|
|
|
+#### 5.1.1 表结构设计
|
|
|
+```sql
|
|
|
+-- 测试项目表
|
|
|
+CREATE TABLE `kku_test_items` (
|
|
|
+ `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
|
|
+ `name` varchar(255) NOT NULL COMMENT '项目名称',
|
|
|
+ `description` text COMMENT '项目描述',
|
|
|
+ `status` tinyint NOT NULL DEFAULT 1 COMMENT '状态：1待处理，2处理中，3已完成，4失败',
|
|
|
+ `config` json DEFAULT NULL COMMENT '配置信息',
|
|
|
+ `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
|
|
+ `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
|
|
+ PRIMARY KEY (`id`),
|
|
|
+ KEY `idx_status` (`status`),
|
|
|
+ KEY `idx_created_at` (`created_at`)
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='测试项目表';
|
|
|
+
|
|
|
+-- 测试日志表
|
|
|
+CREATE TABLE `kku_test_logs` (
|
|
|
+ `id` bigint NOT NULL AUTO_INCREMENT COMMENT '日志ID',
|
|
|
+ `test_id` int NOT NULL COMMENT '测试项目ID',
|
|
|
+ `action` varchar(100) NOT NULL COMMENT '操作类型',
|
|
|
+ `message` text COMMENT '日志消息',
|
|
|
+ `data` json DEFAULT NULL COMMENT '相关数据',
|
|
|
+ `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
|
|
+ PRIMARY KEY (`id`),
|
|
|
+ KEY `idx_test_id` (`test_id`),
|
|
|
+ KEY `idx_action` (`action`),
|
|
|
+ KEY `idx_created_at` (`created_at`)
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='测试日志表';
|
|
|
+```
|
|
|
+
|
|
|
+#### 5.1.2 索引设计原则
|
|
|
+- **主键索引**：每个表必须有主键
|
|
|
+- **外键索引**：关联字段建立索引
|
|
|
+- **查询索引**：常用查询条件建立索引
|
|
|
+- **复合索引**：多字段查询建立复合索引
|
|
|
+
|
|
|
+### 5.2 事件系统
|
|
|
+
|
|
|
+#### 5.2.1 事件定义
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Events;
|
|
|
+
|
|
|
+use App\Module\Test\Models\TestItem;
|
|
|
+use Illuminate\Foundation\Events\Dispatchable;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试创建事件
|
|
|
+ */
|
|
|
+class TestCreatedEvent
|
|
|
+{
|
|
|
+ use Dispatchable;
|
|
|
+
|
|
|
+ public TestItem $testItem;
|
|
|
+
|
|
|
+ public function __construct(TestItem $testItem)
|
|
|
+ {
|
|
|
+ $this->testItem = $testItem;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 5.2.2 事件监听器
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Listeners;
|
|
|
+
|
|
|
+use App\Module\Test\Events\TestCreatedEvent;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试创建监听器
|
|
|
+ */
|
|
|
+class TestCreatedListener
|
|
|
+{
|
|
|
+ public function handle(TestCreatedEvent $event): void
|
|
|
+ {
|
|
|
+ // 处理测试创建后的逻辑
|
|
|
+ // 如：发送通知、更新统计等
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.3 后台管理
|
|
|
+
|
|
|
+#### 5.3.1 控制器设计
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\AdminControllers;
|
|
|
+
|
|
|
+use App\Module\Test\AdminControllers\Helper\TestGridHelper;
|
|
|
+use App\Module\Test\AdminControllers\Helper\TestFormHelper;
|
|
|
+use App\Module\Test\Repositories\TestRepository;
|
|
|
+use UCore\DcatAdmin\AdminController;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试后台控制器
|
|
|
+ *
|
|
|
+ * @route /admin/test-items
|
|
|
+ */
|
|
|
+class TestController extends AdminController
|
|
|
+{
|
|
|
+ protected string $title = '测试管理';
|
|
|
+ protected string $repository = TestRepository::class;
|
|
|
+
|
|
|
+ protected function grid()
|
|
|
+ {
|
|
|
+ return TestGridHelper::make($this->repository());
|
|
|
+ }
|
|
|
+
|
|
|
+ protected function form()
|
|
|
+ {
|
|
|
+ return TestFormHelper::make();
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.4 测试规范
|
|
|
+
|
|
|
+#### 5.4.1 单元测试
|
|
|
+```php
|
|
|
+<?php
|
|
|
+
|
|
|
+namespace App\Module\Test\Tests;
|
|
|
+
|
|
|
+use App\Module\Test\Services\TestService;
|
|
|
+use PHPUnit\Framework\TestCase;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 测试服务单元测试
|
|
|
+ */
|
|
|
+class TestServiceTest extends TestCase
|
|
|
+{
|
|
|
+ public function testCreateTest()
|
|
|
+ {
|
|
|
+ $data = [
|
|
|
+ 'name' => '测试项目',
|
|
|
+ 'description' => '这是一个测试项目',
|
|
|
+ ];
|
|
|
+
|
|
|
+ $result = TestService::createTest($data);
|
|
|
+
|
|
|
+ $this->assertNotNull($result);
|
|
|
+ $this->assertEquals($data['name'], $result->name);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 5.4.2 手动测试
|
|
|
+```php
|
|
|
+<?php
|
|
|
+// app/Module/Test/Tests/test_manual.php
|
|
|
+
|
|
|
+require_once __DIR__ . '/../../../../bootstrap/app.php';
|
|
|
+
|
|
|
+use App\Module\Test\Services\TestService;
|
|
|
+
|
|
|
+// 测试创建功能
|
|
|
+$data = [
|
|
|
+ 'name' => '手动测试项目',
|
|
|
+ 'description' => '手动测试描述',
|
|
|
+];
|
|
|
+
|
|
|
+try {
|
|
|
+ $result = TestService::createTest($data);
|
|
|
+ echo "创建成功：" . json_encode($result, JSON_UNESCAPED_UNICODE) . "\n";
|
|
|
+} catch (Exception $e) {
|
|
|
+ echo "创建失败：" . $e->getMessage() . "\n";
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 6. 参考示例
|
|
|
+
|
|
|
+### 6.1 物品模块参考
|
|
|
+
|
|
|
+Test模块可以参考GameItems模块的以下设计：
|
|
|
+
|
|
|
+- **冻结功能**：物品冻结机制的实现方式
|
|
|
+- **拆堆模式**：统一属性物品的数量管理
|
|
|
+- **事务处理**：多步骤操作的事务保护
|
|
|
+- **日志记录**：完整的操作审计机制
|
|
|
+
|
|
|
+### 6.2 Mex模块参考
|
|
|
+
|
|
|
+Test模块可以参考Mex模块的以下设计：
|
|
|
+
|
|
|
+- **撮合算法**：复杂业务逻辑的处理方式
|
|
|
+- **状态机**：订单状态的流转管理
|
|
|
+- **定时任务**：后台任务的设计模式
|
|
|
+- **多币种适配**：灵活的配置管理
|
|
|
+
|
|
|
+### 6.3 农场模块参考
|
|
|
+
|
|
|
+Test模块可以参考Farm模块的以下设计：
|
|
|
+
|
|
|
+- **生长周期**：时间相关业务的处理
|
|
|
+- **灾害系统**：随机事件的实现机制
|
|
|
+- **升级系统**：进度管理的设计模式
|
|
|
+- **神灵加持**：临时效果的管理方式
|
|
|
+
|
|
|
+## 7. 开发指南
|
|
|
+
|
|
|
+### 7.1 新建模块步骤
|
|
|
+
|
|
|
+1. **创建目录结构**：按照标准目录结构创建文件夹
|
|
|
+2. **定义枚举类型**：先定义业务相关的枚举
|
|
|
+3. **设计数据模型**：创建数据库表和模型类
|
|
|
+4. **实现业务逻辑**：编写Logic类处理业务规则
|
|
|
+5. **提供服务接口**：创建Service类对外提供功能
|
|
|
+6. **添加验证机制**：实现Validation和Validator类
|
|
|
+7. **创建后台管理**：实现AdminController和Helper类
|
|
|
+8. **编写测试用例**：添加单元测试和手动测试
|
|
|
+9. **完善文档**：编写详细的模块文档
|
|
|
+
|
|
|
+### 7.2 注意事项
|
|
|
+
|
|
|
+1. **模型无业务逻辑**：模型只负责数据结构定义
|
|
|
+2. **服务层对外**：其他模块只能通过Service层访问
|
|
|
+3. **事务保护**：多步骤操作必须使用数据库事务
|
|
|
+4. **异常处理**：Handler中不设置异常处理，继续抛出
|
|
|
+5. **日志记录**：关键操作记录详细日志
|
|
|
+6. **中文注释**：代码中添加中文注释说明
|
|
|
+7. **文档维护**：及时更新模块文档
|
|
|
+
|
|
|
+### 7.3 扩展建议
|
|
|
+
|
|
|
+1. **功能扩展**：基于现有架构添加新功能
|
|
|
+2. **性能优化**：添加缓存机制和索引优化
|
|
|
+3. **监控告警**：实现业务监控和异常告警
|
|
|
+4. **国际化**：支持多语言和多地区
|
|
|
+5. **API接口**：提供RESTful API接口
|
|
|
+6. **移动端适配**：支持移动端应用接入
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**最后更新时间**：2025年06月16日
|
|
|
+**文档版本**：v1.0
|
|
|
+**维护人员**：开发团队
|
|
|
+```
|
|
|
|
