update to build 417

2026-07-21 23:55:35 +08:00 · 2021-09-01 14:14:00 +08:00
parent a13c4628f5
commit 229778ebf9
50 changed files with 1376 additions and 207 deletions
--- a/docs/component/bot/robot-api.md
+++ b/docs/component/bot/robot-api.md
@@ -1,26 +1,29 @@
-# 机器人 API（ZMRobot）
+# 机器人 API（OneBotV11）

-ZMRobot 类是封装好的 OneBot 标准的 API 接口调用类，可以在机器人连接后通过连接或者机器人 QQ 号获取对象并调用接口（如发送群消息、获取群列表等操作）。
+OneBotV11 类是封装好的 OneBot 标准的 API 接口调用类，可以在机器人连接后通过连接或者机器人 QQ 号获取对象并调用接口（如发送群消息、获取群列表等操作）。

-| 属性项   | 属性值           | 备注                           |
-| -------- | ---------------- | ------------------------------ |
-| 名称     | ZMRobot          |                                |
-| 类型     | 实例化类         | `$r = new ZMRobot($conn)`      |
-| 命名空间 | `ZM\API\ZMRobot` | 使用前先 `use ZM\API\ZMRobot;` |
+| 属性项   | 属性值             | 备注                             |
+| -------- | ------------------ | -------------------------------- |
+| 名称     | OneBotV11          |                                  |
+| 类型     | 实例化类           | `$r = new OneBotV11($conn)`      |
+| 命名空间 | `ZM\API\OneBotV11` | 使用前先 `use ZM\API\OneBotV11;` |
+| 别名     | `ZM\API\ZMRobot`   | 此类目前是 `extends OneBotV11`   |
+
+> 你也可以继续使用 2.5 版本之前的别名类 `ZMRobot`，但未来框架将会优先兼容 OneBot V12 版本的协议，可能会造成更新问题，建议切换为 OneBotV11 类。

 ## 属性

 对象属性方法是对 API 的调整，例如是否以 `_async`、`_rate_limited` 后缀发送 API、设置协程返回还是异步返回结果等。

-### ZMRobot::API_NORMAL
+### OneBotV11::API_NORMAL

 以默认（无后缀）方式请求 API。

-### ZMRobot::API_ASYNC
+### OneBotV11::API_ASYNC

 以后缀 `_async` 方式异步请求 API。

-### ZMRobot::API_RATE_LIMITED
+### OneBotV11::API_RATE_LIMITED

 以后缀 `_rate_limited` 方式请求 API。

@@ -30,7 +33,7 @@ ZMRobot 类是封装好的 OneBot 标准的 API 接口调用类，可以在机

 设置后缀。目前支持 `_async`、`_rate_limited`。

