kknongchang_2506/app/Module/Test

Test 模块

示例模块 - 展示模块化开发的最佳实践和标准架构

目录

1. 模块概述
2. 目录结构
3. 架构设计
4. 开发规范
5. 最佳实践
6. 参考示例

1. 模块概述

1.1 功能与目的

Test模块是一个标准的示例模块，用于展示项目中模块化开发的最佳实践。它提供了完整的模块架构参考，包括数据层、业务逻辑层、服务层、控制器层等各个层次的标准实现方式。

1.2 主要特点

• 标准架构：遵循项目统一的分层架构设计
• 完整示例：包含所有必要的目录和文件结构
• 最佳实践：展示代码组织、命名规范、设计模式等最佳实践
• 参考模板：为新模块开发提供标准模板
• 逻辑模块：默认不提供Api、前端页面，专注业务逻辑实现
• 注解路由：使用注解方式注册路由，不使用路由配置文件
• 中文友好：支持中文注释和文档，便于团队协作

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               # 模块配置
├── Casts/                      # 自定义类型转换器
│   └── TestAttributesCast.php # 测试属性转换器
├── Databases/                  # 数据库相关
│   └── create.sql             # 数据库创建脚本
├── 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 # 测试服务提供者
├── Repositorys/                # 数据仓库（后台专用）
│   └── TestRepository.php     # 测试仓库
├── Services/                   # 服务类（对外接口）
│   └── TestService.php        # 测试服务
├── Validations/                # 验证类（业务验证）
│   └── TestCreateValidation.php # 创建验证
├── Validators/                 # 验证器（单一验证逻辑）
│   └── TestStatusValidator.php # 状态验证器
└── Tests/                      # 测试目录
    ├── TestServiceTest.php     # 服务测试
    └── test_manual.php         # 手动测试脚本

2.2 目录说明

目录	用途	说明
AdminControllers/	后台管理界面	继承自UCore\DcatAdmin\AdminController
Commands/	命令行工具	定时任务、数据处理等命令
Casts/	自定义类型转换器	处理JSON属性等特殊字段
Config/	配置文件	模块相关配置参数
Databases/	数据库相关	SQL创建脚本
Docs/	文档目录	模块设计和开发文档
Dtos/	数据传输对象	继承自UCore\Dto\BaseDto
Enums/	枚举定义	使用PHP enum语法，避免魔法数字
Events/	事件类	模块间通信事件
Exceptions/	自定义异常	业务异常处理
Listeners/	事件监听器	处理事件响应
Logics/	业务逻辑	内部业务处理，不对外暴露
Models/	数据模型	继承自UCore\ModelCore，无业务逻辑
Providers/	服务提供者	注册服务和事件
Repositorys/	数据仓库	封装数据库操作，仅供后台管理使用
Services/	服务接口	对外提供功能，调用Logics层
Validations/	验证类	复合验证逻辑
Validators/	验证器	单一验证逻辑
Tests/	测试文件	单元测试和手动测试

3. 架构设计

3.1 分层架构

Test模块采用标准的分层架构设计：

┌─────────────────┐
│   Controllers   │ ← HTTP请求处理（非对外模块不提供）
├─────────────────┤
│    Services     │ ← 对外服务接口
├─────────────────┤
│     Logics      │ ← 内部业务逻辑
├─────────────────┤
│     Models      │ ← 数据模型层
└─────────────────┘

3.2 设计原则

1. 单一职责原则：每个类只负责一个功能领域
2. 关注点分离：模型只负责数据结构，业务逻辑由Logic类处理
3. 依赖注入：通过构造函数注入依赖，提高可测试性
4. 事务完整性：涉及多个操作的功能使用数据库事务（注意：Logic层不能开启事务）
5. 日志记录：关键操作记录详细日志
6. 简单设计：功能拆分为独立简单静态类，避免复杂设计模式
7. 中文注释：代码中增加中文注释，提高可读性
8. 异常透传：Handler中不设置异常处理，继续抛出异常交由框架处理

3.3 模块交互

