mirror of
https://github.com/zhamao-robot/zhamao-framework.git
synced 2026-07-21 15:45:36 +08:00
renew docs (#205)
This commit is contained in:
sunxyw
GitHub
@@ -1,4 +0,0 @@
|
||||
# 进阶开发
|
||||
在本章，下面的部分将详细说明一些具体的案例和自定义框架的操作。
|
||||
|
||||
> 更多进阶教程敬请期待....（或者你可以选择提 Issue 到框架 GitHub，有需求就写入文档）
|
||||
@@ -1,144 +0,0 @@
|
||||
# 接入 WebSocket 客户端
|
||||
|
||||
炸毛框架其实从本质上讲，就是一个 HTTP + WebSocket 服务器，所以框架也支持对接其他任何 HTTP 客户端和 WebSocket 客户端，实际上炸毛框架非常适合用 WebSocket 做在线的 IM 聊天通讯，也可以方便地进行 WS 通信。这里主要说明如何对接一个自定义的 WebSocket 客户端。
|
||||
|
||||
## 类型指定
|
||||
|
||||
由于 WebSocket 连接都具有同样的性质，没有状态，所以在建立 WebSocket 连接的时候，需要客户端表明自己的身份和类型。指定客户端连接类型的方式有两种：
|
||||
|
||||
- `GET` 参数传递，在连接的时候，加上 GET 参数 `type` 即可。比如 js 中 WebSocket 建立时地址写：`ws://127.0.0.1:20001/?type=foo`，这时传入的连接就是 `foo` 类型。
|
||||
- `Header` 传递，用户需要在建立连接时指定 HTTP 的头部信息 `X-Client-Role`，例如 `X-Client-Role: foo`，这时传入的连接就是 `foo` 类型。
|
||||
|
||||
以上两种方式，`Header` 方式比 `GET` 方式优先级要高，如果两者均没有指定，框架会将此连接当作 `default` 类型接入。
|
||||
|
||||
::: tip 提示
|
||||
|
||||
对于对接 OneBot 标准的机器人客户端，只要符合 OneBot 标准，即 `X-Client-Role` 会自动带上 `universal`、`qq` 等字样，就会自动标记为 `qq` 类型。
|
||||
|
||||
:::
|
||||
|
||||
## 逻辑编写
|
||||
|
||||
传入连接后，我们就能通过注解事件绑定来做我们自己想做的事情了！比如下方是传入类型为 foo 连接要做的事情
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace Module\Example;
|
||||
use ZM\Annotation\Swoole\OnOpenEvent;
|
||||
use ZM\Console\Console;
|
||||
use ZM\ConnectionManager\ConnectionObject;
|
||||
class Hello {
|
||||
/**
|
||||
* @OnOpenEvent("foo")
|
||||
*/
|
||||
public function onFooConnect(ConnectionObject $conn) {
|
||||
Console::info($conn->getName()." 已连接！");
|
||||
}
|
||||
```
|
||||
|
||||
以上作用就是在终端输出 `foo 已连接！` 这个提示的。关于 `ConnectionObject` 对象，见下方。
|
||||
|
||||
## WS 连接对象
|
||||
|
||||
对于每一个 WebSocket 连接，框架内都有一个专属的操作类，有获取类型名称、保存链接参数和属性以及获取文件标识符等功能。
|
||||
|
||||
### getFd()
|
||||
|
||||
获取文件标示符，用于发送消息、接收消息等。这个参数获取的 `fd` 是 Swoole 指定的，用于发送信息等。
|
||||
|
||||
```php
|
||||
$fd = $conn->getFd();
|
||||
server()->send($fd, "hello world");
|
||||
```
|
||||
|
||||
> WebSocket 是全双工的，所以发送和接收其实是互不干扰的，你可以不仅仅在 WebSocket 相关的上下文中，还可以比如在 HTTP 或者机器人上下文中给别的 WebSocket 客户端发请求。
|
||||
|
||||
### getName()
|
||||
|
||||
获取连接对象绑定的连接类型，例如上方提到的 `foo`、`default` 等。
|
||||
|
||||
```php
|
||||
Console::info("当前连接类型：".$conn->getName()); //当前连接类型：foo
|
||||
```
|
||||
|
||||
### setName()
|
||||
|
||||
改变连接对象绑定的连接类型，例如从 `foo` 改为 `bar`。
|
||||
|
||||
```php
|
||||
$s = $conn->getName(); // foo
|
||||
$conn->setName("bar");
|
||||
$s = $conn->getName(); // bar
|
||||
```
|
||||
|
||||
### getOptions()
|
||||
|
||||
获取此连接存储的所有参数，以数组形式。存储内容见下方 `setOption()`。
|
||||
|
||||
格式：`["参数1" => {参数1的值}, "参数2" => {参数2的值}]`
|
||||
|
||||
### getOption()
|
||||
|
||||
获取此连接存储的参数，获取指定名称的，此方法拥有一个参数 `$key`，指定即可获取。
|
||||
|
||||
如果没有对应参数，则返回 `null`。
|
||||
|
||||
我们在前面的机器人部分知道，框架主要是用于机器人的连接，那么机器人客户端在连接后，比如我们想知道这个机器人的 WS 连接对应的是哪个 QQ 号的机器人，我们就可以用 `getOption("connect_id")` 来获取。这个 `connect_id` 是 OneBot 标准的客户端接入后自动填入的一个参数。例如，我们想在机器人接入后打出接入机器人的 QQ 号：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @OnOpenEvent("qq")
|
||||
*/
|
||||
public function onQQConnect($conn) {
|
||||
Console::success("机器人 ".$conn->getOption("connect_id")." 已连接！"); // 机器人 123456 已连接！
|
||||
}
|
||||
```
|
||||
|
||||
### setOption()
|
||||
|
||||
设置连接存储的参数。参数：`setOption($key, $value)`。`$key` 限定为 `connect_id` 一种。（因为目前有了 LightCache，所以这里暂时不提供别的 key 设定）
|
||||
|
||||
```php
|
||||
$conn->setOption("connect_id", "asdasdasd"); // $value 最长长度为 29
|
||||
```
|
||||
|
||||
## 发送到 WebSocket 客户端
|
||||
|
||||
很简单，从上面获取到 `fd` 后使用下面的方式就可以了～
|
||||
|
||||
```php
|
||||
server()->push($conn->getFd(), "hello"); // 第二个为 string 类型的参数
|
||||
```
|
||||
|
||||
## 从客户端接收
|
||||
|
||||
接收消息必须从 `@OnMessageEvent` 注解事件下接收，使用上下文 `ctx()->getFrame()` 获取消息帧。
|
||||
|
||||
从这里获取的 `Frame` 对象，见 [Swoole 文档 - Frame](https://wiki.swoole.com/#/websocket_server?id=swoolewebsocketframe)。
|
||||
|
||||
Frame 对象有四个参数：
|
||||
|
||||
- `$frame->fd`：获取发来帧的 fd
|
||||
- `$frame->data`：数据本体
|
||||
- `$frame->opcode`：数据类型 int 值，见 [Swoole 文档 - 数据帧类型](https://wiki.swoole.com/#/websocket_server?id=%e6%95%b0%e6%8d%ae%e5%b8%a7%e7%b1%bb%e5%9e%8b)
|
||||
- `$frame->finish`：是否发送完毕，bool
|
||||
|
||||
下面以接收一个 json 字符串为例，并进行后续的解析：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @OnMessageEvent("foo")
|
||||
*/
|
||||
public function onMessage() {
|
||||
$frame = ctx()->getFrame();
|
||||
$json_str = $frame->data; // 假设传入的是 {"key1":"value1","k2":"v2"}
|
||||
$json = json_decode($json_str, true);
|
||||
Console::info("key1 的值是:" . $json["key1"]);
|
||||
}
|
||||
```
|
||||
|
||||
## 关闭连接
|
||||
|
||||
```php
|
||||
server()->close($conn->getFd());
|
||||
```
|
||||
@@ -1,136 +0,0 @@
|
||||
# 框架高级启动
|
||||
|
||||
## 框架下载方式
|
||||
|
||||
从前面的几章中，我们了解到框架有多种下载到本地的方式。
|
||||
|
||||
- Composer 依赖模式
|
||||
- Starter 从模板创建模式（等同于 Composer 模式）
|
||||
- 源码模式
|
||||
- Phar Composer 依赖模式
|
||||
- Phar 源码模式
|
||||
|
||||
### Composer 依赖模式
|
||||
|
||||
从 Composer 依赖加载框架是一种拉取框架的方式，这种方式的优点在于，你可以直观地感受到是如何使用框架从零开始一个完整的项目的过程。
|
||||
|
||||
从 Composer 依赖的启动步骤：
|
||||
|
||||
```bash
|
||||
mkdir my-bot # 新建一个空的文件夹
|
||||
cd my-bot/
|
||||
composer require zhamao/framework # 从 composer 拉取后会自动部署 autoload 和 composer.json 等内容
|
||||
|
||||
# 使用命令初始化框架
|
||||
vendor/bin/start init
|
||||
|
||||
# 启动框架
|
||||
vendor/bin/start server
|
||||
```
|
||||
|
||||
注意：使用 `init` 命令时，会给当前目录解压以下文件：
|
||||
|
||||
```php
|
||||
$extract_files = [
|
||||
"/config/global.php", // 全局配置文件
|
||||
"/.gitignore", // git 排除文件
|
||||
"/config/file_header.json", // HTTP 文件头
|
||||
"/config/console_color.json", // 终端颜色主题文件
|
||||
"/config/motd.txt", // 框架启动时自定义的 motd
|
||||
"/src/Module/Example/Hello.php", // 框架自带的示例模块
|
||||
"/src/Module/Middleware/TimerMiddleware.php", // 框架自带的函数运行时间监控中间件
|
||||
"/src/Custom/global_function.php" // 用户可在这里自定义编写自己的全局函数
|
||||
];
|
||||
```
|
||||
|
||||
经过 init 解压这些文件后，你的框架就能正常运行且开始编写代码了！
|
||||
|
||||
### Starter 模板模式
|
||||
|
||||
从模板新建其实原理和 Composer 依赖模式完全一样，只不过，这个过程是使用模板仓库新建的项目，使用 Composer 自带的 `create-project` 方式创建的。starter 也是一个 GitHub 项目，见 [地址](https://github.com/zhamao-robot/zhamao-framework-starter)。
|
||||
|
||||
```bash
|
||||
composer create-project zhamao/framework-starter my-bot/ # my-bot 是你自定义的文件夹名称，和上方相同
|
||||
cd my-bot
|
||||
vendor/bin/start server # 启动框架
|
||||
```
|
||||
|
||||
Starter 模式相当于直接从 GitHub 拉取 `zhamao-framework-starter` 项目，然后执行 `composer update`。
|
||||
|
||||
那和 Composer 依赖模式有什么区别呢？没区别！构建出来的框架和文件是一模一样的！使用 Composer 依赖模式，使用 `init` 命令后，文件会和 `zhamao-framework-starter` 仓库拉取回来的模板一模一样！（或者换句话说，这个仓库就是使用 `init` 命令生成的文件的）
|
||||
|
||||
那使用哪种好呢？看你自己！如果你想给你自己的已有项目套上炸毛框架，那么就推荐使用 Composer 依赖模式，如果是从 0 开始编写框架模块，则推荐使用模板模式。
|
||||
|
||||
### 源码模式
|
||||
|
||||
源码模式和以上两种方案都不一样，源码模式允许你对框架本身进行一系列修改，框架本体就可以直接运行。
|
||||
|
||||
Composer 依赖模式（以及模板模式）和源码模式的区别是：
|
||||
|
||||
- 依赖模式和模板模式是通过 library 方式引入框架的，框架本身会放在 composer 的 `vendor/` 目录下，从 composer 引入的 library 相当于子集，vendor 目录下的文件最好不要手动修改（应该都知道吧），所以框架本身也只是加载了进来。
|
||||
- 源码模式相当于直接从框架源码目录运行框架和模块，框架源码都在 `src/ZM` 目录下，默认的示例模块都在 `src/Module` 下，是同级目录。而此时的 `vendor/` 目录只包含了框架依赖的外部组件，例如注解解析器和 psysh 等。
|
||||
|
||||
源码模式可以方便地调试和修改框架本身，拉取方式很简单，用 `git clone` 或从 GitHub 下载最新版的源码包解压即可。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zhamao-robot/zhamao-framework.git
|
||||
cd zhamao-framework/
|
||||
bin/start server # 第一次运行时会提示一个“框架源码模式需要在autoload文件中添加Module目录为自动加载”
|
||||
composer update # 更新 autoload 文件，应用刚才上一步添加的 `src/Module` 文件夹下的模块自动加载
|
||||
bin/start server # 通过源码模式启动框架
|
||||
```
|
||||
|
||||
## 框架启动参数
|
||||
|
||||
框架启动时可以根据实际情况指定启动参数。
|
||||
|
||||
- `--debug-mode`：启用调试模式，调试模式的作用是关闭一键协程化和终端交互，减少 Swoole 本身对代码逻辑的干扰（比如执行 `shell_exec()` 报错的话可以开启这个进行调试）。
|
||||
- `--log-{mode}`：设置 log 等级。支持 `--log-debug`，`--log-verbose`，`--log-info`，`--log-warning`，`--log-error`。
|
||||
- `--log-theme`：设置终端信息的主题。这个选项适用于多种终端信息显示的兼容，例如白色终端和不支持颜色的终端。详见 [Console - 主题设置](/component/console/#_2)。
|
||||
- `--disable-coroutine`：关闭一键协程化。
|
||||
- `--remote-terminal`：开启 nc 远程终端，配置文件使用全局中的 `remote_terminal` 项。也可以在全局配置中常开启（status 设置为 true）。
|
||||
- `--daemon`：以守护进程方式运行框架，此参数将直接在输出 motd 后将进程挂到 init 下运行，后台常驻。
|
||||
- `--watch`：监控 `src/` 目录下的文件变化，有变化则自动重新载入代码。开启监控需要安装 PHP 扩展：inotify。使用 pecl 就可以安装：`pecl install inotify`。（注：不支持 WSL 和 macOS）
|
||||
- `--env`：设置运行环境，设置运行环境后将优先加载指定环境的配置文件，支持 `--env=production`，`--env=staging`，`--env=development`，见 [基本配置](/guide/basic-config/#_2)。
|
||||
- `--worker-num`：指定运行的工作进程数量（并不是越多越好，框架默认为 CPU 核心数），例如 `--worker-num=8`。
|
||||
- `--task-worker-num`：启用 TaskWorker 进程并指定数量。
|
||||
- `--show-php-ver`：在启动时显示 Swoole 和 PHP 的版本。
|
||||
|
||||
## 守护进程操作命令
|
||||
|
||||
守护进程在 2.2.0 版本开始，可以使用命令行快速操作，如重启、停止、查看状态等。
|
||||
|
||||
注意，这里的守护进程操作命令是指 **使用 `--daemon` 方式启动的框架**，如使用 Docker、screen、tmux、systemd 等方式挂后台跑则此命令不可用！
|
||||
|
||||
```bash
|
||||
vendor/bin/start daemon:status # 查看守护进程的状态
|
||||
vendor/bin/start daemon:reload # 重载框架
|
||||
vendor/bin/start daemon:stop # 停止运行守护进程的框架
|
||||
```
|
||||
|
||||
## 独立启动其他组件
|
||||
|
||||
框架默认不止启动框架的 `server` 命令，还有 `init` 命令和 `simple-http-server` 命令。`init` 命令在上方 Composer 依赖模式中提到过，就是初始化各个文件的。
|
||||
|
||||
### 独立 HTTP 文件服务器
|
||||
|
||||
如果你只需要一个静态文件服务器，类似 Nginx，那么框架也支持。
|
||||
|
||||
```bash
|
||||
vendor/bin/start simple-http-server your-web-dir/ --host=0.0.0.0 --port=8080
|
||||
```
|
||||
|
||||
- `your-web-dir` 是必填的参数。
|
||||
- `--host` 和 `--port` 是可选参数，如果不填，则默认使用 `global.php` 配置文件中的配置。
|
||||
|
||||
### 检查配置是否更新
|
||||
|
||||
默认情况下（非源码模式），你可以使用命令 `vendor/bin/start check:config` 来检查你的配置文件是否需要更新部分段落。
|
||||
|
||||
### systemd 配置文件生成器
|
||||
|
||||
框架支持生成 systemd 配置文件 `zhamao.service`，生成后将文件放入 `/etc/systemd/system` 后输入 `systemctl enable zhamao.service` 即可。
|
||||
|
||||
命令：`vendor/bin/start systemd:generate`
|
||||
|
||||
注意，systemd 启动的守护进程模式和使用参数 `--daemon` 不一样，请勿同时混用，直接使用上述命令生成的配置文件即可正常使用！
|
||||
@@ -1,229 +0,0 @@
|
||||
# 编写管理员专属功能
|
||||
|
||||
众所周知，如果大家使用炸毛框架来开发聊天机器人的话，会比较方便。但是有些地方你一定会感觉还是欠缺了点，比如下面这样，你想编写一个只能由机器人管理员，也就是你自己，才能触发的功能：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @CQCommand(match="禁言",message_type="group")
|
||||
*/
|
||||
public function banSomeone() {
|
||||
$r1 = ctx()->getNextArg("请输入禁言的人或at他");
|
||||
$r2 = ctx()->getFullArg("请输入禁言的时间（秒）");
|
||||
$cq = CQ::getCQ($r1);
|
||||
if ($cq !== null) {
|
||||
if ($cq["type"] != "at") return "请at或者输入正确的QQ号！";
|
||||
$r1 = $cq["params"]["qq"];
|
||||
}
|
||||
// 群内禁言用户
|
||||
ctx()->getRobot()->setGroupBan(ctx()->getGroupId(), $r1, $r2);
|
||||
return "禁言成功！";
|
||||
}
|
||||
```
|
||||
|
||||
这时候，如果只是自己有绝对的权利，可以将自己的 QQ 号写死在注解 `@CQCommand` 中，并限定 `user_id`（假设我的 QQ 号码为 123456）：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @CQCommand(match="禁言",message_type="group",user_id=123456)
|
||||
*/
|
||||
```
|
||||
|
||||
但是，随着时间的推移，你的机器人伙伴群可能越来越大，这个命令可能不止需要绝对的你来使用，你还要将机器人的部分权利下发给更多的伙伴，怎么办呢？注解里面只能写死的。
|
||||
|
||||
答案很简单，这时候我们就需要用到框架提供的中间件（Middleware）。中间件说白了就是在事件执行前、后、过程中抛出的异常对其进行阻断和插入代码，比如我们上方在触发禁言这个注解事件前首先要判断执行这个命令的是不是钦定的管理员。
|
||||
|
||||
## 第一步：定义中间件
|
||||
|
||||
首先，我们需要定义一个中间件。在框架默认提供的脚手架中，包含了一个叫 `TimerMiddleware.php` 的示例中间件，这个示例中间件的目的是非常简单的，就是判断这个注解事件运行了多长时间。假设你有一个机器人功能，这个功能下的代码需要执行很长时间，可以使用这一注解轻松将事件执行的时间打印到终端上。
|
||||
|
||||
关于中间件的有关说明，见 [中间件](/event/middleware)。
|
||||
|
||||
下面我们假设你已经阅读过中间件注解的文档了，我们着手编写一个判断指令执行者是否是指定的管理员 QQ 的中间件。为了省事和让大家方便地复现，我先在脚手架下的目录 `src/Module/Middleware/` 下新建 PHP 类文件 `AdminMiddleware.php`（和 `TimerMiddleware.php` 在同一个目录）。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Module\Middleware;
|
||||
|
||||
use ZM\Annotation\Http\HandleBefore;
|
||||
use ZM\Annotation\Http\MiddlewareClass;
|
||||
use ZM\Exception\ZMException;
|
||||
use ZM\Http\MiddlewareInterface;
|
||||
use ZM\Store\LightCache;
|
||||
|
||||
/**
|
||||
* Class AdminMiddleware
|
||||
* 示例中间件：用于动态管理一些管理员指令的中间件
|
||||
* @package Module\Middleware
|
||||
* @MiddlewareClass("admin")
|
||||
*/
|
||||
class AdminMiddleware implements MiddlewareInterface
|
||||
{
|
||||
/**
|
||||
* @HandleBefore()
|
||||
* @return bool
|
||||
* @throws ZMException
|
||||
*/
|
||||
public function onBefore(): bool {
|
||||
$r = ctx()->getUserId(); // 从上下文获取发消息的用户 QQ
|
||||
$admin_list = LightCache::get("admin_list") ?? []; // 从轻量缓存获取管理员列表
|
||||
return in_array($r, $admin_list); // 返回这个 QQ 是否在管理员列表中
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中，`@MiddlewareClass("admin")` 的意思是，定义这个类为名字叫 `admin` 的中间件，同时，所有中间件的类**必须**带上 `implements MiddlewareInterface`，统一接口形式。
|
||||
|
||||
`@HandleBefore()` 代表的是，这个类下的这个函数（onBefore）被标注为这个中间件的 `onBefore` 事件，也就是说，如果有别的注解事件插入了这个 `admin` 中间件，那么执行对应注解事件前都要执行一下 `@HandleBefore` 所绑定的这个函数。而这个绑定的函数只能返回 `bool` 类型的值哦！
|
||||
|
||||
## 第二步：使用中间件
|
||||
|
||||
使用中间件很简单，在需要阻断的注解事件绑定的函数上再加一个注解就好了！我们以上方的禁言例子说明：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @Middleware("admin")
|
||||
* @CQCommand(match="禁言",message_type="group")
|
||||
*/
|
||||
```
|
||||
|
||||
<chat-box :my-chats="[
|
||||
{type:0,content:'禁言 1234567 600'},
|
||||
{type:1,content:'禁言成功！'},
|
||||
{type:2,content:'假设我不在管理员名单里'},
|
||||
{type:0,content:'禁言 1234567 900'},
|
||||
{type:2,content:'机器人没有回复，因为中间件返回了 false，不继续执行'},
|
||||
]"></chat-box>
|
||||
|
||||
而这时候有朋友又要问了，如果我有一系列管理员命令，假设都在一个叫 `AdminFunc.php` 的模块类里，我是不是还得一个一个地给注解事件写 `@Middleware("admin")` 呢？当然不需要！如果你这个类所有的注解事件都是机器人的聊天事件（`@CQCommand`，`@CQMessage`）的话，可以直接给类注解这个中间件，效果等同于给每一个函数写一次中间件注解。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Module\Example;
|
||||
|
||||
use ZM\Annotation\Http\Middleware;
|
||||
|
||||
/**
|
||||
* Class AdminFunc
|
||||
* @package Module\Example
|
||||
* @Middleware("admin")
|
||||
*/
|
||||
class AdminFunc
|
||||
{
|
||||
// ...这里是你的一堆注解事件的函数
|
||||
}
|
||||
```
|
||||
|
||||
## 第三步：补全代码
|
||||
|
||||
上面我们讲到了，中间件里面使用了 `LightCache` 轻量缓存来储存临时的管理员列表，那么我们将这部分的代码完善吧！
|
||||
|
||||
**src/Module/Example/AdminFunc.php**
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Module\Example;
|
||||
|
||||
use ZM\Annotation\CQ\CQCommand;
|
||||
use ZM\Annotation\Http\Middleware;
|
||||
use ZM\API\CQ;
|
||||
|
||||
/**
|
||||
* Class AdminFunc
|
||||
* @package Module\Example
|
||||
* @Middleware("admin")
|
||||
*/
|
||||
class AdminFunc
|
||||
{
|
||||
/**
|
||||
* @CQCommand(match="禁言",message_type="group")
|
||||
*/
|
||||
public function banSomeone() {
|
||||
$r1 = ctx()->getNextArg("请输入禁言的人或at他");
|
||||
$r2 = ctx()->getFullArg("请输入禁言的时间（秒）");
|
||||
$cq = CQ::getCQ($r1);
|
||||
if ($cq !== null) {
|
||||
if ($cq["type"] != "at") return "请at或者输入正确的QQ号！";
|
||||
$r1 = $cq["params"]["qq"];
|
||||
}
|
||||
// 群内禁言用户
|
||||
ctx()->getRobot()->setGroupBan(ctx()->getGroupId(), $r1, $r2);
|
||||
return "禁言成功！";
|
||||
}
|
||||
|
||||
/**
|
||||
* @CQCommand(match="解除禁言",message_type="group")
|
||||
*/
|
||||
public function unbanSomeone() {
|
||||
$r1 = ctx()->getNextArg("请输入禁言的人或at他");
|
||||
$cq = CQ::getCQ($r1);
|
||||
if ($cq !== null) {
|
||||
if ($cq["type"] != "at") return "请at或者输入正确的QQ号！";
|
||||
$r1 = $cq["params"]["qq"];
|
||||
}
|
||||
// 群内禁言用户
|
||||
ctx()->getRobot()->setGroupBan(ctx()->getGroupId(), $r1, 0);
|
||||
return "解除禁言成功！";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**src/Module/Example/AdminManager.php**
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Module\Example;
|
||||
|
||||
use ZM\Annotation\CQ\CQCommand;
|
||||
use ZM\Annotation\Http\Middleware;
|
||||
use ZM\Annotation\Swoole\OnStart;
|
||||
use ZM\Store\LightCache;
|
||||
use ZM\Store\Lock\SpinLock;
|
||||
|
||||
class AdminManager
|
||||
{
|
||||
/**
|
||||
* @OnStart()
|
||||
*/
|
||||
public function onStart() {
|
||||
if (!LightCache::isset("admin_list")) { //一次性代码，首次执行才会执行if
|
||||
LightCache::set("admin_list", [ // 框架启动时初始化管理员列表
|
||||
"123456",
|
||||
"234567"
|
||||
], -2); // 这里用 -2 的原因是将这一列表持久化保存，避免关闭框架后丢失
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @CQCommand(match="添加管理员")
|
||||
* @Middleware("admin")
|
||||
*/
|
||||
public function addAdmin() { //只有管理员才能添加管理员
|
||||
$qq = ctx()->getNextArg("请输入要添加管理员的QQ(qq号码，不可at）");
|
||||
SpinLock::lock("admin_list"); //如果是多进程模式的话需要加锁
|
||||
$ls = LightCache::get("admin_list");
|
||||
if (!in_array($qq, $ls)) $ls[] = $qq;
|
||||
LightCache::set("admin_list", $ls, -2);
|
||||
SpinLock::unlock("admin_list"); //如果是多进程模式的话需要加锁
|
||||
return "成功添加 $qq 到管理员列表！";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<chat-box :my-chats="[
|
||||
{type:2,content:'现在我是 123456'},
|
||||
{type:0,content:'禁言 13579 60'},
|
||||
{type:1,content:'禁言成功！'},
|
||||
{type:0,content:'解除禁言 13579'},
|
||||
{type:1,content:'解除禁言成功！'},
|
||||
{type:0,content:'添加管理员 98765'},
|
||||
{type:1,content:'成功添加 98765 到管理员列表！'},
|
||||
{type:2,content:'现在我是98765'},
|
||||
{type:0,content:'禁言 13579'},
|
||||
{type:1,content:'请输入禁言的时间（秒）'},
|
||||
{type:0,content:'120'},
|
||||
{type:1,content:'禁言成功！'},
|
||||
]"></chat-box>
|
||||
@@ -1,85 +0,0 @@
|
||||
# 接入青云客智能聊天机器人API
|
||||
|
||||
作为一个群聊机器人，懂得聊天会让机器人增色不少，在大数据和 AI 热潮下，不少厂商都研发了自己的智能聊天 API，例如图灵机器人、腾讯智能闲聊等，大厂开发的 API 自然有着他人无可比拟的健壮性和可靠性，但是随之而来不菲的价格显然并不适合大众开发者。这时候一个免费、可用的智能聊天 API 便非常重要了，其中，青云客是少有的完全免费、无需注册的智能聊天 API，提供了包括智能聊天、歌词、天气查询、笑话等多种有用功能，且接入简单，非常适合新手开发者尝试。
|
||||
|
||||
## 结果演示
|
||||
|
||||
|
||||
|
||||
## 阅读接入指南
|
||||
|
||||
不管接入何种服务，阅读接入指南永远都是最优先、最重要的一步，所幸青云客的接入指南十分简单，简单来说归纳为以下：
|
||||
* 请求：GET https://api.qingyunke.com/api.php
|
||||
* 参数：
|
||||
* * `key` 目前固定为 `free`
|
||||
* * `appid` 目前固定为 `0`
|
||||
* * `msg` 关键词，需要经过 `urlencode`
|
||||
* 注意：返回结果中 `{br}` 代表换行
|
||||
|
||||
## 逻辑编写
|
||||
|
||||
阅读过后，我们便可以进行主要的编写工作了。
|
||||
|
||||
首先，为了机器人的性能考虑，也为了避免过分打扰群聊的聊天，我们希望机器人只有在主动触发（@AT 或者 关键词等）时才会进行智能聊天。
|
||||
|
||||
对于关键词匹配，我们可以使用 `@CQCommand`：
|
||||
|
||||
```php
|
||||
/**
|
||||
* 智能聊天
|
||||
*
|
||||
* @CQCommand(start_with="机器人")
|
||||
*/
|
||||
public function chat()
|
||||
{
|
||||
// 替换掉机器人前缀，并获取消息内容
|
||||
$msg = ctx()->getMessage();
|
||||
$msg = str_replace('机器人', '', $msg);
|
||||
if (empty(trim($msg))) {
|
||||
$msg = ctx()->getFullArg('怎么了？');
|
||||
}
|
||||
|
||||
Console::info('正在获取智能聊天回复：' . $msg);
|
||||
// 请求 API 获取回复
|
||||
$raw_data = file_get_contents('https://api.qingyunke.com/api.php?key=free&appid=0&msg=' . urlencode($msg));
|
||||
try {
|
||||
$data = json_decode($raw_data, true, 512, JSON_THROW_ON_ERROR);
|
||||
} catch (\Exception $e) {
|
||||
$data = ['content' => '机器人解析异常，请稍后再试'];
|
||||
Console::warning('无法获取智能聊天回复：' . $e->getMessage());
|
||||
}
|
||||
if ($data['result'] !== 0) {
|
||||
$data = ['content' => '机器人服务异常，请稍后再试'];
|
||||
Console::warning('无法获取智能聊天回复：' . $raw_data);
|
||||
}
|
||||
Console::info('获取智能聊天回复完成：' . $data['content']);
|
||||
// 将 {br} 替换为换行
|
||||
$data['content'] = strtr($data['content'], ['{br}' => "\n"]);
|
||||
return $data['content'];
|
||||
}
|
||||
```
|
||||
|
||||
这样我们的命令便只会在用户发送以`机器人`开头的消息时才会触发。
|
||||
|
||||
同时，我们也希望在 @AT 机器人时也进行回复，此时可以使用 `@CQBefore` 方法进行折中：
|
||||
|
||||
```php
|
||||
/**
|
||||
* 将 AT 机器人的消息交由智能聊天处理
|
||||
*
|
||||
* @CQBefore("message")
|
||||
*/
|
||||
public function changeAt(): bool
|
||||
{
|
||||
// 判断此条消息是否 AT 了机器人
|
||||
if (MessageUtil::isAtMe(ctx()->getMessage(), ctx()->getRobotId())) {
|
||||
// 将 AT 本身从消息中去掉
|
||||
$msg = str_replace(CQ::at(ctx()->getRobotId()), '', ctx()->getMessage());
|
||||
ctx()->setMessage('机器人' . trim($msg));
|
||||
// 调用智能聊天
|
||||
ctx()->reply($this->chat());
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
@@ -1,113 +0,0 @@
|
||||
# 基于词性分析和魅族天气的天气查询机器人
|
||||
|
||||
本文将基于 [`jieba-php`](https://github.com/fukuball/jieba-php) 中文分词库以及 [魅族天气 API](https://github.com/shichunlei/-Api/blob/master/MeizuWeather.md) 开发一个天气查询机器人。
|
||||
|
||||
## 结果演示
|
||||
|
||||
|
||||
尾部的随机表情并非本教程的一部分。
|
||||
|
||||
## 逻辑编写
|
||||
|
||||
[jieba-php](https://github.com/fukuball/jieba-php) 是目前比较好用的中文分词库，虽然最近的维护并不活跃，但已足够我们的需求：
|
||||
|
||||
```shell
|
||||
composer require fukuball/jieba-php:dev-master
|
||||
```
|
||||
|
||||
以下代码使用了本文作者自行编写的天气查询库，需要进行引入：
|
||||
|
||||
```shell
|
||||
composer require sunxyw/weather
|
||||
```
|
||||
|
||||
您也可以将以下代码自行改写为直接调用魅族天气 API，详情请参阅[魅族天气 API 文档](https://github.com/shichunlei/-Api/blob/master/MeizuWeather.md)。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Bot\Module\SmartChat;
|
||||
|
||||
use Fukuball\Jieba\Jieba;
|
||||
use Fukuball\Jieba\Posseg;
|
||||
use Sunxyw\Weather\Weather;
|
||||
use ZM\Annotation\CQ\CQCommand;
|
||||
use ZM\Console\Console;
|
||||
|
||||
class WeatherReport
|
||||
{
|
||||
/**
|
||||
* 加载字典
|
||||
*
|
||||
* @OnStart(worker_id=-1)
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function initDictionary(): void
|
||||
{
|
||||
// 分词以及词性分析需要载入字典到内存
|
||||
ini_set('memory_limit', '600M');
|
||||
Jieba::init(['dict' => 'small']);
|
||||
Posseg::init();
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询天气
|
||||
*
|
||||
* @CQCommand(keyword="天气")
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function cmdQueryWeather(): string
|
||||
{
|
||||
// 分词并进行词性分析
|
||||
$seg_list = Posseg::cut(ctx()->getMessage());
|
||||
$tags = array_column($seg_list, 'tag');
|
||||
// 找出词性为 ns（地名）的单词
|
||||
$location_index = array_search('ns', $tags, true);
|
||||
$location = $seg_list[$location_index]['word'];
|
||||
|
||||
// 此处引入了本文作者自己写的天气库
|
||||
$w = new Weather();
|
||||
try {
|
||||
$report = $w->getWeather($location);
|
||||
} catch (\InvalidArgumentException) {
|
||||
return '城市输入错误';
|
||||
} catch (\JsonException $e) {
|
||||
Console::warning("天气查询失败：{$e->getMessage()}");
|
||||
return '天气查询失败';
|
||||
}
|
||||
|
||||
$template = <<<EOF
|
||||
%s天气：%s
|
||||
温度：%s℃
|
||||
湿度：%s%%
|
||||
风向：%s %s
|
||||
空气质量：%s
|
||||
------------------------------
|
||||
未来三天天气：
|
||||
%s：%s，日间%s℃，夜间%s℃，吹%s %s
|
||||
%s：%s，日间%s℃，夜间%s℃，吹%s %s
|
||||
%s：%s，日间%s℃，夜间%s℃，吹%s %s
|
||||
EOF;
|
||||
$args = [
|
||||
$report->getCity(),
|
||||
$report->getRealtime()['weather'],
|
||||
$report->getRealtime()['temperature'],
|
||||
$report->getRealtime()['humidity'],
|
||||
$report->getRealtime()['wind_direction'],
|
||||
$report->getRealtime()['wind_speed'],
|
||||
$report->getRealtime()['air_quality'],
|
||||
];
|
||||
foreach (array_slice($report->getForecastDaily(), 0, 3) as $forecast) {
|
||||
$args[] = $forecast['date'];
|
||||
$args[] = $forecast['weather'];
|
||||
$args[] = $forecast['temperature']['day'];
|
||||
$args[] = $forecast['temperature']['night'];
|
||||
$args[] = $forecast['wind_direction'];
|
||||
$args[] = $forecast['wind_speed'];
|
||||
}
|
||||
return vsprintf($template, ...$args);
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,5 +0,0 @@
|
||||
# 框架剖析
|
||||
|
||||
## 框架运行总结构图
|
||||
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
# 内部类文件手册
|
||||
|
||||
这个章节写明了在框架使用过程中可能涉及到的框架内部或 Swoole、其他 composer 依赖组件的内部类，这里会根据类的命名空间一一说明。
|
||||
|
||||
## Swoole\Http\Request
|
||||
|
||||
此类是 Swoole 内部的一个类，一般在收到 HTTP 请求时，在 `@RequestMapping` 或 `@OnRequestEvent()` 两个注解下可用，用作获取 GET、POST参数，上传到后端的文件、Cookies 等。详见 [Swoole 文档 - Request](http://wiki.swoole.com/#/http_server?id=httprequest) 。
|
||||
|
||||
### 属性
|
||||
|
||||
- `$fd`：获取当前连接的文件描述符 ID。
|
||||
- `$header`：`HTTP` 请求的头部信息。类型为数组，所有 `key` 均为小写。
|
||||
- `$server`：`HTTP` 请求相关的服务器信息。
|
||||
- `$cookie`：获取 Cookies。
|
||||
- `$get`：获取 GET 参数。
|
||||
- `$post`：获取 POST 参数。
|
||||
- `$files`：获取上传的文件信息
|
||||
|
||||
### 方法
|
||||
|
||||
- `rawContent()`：获取 POST 包原始二进制内容，相当于原生 PHP 的 ` file_get_contents("php://input");` 。
|
||||
- `getData()`：获取完整的原始 `Http` 请求报文。包括 `Http Header` 和 `Http Body`
|
||||
|
||||
### 示例
|
||||
|
||||
```php
|
||||
TODO：先放一放。
|
||||
```
|
||||
|
||||
## ZM\Entity\MatchObject
|
||||
|
||||
此类是调用方法 `MessageUtil::matchCommand()` 返回的对象体，含有匹配成功与否和匹配到的注解相关的信息。
|
||||
|
||||
### 属性
|
||||
|
||||
- `$match`：`bool` 类型，返回匹配是否成功
|
||||
- `$object`：`CQCommand` 注解类，如果匹配成功则返回对应的 `@CQCommand` 信息
|
||||
- `match`：`array` 类型，如果匹配成功则返回匹配到的参数
|
||||
|
||||
```php
|
||||
// 假设我有一个注解事件 @CQCommand(match="你好")，绑定的函数是 \Module\Example\Hello 下的 hello123()
|
||||
|
||||
$obj = MessageUtil::matchCommand("你好 我叫顺溜 我今年二十八", ctx()->getData());
|
||||
/* 以下是返回信息，仅供参考
|
||||
$obj->match ==> true
|
||||
$obj->object ==> \ZM\Annotation\CQ\CQCommand: (
|
||||
match: "你好",
|
||||
pattern: "",
|
||||
regex: "",
|
||||
start_with: "",
|
||||
end_with: "",
|
||||
keyword: "",
|
||||
alias: [],
|
||||
message_type: "",
|
||||
user_id: 0,
|
||||
group_id: 0,
|
||||
discuss_id: 0,
|
||||
level: 20,
|
||||
method: "hello123",
|
||||
class: \Module\Example\Hello::class
|
||||
)
|
||||
$obj->match ==> [
|
||||
"我叫顺溜",
|
||||
"我今年二十八"
|
||||
]
|
||||
*/
|
||||
```
|
||||
@@ -1,3 +0,0 @@
|
||||
# 手动部署环境教程
|
||||
|
||||
TODO: 还没写
|
||||
@@ -1,72 +0,0 @@
|
||||
# 框架多进程
|
||||
|
||||
首先对于多进程概念，对于传统 PHP 程序员可能比较陌生，唯一接触到的地方可能就是 php-fpm 等一些方式处理时间长的请求时开进程去执行。关于多进程，我觉得廖雪峰的 Python 多进程这段讲的不错：
|
||||
|
||||
> Unix/Linux 操作系统提供了一个`fork()`系统调用，它非常特殊。普通的函数调用，调用一次，返回一次，但是`fork()`调用一次，返回两次，因为操作系统自动把当前进程（称为父进程）复制了一份（称为子进程），然后，分别在父进程和子进程内返回。
|
||||
|
||||
这里面的重点在于，多进程的创建，是父进程的复制，然后两个进程接下来运行的代码和存的内容就分道扬镳了。
|
||||
|
||||
PHP 也是如此，框架的多进程又是怎么一回事呢？为什么要采用多进程呢？
|
||||
|
||||
## 作用
|
||||
|
||||
使用过框架的你一定知道，框架是以命令行方式运行 PHP 的，而命令行方式运行 PHP，就代表要常驻内存，就像 Python、Node.js 一样。而默认情况下，比如 Python 的 Flask 为单线程单进程模式，也就是说同时只能处理一个 Web 请求。但大部分情况下，比如 Node.js，提供的都是异步 I/O，这也就是说明它在 Web 处理请求上，可同时承接的 I/O 密集型请求会更多一些，这样在对一般的 Web 应用中 I/O 密集型场景非常有用，而且往往只需要单进程也可以承载上万的并发请求。
|
||||
|
||||
在炸毛框架中，因为框架基于 Swoole 构建，所以天然支持协程，而协程就是针对 I/O 操作进行一个调度，类似异步的 Node.js，所以针对项目中存在太多的 SQL 语句执行、文件读写的话，炸毛框架直接上手，无需做任何修改，也可以达到很好的性能。
|
||||
|
||||
**但是**，CPU 密集型的应用怎么办呢？假设我的 Web 应用有大量的排序、md5 运算怎么办呢？这样的阻塞，假设是一个超级大的 for 循环或者是要执行很长时间的 while 循环，CPU 一直在被占用。多进程就是针对 CPU 密集型的应用说 yes 的一个方案。
|
||||
|
||||
|
||||
|
||||
我们假设现在有 3 个请求同时访问，也就是说上面的流程需要执行 3 遍。而如果我们只有一个进程的话，最后一个请求需要等待的时间为 `2*3+5*3=21` 秒，非常耗时。
|
||||
|
||||
而如果有两个进程处理 3 个请求，则最后一个完成的请求就缩短了，`2+5+2+5=14` 秒。
|
||||
|
||||
|
||||
|
||||
所以如果要充分利用你的服务器或者个人电脑的多核 CPU 资源，就要设置多个进程来处理。一个进程只能在一个 CPU 上运行，而设置了多进程后，就可以让多核 CPU 充分运行多个进程，所以我们给框架设置多进程的推荐数值为等同于 CPU 的核心数。
|
||||
|
||||
## 为什么不是多线程
|
||||
|
||||
因为众所周知，PHP 对线程的支持比较不好，而 ZTS 版本的 PHP 又会影响传统的 Web 端 PHP 的性能，再加上 Linux 对线程的切换效率和多进程切换的效率差不多，多线程容易造成数据读写不安全等问题，故 Swoole 使用的是多进程模型。
|
||||
|
||||
## 框架进程模型
|
||||
|
||||
|
||||
|
||||
上图中，横向的时间片可以理解为并行执行，这些操作在多个 CPU 内可能同时在执行。
|
||||
|
||||
## 进程间隔离
|
||||
|
||||
众所周知，进程是程序在操作系统中的一个边界，和自己有关的一切变量、内容和代码都在自己的进程内，不同进程之间如果不使用管道等方式，是不可以互相访问的。而加上开始描述的，创建子进程是一个复制自身的过程，所以也就会有如下图的情况：
|
||||
|
||||
|
||||
|
||||
我们以静态类为例，设置一个进程中的全局变量。这里就会出现，同一个静态变量在多个进程中完全不同的值的结果。此后，我们将会在 Worker 进程中执行用户的代码，如果设置 Worker 数量仅为 1 的话，那么就简单许多了，你还是可以使用全局变量或静态类来存储你想要的内容而不用担心这种多个进程变量隔离的情况（因为用户的 Web 请求处理的代码只会在一个 Worker 进程中执行）。如果像上图一样设置了多个 Worker，则用户过来的比如 HTTP 请求就有可能出现在不同的 Worker 进程中，给全局变量设值就一定会造成不同步的问题。这时我们就不可以使用全局变量做数据同步（注意，我说的是数据同步）。
|
||||
|
||||
## 跨进程同步
|
||||
|
||||
跨进程同步方案中，框架给出了很多种解决方案。
|
||||
|
||||
- MySQL 数据库
|
||||
- Redis
|
||||
- LightCache 轻量缓存（共享内存）
|
||||
- WorkerCache 大缓存
|
||||
- ZMAtomic 跨进程原子计数器
|
||||
|
||||
下面的表格我将列出下方的特点和各自的优缺点：
|
||||
|
||||
| 类型 | 用途 | 优点 | 缺点 |
|
||||
| ----------- | --------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
|
||||
| MySQL | 大型的传统的关系式数据都可以用数据库，你懂的 | 就是数据库的优点 | 和数据库不在同一台服务器的话网络延迟会较大，数据获取效率不高 |
|
||||
| Redis | 传统的 key-value 数据库 | 数据无同步等问题，性能高 | 有网络通信延迟 |
|
||||
| LightCache | 框架封装的跨进程的 key-value 存储模型 | 性能强悍，无 I/O 和网络通信 | 需要提前分配最大内存大小，最大单个值长度大小，不灵活 |
|
||||
| WorkerCache | 框架封装的基于进程的 key-value 存储模型，类似 Redis | 无需提前分配最大内存大小，受限于 PHP memory_limit | 见 WorkerCache 的说明 |
|
||||
|
||||
::: tip WorkerCache 的说明
|
||||
|
||||
对于 WorkerCache 来说，其实是比较特殊的进程间通信。具体来说就是，WorkerCache 的原理就是将变量指定的存到一个进程中，如果是本进程读写的话直接相当于改一下全局变量，如果是其他进程读写的话，则依靠进程间通信。
|
||||
|
||||
所以缺点也显而易见，如果使用过程中不是命中了 WorkerCache 存储所在的进程的话，则一直会使用进程间通信，影响一定的效率。
|
||||
|
||||
:::
|
||||
@@ -1,3 +0,0 @@
|
||||
# PHP 环境高级部署方式
|
||||
|
||||
TODO: 留个坑。
|
||||
@@ -1,3 +0,0 @@
|
||||
# 使用 TaskWorker 进程处理密集运算
|
||||
|
||||
> TODO: 新开个坑，有时间补上。（__填坑标记__）
|
||||
Reference in New Issue
Block a user