- **prefix**: `int` `默认:API_NORMAL`，可选 `ZMRobot::API_NORMAL`、`ZMRobot::API_ASYNC`、`ZMRobot::API_RATE_LIMITED`
+- **prefix**: `int` `默认:API_NORMAL`，可选 `OneBotV11::API_NORMAL`、`OneBotV11::API_ASYNC`、`OneBotV11::API_RATE_LIMITED`

 设置后缀后，请求的 API 会发生变化。例如发送私聊消息：`sendPrivateMsg()`，请求的 API 为 `send_private_msg_async`，详见 [OneBot 文档](https://github.com/howmanybots/onebot/blob/master/v11/specs/api/README.md)。

@@ -43,22 +46,22 @@ ZMRobot 类是封装好的 OneBot 标准的 API 接口调用类，可以在机
 获取当前对象的机器人 QQ 或 OneBot 实例的 ID。

 ```php
-$bot = ZMRobot::get(123456);
+$bot = OneBotV11::get(123456);
 echo $bot->getSelfId(); //123456
 ```

-### ZMRobot::get()
+### OneBotV11::get()

-静态方法，用来通过机器人 QQ 或 OneBot 实例的 ID 获取 ZMRobot 对象。
+静态方法，用来通过机器人 QQ 或 OneBot 实例的 ID 获取 OneBotV11对象。

 参数：`$robot_id`，必填。

 ```php
-$r = ZMRobot::get(123456); 
+$r = OneBotV11::get(123456); 
 $r->sendPrivateMsg(55555, "hello");
 ```

-### ZMRobot::getRandom()
+### OneBotV11::getRandom()

 静态方法，随机获取一个连接到框架的机器人（多个机器人实例连接到框架时适用）。

@@ -66,21 +69,21 @@ $r->sendPrivateMsg(55555, "hello");

 ```php
 try {
-	$bot = ZMRobot::getRandom();
+	$bot = OneBotV11::getRandom();
 	$bot->sendPrivateMsg(55555, "foo");
 } catch (\ZM\Exception\RobotNotFoundException $e) {
    echo "还没有机器人连接到框架！\n";
 }
 ```

-### ZMRobot::getAllRobot()
+### OneBotV11::getAllRobot()

-获取所有连接到框架的机器人的 ZMRobot 对象。
+获取所有连接到框架的机器人的 OneBotV11 对象。

-返回值：`ZMRobot[]`。
+返回值：`OneBotV11[]`。

 ```php
-$all = ZMRobot::getAllRobot();
+$all = OneBotV11::getAllRobot();
 foreach($all as $v) {
    $v->sendPrivateMsg(55555, "机器人轮流给一个人发消息啦！");
 }
@@ -95,7 +98,7 @@ foreach($all as $v) {
 ```php
 //从上下文获取 Websocket 连接对象
 $conn = ctx()->getConnection();
-$bot = new ZMRobot($conn);
+$bot = new OneBotV11($conn);
 ```

 ## 返回结果处理
@@ -103,7 +106,7 @@ $bot = new ZMRobot($conn);
 因为框架的机器人是兼容 OneBot 标准的（原 CQHTTP），所以每次接收发送 API 请求的结果都是大体一样的结构。我们以 `sendPrivateMsg()` 为例，因为发送出去的每一条消息都会在 OneBot 实例（如 CQHTTP 插件、go-cqhttp 等）中对应一个消息 ID，以供我们核查消息和后续撤回等操作需要。

 ```php
-$bot = ZMRobot::get("123456"); // 机器人QQ号
+$bot = OneBotV11::get("123456"); // 机器人QQ号
 $obj = $bot->sendGroupMsg("234567", "你好");
 echo json_encode($obj, 128|256);
 ```
@@ -163,7 +166,7 @@ vardump($result["retcode"]); //如果成功撤回，输出 int(0)
 === "代码"

 	```php
-	$bot = ZMRobot::get(123456); // 123456是你的机器人QQ
+	$bot = OneBotV11::get(123456); // 123456是你的机器人QQ
 	$bot->sendPrivateMsg("627577391", "你好啊！你好你好！");
 	```

--- a/docs/component/module/module-pack.md
+++ b/docs/component/module/module-pack.md
@@ -158,4 +158,24 @@ src/
 	}
 	```

-在打包时框架会自动添加这些文件到 phar 插件包内，到解包时，会自动将这些文件释放到对应框架的 `zm_data` 目录下。
+在打包时框架会自动添加这些文件到 phar 插件包内，到解包时，会自动将这些文件释放到对应框架的 `zm_data` 目录下。
+
+## 打包命令
+
+```bash
+# ./zhamao 和原先的 vendor/bin/start 是完全一致的
+./zhamao module:pack <module-name>
+```
+
+例如，打包上面的名叫 foo 的模块：`./zhamao module:pack foo`。
+
+打包命令执行后，将会在 `zm_data` 下的 `output` 目录输出一个 phar 文件。如果你指定了 `version` 参数，那么文件名将会是 `${name}_${version}.phar`，如果没有指定版本，那么只会有 `${name}.phar`，同时如果文件已经存在，将覆盖写入。
+
+## 查看模块信息命令
+
+```bash
+./zhamao module:list
+```
+
+通过此命令可以查看模块相关的信息，如未打包但已配置的模块信息等。
+
--- a/docs/component/module/module-unpack.md
+++ b/docs/component/module/module-unpack.md
@@ -0,0 +1,84 @@
+# 模块解包
+
+从 2.5 版本起，炸毛框架的模块源码支持了打包和分发，分发后必不可少的一步就是将其解包。
+
+解包过程大致为：
+
+1. 检查模块的配置文件是否正常。
+2. 检查模块的依赖问题，如果有依赖但未安装，则抛出异常。
+3. 检查 LightCache 轻量缓存是否需要写入。
+4. 检查 `zm_data` 是否有需要存入的数据。
+5. 合并 `composer.json` 文件。
+6. 拷贝 `zm_data` 相关的文件。
+7. 写入 LightCache 相关数据。
+8. 提示用户手动合并 `global.php` 全局配置文件。
+9. 拷贝模块 PHP 源文件。
+
+## 解包命令
+
+```bash
+./zhamao module:unpack <module-name>
+```
+
+首先将待解包的 phar 文件放入 `zm_data` 目录下的 `modules` 文件夹（如果不存在需要手动创建），如果你手动修改过 `global.php` 下面的 `module_loader.load_path` 项，需要放入对应的目录。
+
+放入后，结构如下：
+
+```
+zm_data/
+zm_data/modules/
+zm_data/modules/foo.phar
+```
+
+接下来，需要知道模块的名称。当然一般情况下，phar 的名称可以获取到模块的实际名称，如 `foo`，但最好用 `./zhamao module:list` 列出模块的信息来获取真实的模块名称。
+
+```
+./zhamao module:list
+# 下面是输出
+[foo]
+        类型: 模块包(phar)
+        位置: zm_data/modules/我是假的名字.phar
+```
+
+解包过程十分简单，只需要执行一次命令即可。
+
+```
+./zhamao module:unpack foo
+# 下面是输出
+[10:05:40] [I] Releasing source file: src/Module/Example/Hello.php
+[10:05:40] [I] Releasing source file: src/Module/Example/zm.json
+[10:05:40] [S] 解压完成！
+```
+
+### 命令参数
+
+在解包时会遇到各种复杂的情况，如源码文件已存在、数据已存在、依赖问题等，通过增加参数可以控制解包时的行为。
+
+#### --overwrite-light-cache
+
+含义：覆盖现有的 LightCache 键值（如果存在的话）。
+
+#### --overwrite-zm-data
+
+含义：覆盖现有的 `zm_data` 下的文件（如果存在的话）。
+
+#### --overwrite-source
+
+含义：覆盖现有的 PHP 模块源文件（如果存在的话）。
+
+#### --ignore-depends
+
+含义：解包时忽略检查依赖。
+
+### 常见问题
+
+如果你解包的模块包要求修改 `global.php`，则会出现类似这样的提示：
+
+```
+# ./zhamao module:unpack foo
+[14:47:39] [W] 模块作者要求用户手动修改 global.php 配置文件中的项目：
+[14:47:39] [W] *请把全局配置文件的light_cache项目中max_strlen选项调整为至少65536
+请输入修改模式，y(使用vim修改)/e(自行使用其他编辑器修改后确认)/N(默认暂不修改)：[y/e/N]
+```
+
+一般这种情况，根据第二条提示（第二条提示为打包时填入的 `global-config-override`）。如果输入 y，则会自动执行命令 `vim config/global.php`，如果输入的是 e，则会等待你手动修改完成文件，最后按回车完成修改。默认情况直接回车的话，会跳过此步骤，如果模块要求了修改但跳过修改，安装后可能会有功能缺失等问题。
--- a/docs/component/store/mysql-db.md
+++ b/docs/component/store/mysql-db.md
@@ -0,0 +1,101 @@
+# MySQL 数据库（旧版组件）
+
+!!! warning "注意"
+
+	此 MySQL 组件为旧版 MySQL 查询器组件，为了统一和提升对未来独立组件的兼容性，现转变为使用 `doctrine/dbal` 和 `doctrine/orm` 库来实现查询器，请转到 [MySQL 查询器]()。
+
+## 配置
+
+炸毛框架的数据库组件支持原生 SQL、查询构造器，去掉了复杂的对象模型关联，同时默认为数据库连接池，使开发变得简单。
+
+数据库的配置位于 `config/global.php` 文件的 `sql_config` 段。
+
+数据库操作的唯一核心工具类和功能类为 `\ZM\DB\DB`，使用前需要配置 host 和 use 此类。
+
+## 查询构造器
+
+在 炸毛框架 中，数据库查询构造器为创建和执行数据库查询提供了一个方便的接口，它可用于执行应用程序中大部分数据库操作。同时，查询构造器使用 `prepare` 预处理来保护程序免受 SQL 注入攻击，因此没有必要转义任何传入的字符串。
+
+### 新增数据
+
+```php
+DB::table("admin")->insert(['admin_name', 'admin_password'])->save();
+// INSERT INTO admin VALUES ('admin_name', 'admin_password')
+```
+
+其中 `insert` 的参数是插入条目的数据列表。假设 admin 表有 `name`，`password` 两列。
+
+> 自增 ID 插入 0 即可。
+
+### 删除数据
+
+```php
+DB::table("admin")->delete()->where("name", "admin_name")->save();
+// DELETE FROM admin WHERE name = 'admin_name'
+```
+
+其中 `where` 语句的第一个参数为列名，当只有两个参数时，第二个参数为值，效果等同于 SQL 语句：`WHERE name = 'admin_name'`，当含有第三个参数且第二个参数为 `=`，`!=`，`LIKE` 的时候，效果就是 `WHERE 第一个参数 第二个参数的操作符 第三个参数`。
+
+### 更新数据
+
+```php
+DB::table("admin")->update(["name" => "fake_admin"])->where("name", "admin_name")->save();
+// UPDATE admin SET name = 'fake_admin' WHERE name = 'admin_name'
+```
+
+`update()` 方法中是要 SET 的内容的键值对，例如上面把 `name` 列的值改为 `fake_admin`。
+
+### 查询数据
+
+```php
+$r = DB::table("admin")->select(["name"])->where("name", "fake_admin")->fetchFirst();
+// SELECT name FROM admin WHERE name = 'fake_admin'
+echo $r["name"];
+echo DB::table("admin")->where("name", "fake_admin")->value("name");
+// SELECT * FROM admin WHERE name = 'fake_admin'
+```
+
+`select()` 方法的参数是要查询的列，默认留空为 `["*"]`，也就是所有列都获取，也可以在 table 后直接 where 查询。
+
+其中 `fetchFirst()` 获取第一行数据。
+
+如果只需获取一行中的一个字段值，也可以通过上面所示的 `value()` 方法直接获取。
+
+多列数据获取需要使用 `fetchAll()`
+
+```php
+$r = DB::table("admin")->select()->fetchAll();
+// SELECT * FROM admin WHERE 1
+foreach($r as $k => $v) {
+    echo $v["name"].PHP_EOL;
+}
+```
+
+### 查询条数
+
+```php
+DB::table("admin")->where("name", "fake_admin")->count();
+//SELECT count(*) FROM admin WHERE name = 'fake_admin'
+```
+
+
+
+## 直接执行 SQL 
+
+>  在查询器外执行的 SQL 语句都不会被缓存，都是一定会请求数据库的。
+
+### DB::rawQuery()
+
+- 用途：直接执行模板查询的裸 SQL 语句。
+- 参数：`$line`，`$params`
+- 返回：查到的行的数组
+
+`$line` 为请求的 SQL 语句，`$params` 为模板参数。
+
+```php
+$r = DB::rawQuery("SELECT * FROM admin WHERE name = ?", ["fake_admin"]);
+//SELECT * FROM admin WHERE name = 'fake_admin'
+echo $r[0]["password"];
+```
+
+> 参数查询已经从根本上杜绝了 SQL 注入的问题。
--- a/docs/component/store/mysql.md
+++ b/docs/component/store/mysql.md
@@ -1,97 +1,10 @@
 # MySQL 数据库

-## 配置
+## 简介

-炸毛框架的数据库组件支持原生 SQL、查询构造器，去掉了复杂的对象模型关联，同时默认为数据库连接池，使开发变得简单。
+炸毛框架的数据库组件对接了 MySQL 连接池，在使用过程中无需配置即可实现 MySQL 查询，同时拥有高并发。

-数据库的配置位于 `config/global.php` 文件的 `sql_config` 段。
-
-数据库操作的唯一核心工具类和功能类为 `\ZM\DB\DB`，使用前需要配置 host 和 use 此类。
-
-## 查询构造器
-
-在 炸毛框架 中，数据库查询构造器为创建和执行数据库查询提供了一个方便的接口，它可用于执行应用程序中大部分数据库操作。同时，查询构造器使用 `prepare` 预处理来保护程序免受 SQL 注入攻击，因此没有必要转义任何传入的字符串。
-
-### 新增数据
-
-```php
-DB::table("admin")->insert(['admin_name', 'admin_password'])->save();
-// INSERT INTO admin VALUES ('admin_name', 'admin_password')
-```
-
-其中 `insert` 的参数是插入条目的数据列表。假设 admin 表有 `name`，`password` 两列。
-
-> 自增 ID 插入 0 即可。
-
-### 删除数据
-
-```php
-DB::table("admin")->delete()->where("name", "admin_name")->save();
-// DELETE FROM admin WHERE name = 'admin_name'
-```
-
-其中 `where` 语句的第一个参数为列名，当只有两个参数时，第二个参数为值，效果等同于 SQL 语句：`WHERE name = 'admin_name'`，当含有第三个参数且第二个参数为 `=`，`!=`，`LIKE` 的时候，效果就是 `WHERE 第一个参数 第二个参数的操作符 第三个参数`。
-
-### 更新数据
-
-```php
-DB::table("admin")->update(["name" => "fake_admin"])->where("name", "admin_name")->save();
-// UPDATE admin SET name = 'fake_admin' WHERE name = 'admin_name'
-```
-
-`update()` 方法中是要 SET 的内容的键值对，例如上面把 `name` 列的值改为 `fake_admin`。
-
-### 查询数据
-
-```php
-$r = DB::table("admin")->select(["name"])->where("name", "fake_admin")->fetchFirst();
-// SELECT name FROM admin WHERE name = 'fake_admin'
-echo $r["name"];
-echo DB::table("admin")->where("name", "fake_admin")->value("name");
-// SELECT * FROM admin WHERE name = 'fake_admin'
-```
-
-`select()` 方法的参数是要查询的列，默认留空为 `["*"]`，也就是所有列都获取，也可以在 table 后直接 where 查询。
-
-其中 `fetchFirst()` 获取第一行数据。
-
-如果只需获取一行中的一个字段值，也可以通过上面所示的 `value()` 方法直接获取。
-
-多列数据获取需要使用 `fetchAll()`
-
-```php
-$r = DB::table("admin")->select()->fetchAll();
-// SELECT * FROM admin WHERE 1
-foreach($r as $k => $v) {
-    echo $v["name"].PHP_EOL;
-}
-```
-
-### 查询条数
-
-```php
-DB::table("admin")->where("name", "fake_admin")->count();
-//SELECT count(*) FROM admin WHERE name = 'fake_admin'
-```
+目前 2.5 版本后炸毛框架底层采用了 `doctrine/dbal` 组件，可以方便地构建 SQL 语句。



-## 直接执行 SQL 
-
->  在查询器外执行的 SQL 语句都不会被缓存，都是一定会请求数据库的。
-
-### DB::rawQuery()
-
- 用途：直接执行模板查询的裸 SQL 语句。
- 参数：`$line`，`$params`
- 返回：查到的行的数组
-
-`$line` 为请求的 SQL 语句，`$params` 为模板参数。
-
-```php
-$r = DB::rawQuery("SELECT * FROM admin WHERE name = ?", ["fake_admin"]);
-//SELECT * FROM admin WHERE name = 'fake_admin'
-echo $r[0]["password"];
-```
-
-> 参数查询已经从根本上杜绝了 SQL 注入的问题。