• 服务层对外：其他模块只能通过Services层访问功能，不直接访问其他模块模型
• 逻辑层内部：Logic类处理具体业务规则，服务层直接使用逻辑层和模型
• 事件通信：模块间通过事件进行松耦合通信，模块内部不使用事件机制
• 数据访问：Repositorys层仅供后台管理使用，参考Fund模块实现
• DTO传输：服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
• 响应规范：Handler成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0

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_（物品模块item_，宠物模块pet_）
• 全局前缀：所有表都有kku_前缀（在config/database.php中全局配置）
• 完整表名：kku_test_items、kku_test_logs
• 币种标识：币种ID指FUND_CURRENCY_TYPE枚举value值（1=金币,2=钻石,3=人民币,4=美元）

4.1.3 命名空间

• 基础命名空间：App\Module\Test
• Handler命名空间：App\Module\AppGame\Handler（接口层，专门的对外接口模块）
• 路由使用注解：不使用路由配置文件，采用注解方式注册路由
• 模块定位：模块默认不提供Api、前端页面，为逻辑模块

4.2 代码规范

4.2.1 模型设计

<?php

namespace App\Module\Test\Models;

use UCore\ModelCore;

/**
 * 测试项目模型
 *
 * 设计原则：
 * - 继承自\UCore\ModelCore，保持无业务逻辑
 * - 不设置$prefix属性（全局配置在config/database.php）
 * - 在模型中定义访问器而非控制器中实现逻辑
 * - 为模型创建独立Cast类，不同模型不共用Cast类
 *
 * 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

namespace App\Module\Test\Services;

use App\Module\Test\Dtos\TestDto;
use App\Module\Test\Logics\Test as TestLogic;

/**
 * 测试服务类
 *
 * 设计原则：
 * - 对外Service使用静态方法，内部Logic类处理业务逻辑
 * - 服务层直接使用逻辑层和模型，不使用Repositorys
 * - 模块间通过Service层交互，不直接访问其他模块模型
 * - 服务层返回DTO对象而非Model
 */
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

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 验证机制

@docs/Validation使用示例.md

4.3.1 Validation类

<?php

namespace App\Module\Test\Validations;

use UCore\Validation\ValidationCore;

/**
 * 测试创建验证类
 *
 * 设计原则：
 * - 使用Validation和Validator类处理验证逻辑，参考GodActivationValidation模式
 * - 禁止动态属性赋值，需先定义属性并声明类型
 */
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

namespace App\Module\Test\Validators;

use UCore\Validation\ValidatorCore;

/**
 * 测试状态验证器
 *
 * 设计原则：
 * - 实现单一验证逻辑，使用addError方法而非throwMessage
 * - 字段Key使用$arg参数传入，不直接硬编码
 */
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 表结构设计

-- 测试项目表
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.1.3 数据库设计规范

• 不使用迁移类：直接提供SQL语句修改数据库结构
• 小数存储：全面采用DECIMAL(30,10)直接存储小数值（参考Fund模块）
• 精度配置：硬编码到枚举中，如FUND_CURRENCY_TYPE枚举
• 字段注释：所有字段必须添加中文注释说明
• 时间字段：使用timestamp类型，设置默认值和自动更新

5.2 事件系统

5.2.1 事件定义

<?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

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

namespace App\Module\Test\AdminControllers;

use App\Module\Test\AdminControllers\Helper\TestGridHelper;
use App\Module\Test\AdminControllers\Helper\TestFormHelper;
use App\Module\Test\Repositorys\TestRepository;
use UCore\DcatAdmin\AdminController;

/**
 * 测试后台控制器
 *
 * 设计原则：
 * - 继承自UCore\DcatAdmin\AdminController
 * - 使用Grid/Show/Form的'make'方法实例化
 * - 使用GridHelper/ShowHelper/FormHelper/FilterHelper辅助类
 * - Repositorys类参考Fund模块实现，内部不包含方法，仅供后台管理数据访问
 * - 添加路由注释，加入后台菜单适当位置
 *
 * @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 DTO设计规范

5.4.1 DTO类设计

<?php

namespace App\Module\Test\Dtos;

use UCore\Dto\BaseDto;
use App\Module\Test\Models\TestItem;

/**
 * 测试DTO类
 *
 * 设计原则：
 * - 继承自UCore\Dto\BaseDto
 * - 实现fromModel静态方法
 * - 使用驼峰命名公共属性
 * - 服务层返回DTO对象而非Model
 */
