mosen/mosen-api

A comprehensive API plugin for ThinkPHP framework

v1.4.5 2025-04-18 15:30 UTC

Requires

• php: >=7.2.5
• ext-fileinfo: *
• ext-json: *
• ext-mbstring: *
• ext-redis: *
• monolog/monolog: ^2.0
• phpoffice/phpspreadsheet: ^1.29
• predis/predis: ^2.0
• swagger-api/swagger-ui: ^4.0
• symfony/polyfill-ctype: ^1.27
• tecnickcom/tcpdf: ^6.6
• topthink/framework: ^8.0
• topthink/think-orm: ^3.0|^4.0
• topthink/think-queue: ^3.0
• zircote/swagger-php: ^3.0

Requires (Dev)

• mockery/mockery: ^1.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^9.0
• symfony/var-dumper: ^5.0

Suggests

• ext-curl: Required for HTTP requests
• ext-gd: Required for image processing
• ext-imagick: Alternative for image processing
• ext-zip: Required for ZIP archive support
• league/flysystem-ftp: For FTP storage support
• league/flysystem-sftp: For SFTP storage support

MIT

• Mosen

README

Mosen API 插件是一个功能丰富的 API 开发工具包，提供了多种常用的 API 开发功能。

功能特性

• 统一的响应格式
• 异常处理
• 请求日志
• 签名验证
• 跨域支持
• 队列任务
• 文件处理
• 文档生成

环境要求

• PHP >= 8.0
• ThinkPHP >= 8.0
• Redis（用于队列功能）
• Composer

安装

composer require mosen/api

配置

在 config/ms_plugin.php 中配置插件：

return [
    // 导出配置
    'export' => [
        'path' => runtime_path() . 'export/',
        'url' => '/export/',
    ],
    
    // 队列配置
    'queue' => [
        'default' => 'redis',
        'connections' => [
            'redis' => [
                'type' => 'redis',
                'host' => '127.0.0.1',
                'port' => 6379,
            ],
        ],
        'monitor' => [
            'enabled' => true,
            'timeout' => 3600,
        ],
    ],
    
    // 文件配置
    'file' => [
        'default' => 'local',
        'disks' => [
            'local' => [
                'type' => 'local',
                'root' => runtime_path() . 'storage',
            ],
        ],
    ],
    
    // 日志配置
    'log' => [
        'default' => 'file',
        'channels' => [
            'file' => [
                'type' => 'file',
                'path' => runtime_path() . 'log/',
            ],
        ],
    ],
    
    // 文档配置
    'doc' => [
        'path' => runtime_path() . 'doc/',
        'formats' => ['json', 'yaml'],
    ],
    
    // 签名配置
    'signature' => [
        'key' => 'your-signature-key',
        'expire' => 3600,
    ],
];

使用说明

响应服务

use mosen\api\Service\ResponseService;

class YourController
{
    protected ResponseService $responseService;

    public function __construct(ResponseService $responseService)
    {
        $this->responseService = $responseService;
    }

    public function index()
    {
        $data = ['name' => 'test'];
        return $this->responseService->json($data);
    }
}

异常处理

use mosen\api\Service\ErrorCodeService;

class YourController
{
    protected ErrorCodeService $errorCodeService;

    public function __construct(ErrorCodeService $errorCodeService)
    {
        $this->errorCodeService = $errorCodeService;
    }

    public function index()
    {
        try {
            // 你的代码
        } catch (\Exception $e) {
            $message = $this->errorCodeService->getMessage(500);
            return json(['code' => 500, 'msg' => $message]);
        }
    }
}

队列任务

use mosen\api\Service\QueueService;

class YourController
{
    protected QueueService $queueService;

    public function __construct(QueueService $queueService)
    {
        $this->queueService = $queueService;
    }

    public function index()
    {
        $job = new YourJob();
        $this->queueService->push($job);
    }
}

文件处理

use mosen\api\Service\FileService;

class YourController
{
    protected FileService $fileService;

    public function __construct(FileService $fileService)
    {
        $this->fileService = $fileService;
    }

    public function upload()
    {
        $file = request()->file('file');
        $result = $this->fileService->upload($file);
        return json($result);
    }
}

文档生成

use mosen\api\Service\DocService;

class YourController
{
    protected DocService $docService;

    public function __construct(DocService $docService)
    {
        $this->docService = $docService;
    }

    public function generate()
    {
        $result = $this->docService->generate();
        return json($result);
    }
}

中间件

异常处理中间件

// 在全局中间件中注册
'middleware' => [
    \mosen\api\middleware\ExceptionHandlerMiddleware::class,
],

请求日志中间件

// 在全局中间件中注册
'middleware' => [
    \mosen\api\middleware\RequestLogMiddleware::class,
],

签名验证中间件

// 在路由中间件中注册
Route::group('api', function () {
    Route::rule('test', 'test/index')->middleware(\mosen\api\middleware\SignatureMiddleware::class);
});

跨域中间件

// 在全局中间件中注册
'middleware' => [
    \mosen\api\middleware\CorsMiddleware::class,
],

命令行工具

队列监控

php think queue:monitor

注意事项

1. 插件提供了核心功能，具体的业务逻辑需要自行实现
2. 配置项可以根据项目需求进行调整
3. 建议在生产环境中启用签名验证
4. 文件上传建议使用云存储
5. 队列任务建议使用 Redis 驱动
6. 文档生成支持多种格式，建议使用 JSON 或 YAML

许可证

MIT