插件开发指南

本指南介绍如何为 MineShop 开发自定义插件。

🎯 开发流程

1. 创建插件目录结构
2. 编写 ConfigProvider
3. 实现业务逻辑
4. 注册到主应用
5. 测试和发布

📁 目录结构

plugins/my-plugin/
├── src/
│   ├── ConfigProvider.php    # 配置提供者（必需）
│   ├── Controller/           # 控制器
│   │   └── MyController.php
│   ├── Service/              # 服务层
│   │   └── MyService.php
│   ├── Repository/           # 数据仓库
│   ├── Model/                # 数据模型
│   └── Job/                  # 异步任务
├── web/                      # 前端资源
│   ├── index.ts              # 入口文件
│   ├── views/                # 页面组件
│   └── api/                  # API 定义
├── composer.json             # 包定义
└── README.md                 # 说明文档

🔧 ConfigProvider 详解

<?php

namespace Plugin\MyPlugin;

class ConfigProvider
{
    public function __invoke(): array
    {
        return [
            // 1. 注解扫描路径
            'annotations' => [
                'scan' => [
                    'paths' => [__DIR__],
                ],
            ],
            
            // 2. 依赖注入
            'dependencies' => [
                MyInterface::class => MyImplementation::class,
            ],
            
            // 3. 异步队列（自动合并）
            'async_queue' => [
                'my-queue' => [
                    'driver' => RedisDriver::class,
                    'channel' => '{my-queue}',
                ],
            ],
            
            // 4. 自定义进程
            'processes' => [
                MyProcess::class,
            ],
            
            // 5. 中间件
            'middlewares' => [
                'http' => [
                    MyMiddleware::class,
                ],
            ],
            
            // 6. 命令行
            'commands' => [
                MyCommand::class,
            ],
            
            // 7. 定时任务
            'crontab' => [
                MyCrontab::class,
            ],
        ];
    }
}

📦 composer.json 配置

{
    "name": "mineshop/my-plugin",
    "description": "My custom plugin for MineShop",
    "type": "library",
    "license": "Apache-2.0",
    "require": {
        "php": ">=8.1"
    },
    "autoload": {
        "psr-4": {
            "Plugin\\MyPlugin\\": "src/"
        }
    },
    "extra": {
        "hyperf": {
            "config": "Plugin\\MyPlugin\\ConfigProvider"
        }
    }
}

🎨 前端资源

入口文件

// web/index.ts
export default {
    name: 'my-plugin',
    
    // 路由配置
    routes: [
        {
            path: '/my-plugin',
            name: 'MyPlugin',
            component: () => import('./views/index.vue'),
            meta: { title: '我的插件' }
        }
    ],
    
    // 菜单配置
    menus: [
        {
            name: 'my-plugin',
            title: '我的插件',
            icon: 'icon-plugin',
            path: '/my-plugin'
        }
    ]
}

API 定义

// web/api/my-plugin.ts
import { request } from '@/utils/request'

export function getList(params: any) {
    return request.get('/my-plugin/list', { params })
}

export function create(data: any) {
    return request.post('/my-plugin', data)
}

🔌 注册插件

方式一：本地开发

在主应用 composer.json 中添加：

{
    "repositories": [
        {
            "type": "path",
            "url": "./plugins/my-plugin"
        }
    ],
    "require": {
        "mineshop/my-plugin": "*"
    }
}

方式二：Composer 包

发布到 Packagist 后直接安装：

composer require mineshop/my-plugin

✅ 最佳实践

1. 命名规范: 使用 Plugin\{PluginName} 命名空间
2. 配置隔离: 避免与主应用配置键名冲突
3. 依赖声明: 在 composer.json 中明确声明依赖
4. 版本管理: 遵循语义化版本规范
5. 文档完善: 提供清晰的 README 和使用说明
6. 测试覆盖: 编写单元测试和集成测试

⚠️ 注意事项

1. 数据库迁移: 插件如需数据表，提供迁移脚本
2. 卸载清理: 考虑插件卸载时的数据清理
3. 版本兼容: 注意与主应用版本兼容性
4. 性能影响: 避免在 ConfigProvider 中执行耗时操作

📚 相关文档

• 插件系统概述
• 导出中心插件
• 异步队列