class TestDto extends BaseDto
{
    public int $id;
    public string $name;
    public int $status;
    public string $statusName;
    public string $createdAt;
    public string $updatedAt;

    /**
     * 从模型创建DTO
     */
    public static function fromModel(TestItem $model): self
    {
        $dto = new self();
        $dto->id = $model->id;
        $dto->name = $model->name;
        $dto->status = $model->status;
        $dto->statusName = $model->status_name;
        $dto->createdAt = $model->created_at->toDateTimeString();
        $dto->updatedAt = $model->updated_at->toDateTimeString();

        return $dto;
    }
}

5.5 Handler设计规范

5.5.1 Handler类设计

<?php

namespace App\Module\AppGame\Handler;

use App\Module\Test\Services\TestService;
use App\Module\Test\Validations\TestCreateValidation;
use UCore\Handler\HandlerCore;

/**
 * 测试Handler类
 *
 * 设计原则：
 * - 参考PesticideHandler模式：先验证再执行操作
 * - 不设置异常处理，继续抛出异常交由框架处理
 * - 成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0
 * - Handler中将DTO转换为protobuf格式
 * - 动作型方法使用Res对象处理返回值，不直接返回数组
 */
class TestHandler extends HandlerCore
{
    /**
     * 创建测试项目
     */
    public function createTest($request)
    {
        // 验证请求数据
        $validation = new TestCreateValidation();
        $data = $validation->check($request);

        // 执行业务逻辑
        $result = TestService::createTest($data);

        // 返回响应
        return $this->success([
            'test' => $this->convertToProtobuf($result)
        ]);
    }

    /**
     * 转换DTO为protobuf格式
     */
    private function convertToProtobuf($dto): array
    {
        return [
            'id' => $dto->id,
            'name' => $dto->name,
            'status' => $dto->status,
            'status_name' => $dto->statusName,
            'created_at' => $dto->createdAt,
            'updated_at' => $dto->updatedAt,
        ];
    }
}

5.6 测试规范

5.4.1 单元测试

<?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
// 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. 事务保护：多步骤操作必须使用数据库事务（注意：Logic层不能开启事务）
4. 异常处理：Handler中不设置异常处理，继续抛出
5. 日志记录：关键操作记录详细日志
6. 中文注释：代码中添加中文注释说明
7. 文档维护：及时更新模块文档
8. 任务管理：任务开始前/后检查git status，提交代码并Push，使用中文CommitMessage
9. 完成检查：模块开发完成情况全面检查（服务层、逻辑层、模型层、接口层、事件系统、后台管理、验证系统）
10. 清理检查：清理模块残留时全面检查（代码文件、数据库表、文档内容）

7.2.1 任务记录规范

• 任务记录：任务完成后创建记录于'./AiWork/年月/'目录
• 文件命名：'日时分-任务标题.md'格式
• 工作更新：更新WORK.md文件
• 自动生成目录：添加README.md声明内容自动生成不可修改

7.3 项目环境

7.3.1 开发环境

• 运行环境：使用Docker运行
• 访问地址：http://kku_laravel.local.gd
• 调试工具：使用php artisan debug:reproduce-error命令回放错误请求

7.3.2 测试环境

• 单元测试：在tests目录编写非模块phpunit测试
• 测试运行：使用vendor/bin/phpunit运行测试
• 手动测试：不使用laravel console组织测试

7.4 调试和错误处理

7.4.1 调试规范

• 任务开始前：使用'date'命令获取时间
• 网页测试：使用mcp测试网页修改
• SQL执行：使用mcp执行sql
• 数据问题：优先检查数据结构字段名匹配
• 字段一致性：确保Logic层返回字段名与Handler中访问字段名一致

7.4.2 错误处理原则

• 异常透传：Handler中不设置异常处理，继续抛出异常交由框架处理
• 响应规范：成功时使用RESPONSE_CODE常量，不使用魔法数字0
• protobuf处理：确保所有必需字段有正确数据源

7.5 扩展建议

1. 功能扩展：基于现有架构添加新功能
2. 性能优化：添加缓存机制和索引优化
3. 监控告警：实现业务监控和异常告警
4. 国际化：支持多语言和多地区
5. API接口：提供RESTful API接口
6. 移动端适配：支持移动端应用接入

---

最后更新时间：2025年06月16日 文档版本：v1.0 维护人员：开发团队 ```