mirror of
https://github.com/zhamao-robot/zhamao-framework.git
synced 2026-03-18 05:04:51 +08:00
127 lines
5.9 KiB
Markdown
127 lines
5.9 KiB
Markdown
# 插件开发
|
||
|
||
在框架环境准备就绪后，可以使用框架提供的命令、工具集进行插件的开发。
|
||
|
||
如果你还没有阅读 [快速上手-聊天机器人](/guide/get-started.md) 章节的内容，请先阅读。
|
||
|
||
## 创建插件
|
||
|
||
框架默认支持两种形式的插件，一种是 `file` 单文件模式，另一种是 `psr4` 多文件模式。一般情况下，写一个较为简单的功能插件，推荐使用单文件模式，便于管理。
|
||
编写功能较多、需要分多个文件写逻辑的插件，推荐使用 `psr4` 多文件模式。
|
||
|
||
框架的插件命名方式基于 Composer，Composer 要求组件、插件的名称要有开发者名称和项目名称两部分组成。
|
||
例如，我的开发者代号仓库是 `jackson`，插件名称是 `group-manager`，最终你的插件名称就是 `jackson/group-manager`。
|
||
|
||
```bash
|
||
# 使用终端问答向导创建插件，可根据终端的提示选择你要创建插件的名称、类型和命名空间等内容。
|
||
./zhamao plugin:make --type=file
|
||
# 使用 file 类型的示例骨架创建插件，插件名称为 foobar/test-plugin
|
||
./zhamao plugin:make --type=file foobar/test-plugin
|
||
# 使用 psr4 类型的示例骨架创建插件，插件名称为 foobar/psr4-plugin，命名空间为 foobar
|
||
./zhamao plugin:make --type=psr4 --namespace=foobar foobar/psr4-plugin
|
||
# 设置插件作者名称、描述信息
|
||
./zhamao plugin:make --author=tom --description="示例插件"
|
||
```
|
||
|
||
### 单文件模式
|
||
|
||
单文件模式的优势在于以下几点：
|
||
|
||
- 代码较少的情况下，逻辑表达更清晰，可直接在单文件结构下编写机器人、HTTP 服务器的逻辑。
|
||
- 可以添加额外的框架事件 `onPluginLoad`（框架在读取插件元信息后触发的事件）。
|
||
- 可以添加额外的框架事件 `onPack`（插件在被打包时执行的回调函数）。
|
||
|
||
单文件模式下的插件目录结构如下图所示：
|
||
|
||
```text
|
||
plugins/
|
||
└── test-app/
|
||
├── main.php # 你的插件源代码文件
|
||
└── composer.json # 插件元信息（如名称、版本等）
|
||
```
|
||
|
||
使用 file 模式创建的插件会在 `./plugins/` 目录下新建一个文件夹，文件夹名称一般为插件名称 `xxx/yyy` 的 `yyy`。如果遇到重名文件夹时，框架会提示重名。
|
||
|
||
当然，单文件模式也有劣势：
|
||
|
||
- 插件依赖了其他外部 Composer 组件时，依赖管理不方便。
|
||
- 插件逻辑较为复杂时，写到一个文件内会导致代码过长，不利于维护。
|
||
- 一些注解的绑定、中间件，均无法在单文件模式中使用。
|
||
|
||
### 多文件模式
|
||
|
||
多文件模式适用于几乎任何情况，有以下优势：
|
||
|
||
- 逻辑复杂时，使用 Class 类名和注解绑定的形式，有助于编写大型项目。
|
||
- 逻辑简单但功能点繁多时，可以使用类成员的多个绑定注解的方法区分功能逻辑，避免单文件的混乱。
|
||
- 可以使用注解的全部特性，例如中间件绑定、依赖注入等。
|
||
|
||
多文件模式下的插件目录结构如下图所示：
|
||
|
||
```text
|
||
plugins/
|
||
└── psr4-plugin/
|
||
├── composer.json # 插件元信息（如名称、版本等）
|
||
├── vendor/ # Composer 生成的插件依赖库目录和自动加载文件等
|
||
└── src/ # 你的插件源代码文件目录，符合 PSR-4 格式的
|
||
├── Psr4Plugin.php # 使用创建插件命令生成的初始插件逻辑
|
||
└── ... # 如果你的插件想要分成多个 PHP 文件，那么这里可以有多个
|
||
```
|
||
|
||
### 混合模式
|
||
|
||
混合模式为单文件模式和多文件模式的结合，框架不提供创建混合模式插件脚手架的命令，但你可以自行混合。
|
||
|
||
混合模式其实就是多文件模式，只不过同时也可以引入一个单文件插件，弥补多文件模式没办法绑定 `onPack` 和 `onPluginLoad` 事件的问题。
|
||
|
||
混合模式在多文件模式的基础上多了一个 `main.php` 的单文件：
|
||
|
||
```text
|
||
plugins/
|
||
└── psr4-plugin/
|
||
├── composer.json # 插件元信息（如名称、版本等）
|
||
├── vendor/ # Composer 生成的插件依赖库目录和自动加载文件等
|
||
├── main.php # 插件逻辑（单文件部分）
|
||
└── src/ # 你的插件源代码文件目录（多文件部分）
|
||
├── Psr4Plugin.php # 使用创建插件命令生成的初始插件逻辑
|
||
└── ... # 如果你的插件想要分成多个 PHP 文件，那么这里可以有多个
|
||
```
|
||
|
||
在通过以上三种方式创建插件后，你可以通过 IDE、记事本等形式开始编写你的插件逻辑啦！
|
||
|
||
## 编写插件（WIP）
|
||
|
||
> 此处文档正在努力编写中！
|
||
|
||
插件的编写内容当然取决于异想天开的你，这里用最基本和最典型的例子来说明如何从零编写一个自己的插件。
|
||
|
||
### 机器人命令问答
|
||
|
||
在使用框架的上方创建插件命令创建了一个插件目录和骨架文件后，打开文件可以看到默认生成了一个 BotCommand 机器人聊天命令事件，返回的内容为一句简单的话。
|
||
你可以在创建插件后直接使用此命令，在对接机器人实现端（OneBot 12 实现）后，在与机器人对话的窗口或 App 内发送指令，即可测试机器人插件是否正常运行。
|
||
|
||
我们这里假设通过 psr4 模式创建了插件 `foobar/demo2`，初始化时预置的机器人聊天命令代码可能是下面这样：
|
||
|
||
```php
|
||
#[BotCommand(match: '测试demo2')]
|
||
public function firstBotCommand(BotContext $ctx): void
|
||
{
|
||
$ctx->reply('这是foobar/demo2插件的第一个命令！');
|
||
}
|
||
```
|
||
|
||
<chat-box :my-chats="[
|
||
{type:0,content:'测试demo2'},
|
||
{type:1,content:'这是foobar/demo2插件的第一个命令！'},
|
||
]" />
|
||
|
||
在编写插件逻辑时，你可以自由使用框架内的各个组件和注解，这里不再过多描述。
|
||
|
||
## 插件打包
|
||
|
||
在写了在写了。
|
||
|
||
## 插件发布
|
||
|
||
在写了！
|