kknongchang_2506/app/Module/OpenAPI/Docs/Handler机制说明.md

OpenAPI模块Handler机制说明

概述

OpenAPI模块已重构为使用Handler机制来处理具体的业务逻辑，移除了Routes目录，改用注解方式注册路由。这种架构提供了更好的代码组织、可测试性和可维护性。

架构变更

🔄 重构前后对比

重构前

Routes/
├── api.php          # 路由文件，包含匿名函数处理逻辑
└── admin.php        # 后台路由文件

Controllers/
├── AuthController.php
├── AppController.php
└── WebhookController.php

重构后

Handlers/               # 新增：业务处理器
├── BaseHandler.php     # Handler基类
├── User/
│   ├── UserInfoHandler.php
│   └── UserListHandler.php
├── Game/
│   └── GameStatsHandler.php
└── Fund/
    └── FundBalanceHandler.php

Controllers/
├── ApiController.php   # 新增：通用API控制器
├── AuthController.php  # 保留：认证控制器
├── AppController.php   # 保留：应用管理控制器
└── WebhookController.php # 保留：Webhook控制器

Services/
├── RouteRegistrationService.php    # 新增：路由注册服务
└── HandlerRegistrationService.php  # 新增：Handler注册服务

Contracts/
└── HandlerInterface.php # 新增：Handler接口

Handler机制详解

1. Handler接口

所有Handler必须实现HandlerInterface接口：

interface HandlerInterface
{
    public function handle(array $data, array $context = []): JsonResponse;
    public function validatePermissions(array $scopes, array $context = []): bool;
    public function getRequiredScopes(): array;
}

2. BaseHandler基类

提供Handler的基础功能：

abstract class BaseHandler implements HandlerInterface
{
    // 权限验证
    public function validatePermissions(array $scopes, array $context = []): bool;
    
    // 响应方法
    protected function successResponse(string $message, $data = null, int $code = 200);
    protected function errorResponse(string $message, $errors = null, int $code = 400);
    
    // 数据验证
    protected function validateData(array $data, array $rules): ?array;
    
    // 上下文获取
    protected function getUserId(array $context): int;
    protected function getApp(array $context): ?OpenApiApp;
    
    // 日志记录
    protected function logAction(string $action, array $data, array $context): void;
}

3. Handler实现示例

UserInfoHandler

class UserInfoHandler extends BaseHandler
{
    public function getRequiredScopes(): array
    {
        return ['USER_READ'];
    }

    public function handle(array $data, array $context = []): JsonResponse
    {
        // 验证权限
        if (!$this->validatePermissions($app->scopes ?? [], $context)) {
            return $this->errorResponse('权限不足', null, 403);
        }

        // 获取用户信息
        $userInfo = $this->getUserInfo($userId);
        
        // 记录日志
        $this->logAction('user.info.get', ['user_id' => $userId], $context);

        return $this->successResponse('获取用户信息成功', $userInfo);
    }
}

路由注解机制

1. 注解路由注册

使用RouteRegistrationService来注册路由：

class RouteRegistrationService
{
    public function registerApiRoutes(): void
    {
        Route::get('/user/info', [ApiController::class, 'getUserInfo'])
            ->name('openapi.user.info');
    }
}

2. 控制器注解

在控制器中使用注解定义路由属性：

#[Prefix('api/openapi')]
#[Middleware(['api', 'openapi'])]
class ApiController extends Controller
{
    #[Middleware('openapi.scope:USER_READ')]
    public function getUserInfo(Request $request, UserInfoHandler $handler): JsonResponse
    {
        return $this->handleRequest($request, $handler);
    }
}

已实现的Handler

1. 用户模块Handler

UserInfoHandler

• 路由: GET /api/openapi/user/info
• 权限: USER_READ
• 功能: 获取用户详细信息
• 参数: user_id（可选，默认使用上下文中的用户ID）

UserListHandler

• 路由: GET /api/openapi/user/list
• 权限: USER_READ
• 功能: 获取用户列表（分页）
• 参数: page, per_page, search, status

2. 游戏模块Handler

GameStatsHandler

• 路由: GET /api/openapi/game/stats
• 权限: GAME_READ
• 功能: 获取游戏统计数据
• 参数: date_from, date_to, user_id, game_type

3. 资金模块Handler

FundBalanceHandler

• 路由: GET /api/openapi/fund/balance
• 权限: FUND_READ
• 功能: 获取用户资金余额
• 参数: user_id, currency_types, include_frozen

使用指南

1. 创建新的Handler

<?php

namespace App\Module\OpenAPI\Handlers\YourModule;

use App\Module\OpenAPI\Handlers\BaseHandler;
use Illuminate\Http\JsonResponse;

class YourHandler extends BaseHandler
{
    public function getRequiredScopes(): array
    {
        return ['YOUR_SCOPE'];
    }

    public function handle(array $data, array $context = []): JsonResponse
    {
        // 实现你的业务逻辑
        return $this->successResponse('操作成功', $result);
    }
}

2. 注册Handler

在HandlerRegistrationService中注册：

protected function registerYourHandlers(ServiceProvider $provider): void
{
    $provider->app->singleton(YourHandler::class, function ($app) {
        return new YourHandler(
            $app->make(ScopeService::class)
        );
    });
}

3. 添加路由

在RouteRegistrationService中添加路由：

Route::get('/your/endpoint', [ApiController::class, 'yourMethod'])
    ->name('openapi.your.endpoint');

4. 添加控制器方法

在ApiController中添加方法：

#[Middleware('openapi.scope:YOUR_SCOPE')]
public function yourMethod(Request $request, YourHandler $handler): JsonResponse
{
    return $this->handleRequest($request, $handler);
}

与业务模块集成

当前状态

目前Handler返回的是示例数据，需要与实际业务模块集成：

// 当前示例代码
protected function getUserInfo(int $userId): ?array
{
    // TODO: 这里应该调用User模块的服务
    // 例如: return app(UserService::class)->getUserById($userId);
    
    // 暂时返回示例数据
    return ['id' => $userId, 'name' => "用户{$userId}"];
}

集成步骤

1. 引入业务模块服务
2. 替换示例数据
3. 处理异常情况
4. 添加缓存机制
5. 完善日志记录

优势

1. 代码组织

• 业务逻辑与路由分离
• 单一职责原则
• 易于测试和维护

2. 可扩展性

• 新增Handler无需修改现有代码
• 统一的接口规范
• 灵活的权限控制

3. 可测试性

• Handler可以独立测试
• 依赖注入支持
• Mock友好的设计

4. 性能优化

• 延迟加载Handler
• 服务容器管理
• 缓存机制支持

下一步计划

1. 完善现有Handler - 集成实际业务模块
2. 添加更多Handler - 物品、交易等模块
3. 性能优化 - 添加缓存和异步处理
4. 测试覆盖 - 编写单元测试和集成测试
5. 文档完善 - API文档自动生成

Handler机制为OpenAPI模块提供了强大的扩展能力和良好的代码组织结构，为后续的功能扩展奠定了坚实的基础。