zhamao-robot/zhamao-framework
1
0
Fork 0
mirror of https://github.com/zhamao-robot/zhamao-framework.git synced 2026-07-21 15:45:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

renew docs (#205)

Browse Source
This commit is contained in:
sunxyw
2022-12-26 18:31:27 +08:00
committed by GitHub
parent aa28675016
commit 81a5e48b26
73 changed files with 214 additions and 9326 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/guide/README.md
View File

@@ -1,50 +1,30 @@
# 介绍
::: tip 提示
> 编写文档需要较大精力，你也可以参与到本文档的建设中来，比如找错字，增加或更正内容，每页文档可直接点击右上方铅笔图标直接跳转至 GitHub 进行编辑，编辑后自动 Fork 并生成 Pull Request，以此来贡献此文档！
编写文档需要较大精力，你也可以参与到本文档的建设中来，比如找错字，增加或更正内容，每页文档可直接点击右上方铅笔图标直接跳转至 GitHub 进行编辑，编辑后自动 Fork 并生成 Pull Request，以此来贡献此文档！
炸毛框架主要面向聊天机器人（OneBot 标准）和 API 服务的开发。
:::
框架使用 PHP 编写，无需安装任何额外扩展即可运行在任意主流平台，支持包括 Swoole 和 Workerman 在内的多种驱动，同时支持所有在 OneBot 标准内的通信方式，并支持使用注解（Annotation）和属性（Attribute）注册绑定各种事件，同时引入了依赖注入容器让开发更为便捷。
炸毛框架使用 PHP 编写，采用 Swoole 扩展为基础，主要面向 API 服务，聊天机器人（OneBot 标准的机器人对接），包含 WebSocket、HTTP 等监听和请求库，用户代码采用模块化处理，使用注解可以方便地编写各类功能。
框架内置了对于 WebSocket 和 HTTP 的服务端和客户端支持，并针对聊天机器人消息处理进行优化扩展，提供常用会话机制和内部调用机制，让代码更为灵活。
框架主要用途为 HTTP/WebSocket 服务器，机器人搭建框架。尤其对于聊天机器人消息处理较为方便和全面，提供了众多会话机制和内部调用机制，可以以各种方式设计你自己的模块。
这里放个代码示例
此外，QQ 机器人方面此框架基于 OneBot 标准的反向 WebSocket 连接，比传统 HTTP 通信更快。
## 环境要求
```php
/**
* @CQCommand("你好")
*/
public function hello() {
ctx()->reply("你好，我是炸毛！");
}
/**
* @RequestMapping("/index")
*/
public function index() {
return "<h1>hello!</h1>";
}
```
虽然我们已经大力简化了运行框架的要求，但仍然存在少量的必要项：
## 开始前
首先，你需要了解你需要知道哪些事情才能开始着手使用框架：
1. Linux 命令行（会跑 Linux 程序）
2. php >=7.2 开发环境（项目会持续支持最新的 PHP 版本）
4. OneBot 机器人聊天接口标准
需要值得注意的是，本教程中所涉及的内容均为尽可能翻译为白话的方式进行描述，但对于框架的组件或事件等需要单独拆分说明文档的部分则需要足够详细，所以本教程提供一个快速上手的教程，并且会将最典型的安装方式写到快速教程篇。
- PHP 8.0 或以上版本
- JSON 扩展
- Tokenizer 扩展
- Composer 工具
## 框架特色
- 支持MySQL数据库（连接池），自带查询缓存提高多查询时的效率
- Websocket 服务器、HTTP 服务器兼容运行，一个框架多个用处
- WebSocket 服务器、HTTP 服务器兼容运行，一个框架多个用处
- 支持命令、自然语言处理等多种插件形式
- 支持多个机器人账号负载均衡
- 协程 + TaskWorker 进程重度任务处理机制，保证高效，单个请求响应时间为 0.1 ms 左右
- 模块分离和自由组合，可根据自身需求自己建立模块内的目录结构和代码结构
- 灵活的注释注解注册事件方式，弥补 PHP 语言缺少注解的遗憾
- 灵活的注释和注解注册事件方式，支持 PHP 原生注解，提示更为友好

195
docs/guide/basic-config.md
View File

@@ -1,195 +0,0 @@
# 基本配置
到目前为止，炸毛框架的配置文件还没有任何变更，是默认的行为。在本章内容中，将列举出炸毛框架的配置文件的规则和使用。
::: danger 警告
因为炸毛框架的全局配置中含有数据库名称和密码以及 access_token 等敏感字段，在使用版本控制软件过程中请不要将敏感信息写入配置文件并提交至开源仓库！
:::
## 全局配置文件 global.php
框架的全局配置文件在 `config/global.php` 文件中。下面是配置文件的各个选项，请根据自己的需要自行配置。
| 配置名称 | 说明 | 默认值 |
| :--------------------------- | ------------------------------------------------------------ | ---------------------------- |
| `host` | 框架监听的地址 | 0.0.0.0 |
| `port` | 框架监听的端口 | 20001 |
| `http_reverse_link` | 框架开到公网或外部的 HTTP 反代链接 | 见配置文件 |
| `zm_data` | 框架的配置文件、日志文件等文件目录 | `./` 下的 `zm_data/` |
| `debug_mode` | 框架是否启动 debug 模式 | false |
| `crash_dir` | 存放崩溃和运行日志的目录 | `zm_data` 下的 `crash/` |
| `config_dir` | 存放 saveToJson() 方法保存的数据的目录 | `zm_data` 下的 `config/` |
| `swoole` | 对应 Swoole server 中 set 的参数，参考Swoole文档 | 见子表 `swoole` |
| `runtime` | 一些框架运行时调整的设置 | 见子表 `runtime` |
| `light_cache` | 轻量内置 key-value 缓存 | 见字表 `light_cache` |
| `worker_cache` | 跨进程变量级缓存 | 见子表 `worker_cache` |
| `mysql_config` | MySQL 数据库连接信息 | 见子表 `mysql_config` |
| `redis_config` | Redis 连接信息 | 见子表 `redis_config` |
| `access_token` | OneBot 客户端连接约定的token，留空则无，相关设置见 [组件 - Access Token 验证](component/access-token) | 空 |
| `http_header` | HTTP 请求自定义返回的header | 见配置文件 |
| `http_default_code_page` | HTTP服务器在指定状态码下回复的默认页面 | 见配置文件 |
| `init_atomics` | 框架启动时初始化的原子计数器列表 | 见配置文件 |
| `info_level` | 终端日志显示等级（0-4） | 2 |
| `context_class` | 上下文所定义的类，见对应上下文说明文档 | `\ZM\Context\Context::class` |
| `static_file_server` | 静态文件服务器配置项 | 见子表 `static_file_server` |
| `server_event_handler_class` | 注册 Swoole Server 事件注解的类列表，在 Swoole 服务器启动前就被加载 | 空 |
| `onebot` | OneBot 协议相关配置 | 见子表 `onebot` |
| `remote_terminal` | 远程终端相关配置 | 见子表 `remote_terminal` |
| `module_loader` | 模块/插件 加载相关配置 | 见子表 `module_loader` |
### 子表 **swoole**
| 配置名称 | 说明 | 默认值 |
| ----------------------- | ------------------------------------------------------------ | ----------------------------------- |
| `log_file` | Swoole 的日志文件 | `crash_dir` 下的 `swoole_error.log` |
| `worker_num` | Worker 工作进程数 | 运行框架的主机 CPU 核心数 |
| `dispatch_mode` | 数据包分发策略，见 [文档](https://wiki.swoole.com/#/server/setting?id=dispatch_mode) | 2 |
| `max_coroutine` | 最大协程并发数 | 300000 |
| `max_wait_time` | 退出进程时等待协程恢复的最长时间（秒） | 5（2.4.3 版本后默认值） |
| `task_worker_num` | TaskWorker 工作进程数 | 默认不开启（此参数被注释） |
| `task_enable_coroutine` | TaskWorker 工作进程启用协程 | 默认不开启（此参数被注释）或 `bool` |
### 子表 runtime
| 配置名称 | 说明 | 默认值 |
| ----------------------------- | ------------------------------------------------------------ | --------------------------------------- |
| `swoole_coroutine_hook_flags` | Swoole 启动时一键协程化 Hook 的 Flag 值，详见 [一键协程化](http://wiki.swoole.com/#/runtime?id=%e5%87%bd%e6%95%b0%e5%8e%9f%e5%9e%8b) | `SWOOLE_HOOK_ALL & (~SWOOLE_HOOK_CURL)` |
| `swoole_server_mode` | Swoole Server 启动的进程模式，有 `SWOOLE_PROCESS` 和 `SWOOLE_BASE` 两种，见 [启动方式](http://wiki.swoole.com/#/learn?id=swoole_process) | `SWOOLE_PROCESS` |
| `middleware_error_policy` | 中间件错误处理策略，见 [中间件 - 错误处理策略](../../event/middleware/#_6) | 1 |
| `reload_delay_time` | 框架 reload 重载命令接收后延迟的时间（毫秒，0 为不等待） | 800 |
| `global_middleware_binding` | 给注解事件绑定全局中间件，见 [中间件 - 全局中间件](../../event/middleware/#_6) | `[]` |
| `save_console_log_file` | 当这里输入字符串路径时，所有 `Console::xxx()` 输出的日志都将保存到目标文件 | false |
### 子表 **light_cache**
| 配置名称 | 说明 | 默认值 |
| -------------------------- | ----------------------------------------------- | ---------------------------- |
| `size` | 最多可以缓存的 k-v 条目数（必须是 2 的 n 次方） | 512 |
| `max_strlen` | 作为 value 字符串的最大长度 | 32768 |
| `hash_conflict_proportion` | Hash冲突率（越大越好，但是需要的内存更多） | 0.6 |
| `persistence_path` | 持久化的键值对的存储路径 | `zm_data` 下的 `_cache.json` |
| `auto_save_interval` | 持久化的键值对自动保存时间间隔（秒） | 900 |
### 子表 worker_cache
| 配置名称 | 说明 | 默认值 |
| -------- | --------------------------- | ------ |
| `worker` | 跨进程缓存的存储工作进程 id | 0 |
### 子表 **mysql_config**
| 配置名称 | 说明 | 默认值 |
| ------------------------ | ------------------------------ | ------------------------------------------------------------ |
| `host` | 数据库地址(留空则不使用数据库) | 空 |
| `port` | 数据库端口 | 3306 |
| `username` | 连接数据库的用户名 | |
| `dbname` | 要连接的数据库名 | |
| `password` | 数据库连接密码 | |
| `options` | PDO 数据库的 options 参数 | `[PDO::ATTR_STRINGIFY_FETCHES => false,PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC]` |
| `pool_size` | MySQL 连接池大小 | 64 |
| `charset` | MySQL 字符集 | `utf8mb4` |
### 子表 **redis_config**
| 配置名称 | 说明 | 默认值 |
| ---------- | ------------------------------------------ | ------ |
| `host` | Redis 服务器地址，留空则启动时不创建连接池 | 空 |
| `port` | Redis 服务器端口 | 6379 |
| `timeout` | Redis 超时时间 | 1 |
| `db_index` | Redis 要连接的数据库 index | 0 |
| `auth` | 认证字符串 | 空 |
### 子表 static_file_server
| 配置名称 | 说明 | 默认值 |
| ---------------- | ---------------------- | ------------------------------ |
| `status` | 是否开启静态文件服务器 | false |
| `document_root` | 静态文件的根目录 | `{WORKING_DIR}/resources/html` |
| `document_index` | 默认索引的文件名列表 | `["index.html"]` |
### 子表 onebot
| 配置名称 | 说明 | 默认值 |
| ------------------------ | ------------------------------------------------------------ | ------ |
| `status` | 是否开启 OneBot 标准机器人解析功能 | true |
| `single_bot_mode` | 是否开启单机器人模式 | false |
| `message_level` | 机器人的 WebSocket 事件在 Swoole 原生事件 `@OnMessageEvent` 中的等级（越高说明越被优先处理） | 99 |
| `message_convert_string` | 是否将数组格式的消息转换为字符串以保证与旧版本的兼容性 | true |
| `message_command_policy` | CQCommand命令匹配后执行流程，`interrupt` 为不执行后续 CQMessage，`continue` 为继续 | `interrupt` |
### 子表 remote_terminal
| 配置名称 | 说明 | 默认值 |
| -------- | ------------------------------------------------------------ | ----------- |
| `status` | 是否开启远程终端功能，见 [组件 - 远程终端](/component/remote-terminal) | false |
| `host` | 远程终端监听地址，为安全起见，默认值只允许本地回环地址（127.0.0.1） | `127.0.0.1` |
| `port` | 远程终端监听的 TCP 端口 | 20002 |
| `token` | 远程终端连接的令牌（如果为空（""）则不验证） | "" |
### 子表 module_loader
| 配置名称 | 说明 | 默认值 |
| -------- | ------------------------------------------------------------ | ----------- |
| `enable_hotload` | 是否开启热加载模块包的功能 | false |
| `load_path` | 模块包加载的目录地址 | `zm_data` 下的 `modules` |
## 多环境下的配置文件
炸毛框架的配置文件模块支持不同环境下的配置文件，主要结构为 `global.{环境}.php`。在一般情况下，炸毛框架默认从教程引导方式根据指令 `vendor/bin/start server` 启动的框架是不带环境控制的。这章将讲述如何根据不同的环境（development / staging / production）来编写配置文件。
### 使用环境参数
在启动框架时，额外增加参数 `--env` 可以指定当前的环境，从而使用不同的配置文件。现在框架支持以下几种环境： `development`，`staging`，`production`。
```bash
vendor/bin/start server --env=development
```
### 不同环境配置文件
由于框架默认只带有 `global.php` 文件，所以假设你现在需要区分开发环境和生产环境的配置，将 `global.php` 文件复制并重命名为 `global.development.php` 或 `global.production.php` 即可。
### 优先级
如果指定了 `--env` 环境参数：`global.{对应环境}.php` > `global.php`，如果两个配置文件都找不到则报错。
如果未指定 `--env` 环境参数：`global.php` > `global.development.php` > `global.staging.php` > `global.production.php`。
## 其他自定义配置文件
炸毛框架的全局配置文件为 `global.php`，为了让不同的开发者更好的二次开发或者集成更多功能，炸毛框架的配置文件模块也支持自己编写的其他 `*.php` 或 `*.json` 格式的配置文件。例如炸毛框架默认附带了 `file_header.json` 这个配置文件（用来返回各类文件扩展名对应的 `Content-Type` 头参数的表）。
使用也非常简单，我们先以 `.json` 格式为例，我们创建一个 `example_a.json` 文件在 `config/` 目录（和 `global.php` 一个文件夹下），并编写自己的任意配置内容：
```json
{
"key1": "value1"
}
```
在框架中，启动后就会默认加载，使用只需要用以下方式即可：
```php
use ZM\Config\ZMConfig; # 先 use 再使用！
$r = ZMConfig::get("example_a", "key1"); # $r == "value1"
```
如果需要用到变量或其他动态的内容，可以使用 `.php` 格式的配置文件。这里还是以 `example_a.php` 来举例：
```php
<?php
$config['key1'] = "value1";
$config['starttime'] = time();
return $config;
```
使用方式同上：
```php
$r = ZMConfig::get("example_a", "key1"); # $r == "value1"
$time = ZMConfig::get("example_a", "starttime"); # $time == 服务器启动时间
```
同时，自定义配置文件也支持环境变量，例如：`example_a.development.json` 或 `example_a.production.php` 均可。

47
docs/guide/configuration.md Normal file
View File

@@ -0,0 +1,47 @@
# 配置
炸毛框架的所有配置文件都存储在 `config` 目录中。每个选项都带有文档，所以你可以查阅这些文件并熟悉可用的配置项。
一般来说，我们建议你优先查看 `config/global.php` 文件及其文档，它包含了运行框架所需要的绝大部分配置，例如通信方式和时区等。
## 配置文件格式
除了 `php` 文件外，我们还支持以下格式：
- YAML
- JSON
- TOML
## 环境配置
根据运行的环境采用不同的配置值是很有必要的，例如你可能希望在本地和生产环境中使用不同的数据库配置。
为了方便这一功能，我们提供了基于环境的配置加载措施。你可以在启动框架时使用 `--env` 选项指定当前环境，例如 `./zhamao server --env=production` 。
如果未明确指定当前环境，则默认环境为 `development`。
如果要使某一配置文件只在特定环境下记载，你可以为给文件添加后缀，例如 `example.production.php` 只会在当前环境为 `production` 时加载。
你可以同时设置基础配置文件和环境特定配置文件，例如 `global.php` 和 `global.production.php` ，后者将会覆盖前者中的配置项。
### 配置安全
我们**非常不建议**你将数据库信息、访问密钥的敏感字段提交给版本控制，因为这可能会导致相关信息的泄露，同时也不利于其他开发人员修改自己的本地配置。
相反，我们建议你借助 DotEnv 等库，将相关配置信息写入 `.env` 文件中，并按需读取。
## 访问配置项
你可以在任何地方使用全局 `config` 函数获取配置项值。支持使用点语法获取，配置项名称由文件名开头，并允许指定默认值。
```php
# 获取时区，未设置则返回 Asia/Shanghai
$value = config('global.runtime.timezone', 'Asia/Shanghai');
```
你也可以使用 `config` 函数设置配置项，传递数组即可：
```php
# 将时区修改为 UTC
config(['global.runtime.timezone' => 'UTC']);
```

86
docs/guide/errcode.md
View File

@@ -1,86 +0,0 @@
# 错误码对照表
| 异常码 | 含义 | 解决方案 |
|--------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| E00001 | 炸毛框架未检测到 PHP 安装了 Swoole 扩展 | 根据文档安装扩展去！ |
| E00002 | Swoole 扩展安装的版本过低 | 升级 Swoole 版本，最好为最新版。 |
| E00003 | PHP 版本过低 | 升级 PHP 版本，至少为 7.2。 |
| E00004 | Swoole 版本低于 4.6.7 且未安装 pcntl 扩展 | 安装 pcntl 扩展或升级 Swoole 至少为4.6.7。 |
| E00005 | 在框架命令行解析过程中出现了致命错误 | 请根据提示的错误位置进行调试和修复，如果未解决请将问题反馈给作者。 |
| E00006 | 炸毛框架在源码模式启动时未能修改 composer.json 文件 | 检查源码模式下 composer.json 文件是否正常可写可读。 |
| E00007 | 框架在启动时未找到 global.php 全局配置文件 | 如果是使用 `composer create-project` 或用 git 来克隆 starter 仓库的，需要先使用 `vendor/bin/start init` 指令，再启动服务器。 |
| E00008 | 框架在启动时给用于存储连接数据的共享内存表初始化失败 | 请检查系统内存是否过小，如果一切正常，此问题一般是框架内部导致的问题，请将错误日志反馈给开发者。 |
| E00009 | 使用 `--remote-terminal` 时远程终端处理命令出现异常或致命错误 | 检查自身的远程终端是否正确配置和使用，自定义的 `@TerminalCommand` 注解是否抛出了致命错误。 |
| E00010 | 框架在第一步的启动阶段抛出异常或致命错误，导致框架不能继续运行 | 此错误涵盖的错误内容较多，请根据实际抛出的异常内容进行处理或反馈给开发者。<br />如果你使用了 `@SwooleHandler` 或 `@OnSetup` 注解，那么可以自行检查一下注解绑定的函数有没有出错。 |
| E00011 | 框架在调用 Swoole 服务器启动 `$server->start()` 过程中出现了异常 | 此问题未经测试，暂无解决方案，也没有遇到过，如果有发生，请将错误反馈开发者。 |
| E00012 | 框架在启动时调用脚本解析 `@SwooleHandler` 和 `@OnSetup` 时出现了异常 | 留个坑，下次写，TODO。 |
| E00013 | 使用命令行参数动态设置启动的 Worker/TaskWorker 进程数时输入了非法的数字 | 填写合法的数字或不使用此功能。 |
| E00014 | 炸毛框架的启动命令报错，提示没有找到 PHP 环境 | 使用 `./install-runtime.sh` 命令安装便携的静态 PHP 环境或根据教程和 Linux 发行版安装环境。 |
| E00015 | 启动命令启动框架找不到框架本体的入口文件 | 请检查 Composer 拉取的框架代码是否完整。 |
| E00016 | 连接中断后 `@OnCloseEvent` 事件抛出异常 | 检查 `@OnCloseEvent` 或 `@OnSwooleEvent("close")` 注解事件。 |
| E00017 | 框架作为 WebSocket 服务器收到客户端数据后 `@OnMessageEvent`、`@OnSwooleEvent("message")` 或 OneBot 相关事件抛出了未被捕获的异常或错误 | 检查 `@OnSwooleEvent("message")`、`@OnMessageEvent` 或 OneBot 相关注解事件。 |
| E00018 | 框架设置 `access_token` 参数为自定义闭包函数，有新 WebSocket 连接接入但是闭包函数返回失败 | 说白了就是自定义的 `access_token` 验证失败。如果是自己的 OneBot 客户端连接，那么请检查你的函数或 OneBot 客户端那边和框架约定的 token 是否一致，如果将框架开到了公网并有人尝试连接但失败了说明是正常现象。 |
| E00019 | 框架设置了 `access_token` 为固定字符串，但是 WebSocket 新连接验证 Token 失败 | 如果是自身行为，比如 OneBot 客户端接入，请检查 Token 是否一致。如果不需要设置 Token，请检查全局配置文件的 `access_token` 项是否为空字符串。 |
| E00020 | 框架在收到 WebSocket 连接后触发 `@OnOpenEvent` 注解事件过程中抛出了异常 | 检查用户代码中 `@OnOpenEvent`、`@OnSwooleEvent("open")` 注解事件下的代码是否有问题。 |
| E00021 | 框架在处理 pipeMessage 事件时出现了异常 | 如果写了 `@OnPipeMessageEvent` 注解事件，请检查对应注解事件。如果未设置，可能是框架内部错误，请将报错信息反馈开发者。 |
| E00022 | 调用 `ProcessManager::sendActionToWorker()` 方法时，调用此方法的进程不是 Worker 或 Manager 进程 | 如果你在 Master 进程调用此方法会直接报此错误，框架不支持从 Master 进程调用此方法。 |
| E00023 | 框架在收到 HTTP 请求后处理过程中出现了未捕获的异常 | 检查 HTTP 请求相关的注解解析代码，如果调用栈显示非用户代码所致，请将错误信息反馈开发者。 |
| E00024 | 框架使用 `--watch` 时无法使用热更新并报错 | PHP 未安装 inotify 扩展，请使用 pecl 安装 inotify 扩展并启用后再试。 |
| E00025 | 框架使用终端输入时产生了未捕获的异常或致命错误 | 检查 `@TerminalCommand` 注解事件或检查使用动态命令的内容（例如 bc 或 call 运行的代码或函数有没有错误）。 |
| E00026 | 框架使用 `@OnTask` 注解在 TaskWorker 进程中执行函数抛出了异常 | 检查 TaskWorker 运行的任务代码是否会抛出未捕获的异常。 |
| E00027 | 框架在运行过程中 Worker 进程发生未捕获的异常导致崩溃退出 | 见 [Issue #38](https://github.com/zhamao-robot/zhamao-framework/issues/38)。 |
| E00028 | PHP 未安装 pdo_mysql（mysqlnd+PDO）扩展 | 安装 php-mysql（以 ubuntu 为例，apt install php-pdo php-mysql）。 |
| E00029 | PHP 未安装 redis 扩展 | 安装 redis 扩展。 |
| E00030 | 框架在 Worker 进程启动时出现错误 | 检查 `@OnStart` 相关事件的问题，或根据报错信息定位问题所在。此问题可能较常见，一般在启动时导致的。 |
| E00031 | 框架在启动前解析代码出现错误 | 检查模块代码中是否有 PHP 语法错误。 |
| E00032 | 上下文的 class 没有 implements ContextInterface 接口 | 如果从 global.php 设置了自定义上下文类，那么请检查上下文类有没有根据文档标准来编写接口。 |
| E00033 | Worker 进程运行过程使用 `zm_*` 方法过程中抛出了未被捕获的异常 | 一般是由 `zm_go()` 或 `zm_timer_tik()` 造成的，协程或计时器内抛出了异常未被捕获。建议根据 trace 检查是什么地方抛出的异常。 |
| E00034 | 由带中间件的 `@OnTick` 计时器产生了未被捕获的异常 | 建议检查计时器内的代码抛出异常位置，如果错误处理也是一部分功能，建议使用 `try catch` 自行捕获。 |
| E00035 | CQ 码相关错误 | 根据提示检查调用 CQ 码的代码即可。 |
| E00036 | OneBot WebSocket API 推送失败，可能是 WebSocket 客户端出现了问题 | 建议检查 OneBot 客户端和框架的连接是否正常。 |
| E00037 | OneBot 机器人端连接未找到，或单例模式连接了多个机器人 | 根据提示信息进行修复，比如机器人 xxx 未连接到框架，就看一下 OneBot 客户端是否启用和配置正常。 |
| E00038 | 图灵机器人 API 调用出错 | 根据提示和图灵错误码进行检查。 |
| E00039 | 使用 build 命令时检测到目标目录不存在 | 重新指定一个存在的目录即可。 |
| E00040 | 使用 build 命令时检测到 PHP 未设置 `phar.readonly=Off` | 修改 php.ini 将此项设置为 Off。 |
| E00041 | 使用 init 命令时未检测到 composer.json 文件 | 检查引用框架的 composer.json 文件位置。 |
| E00042 | 框架使用 init 命令时启动模式不是 Composer 模式 | 如果你是使用 git 且下载的仓库是 `zhamao-robot/zhamao-framework.git`，那么代表其以源码模式启动，详见[框架启动模式 - 炸毛框架 v2 (zhamao.xin)](https://framework.zhamao.xin/advanced/custom-start/)。 |
| E00043 | MySQL 数据库出错，抛出异常 | 根据提示信息检查 MySQL 语句是否正确，数据库是否连接正常等，其他不能解决的问题建议反馈开发者。 |
| E00044 | 打包模块过程中抛出了异常 | 根据提示文本进行修复错误的指令和代码即可。 |
| E00045 | 打包模块过程中无法储存 `light-cache-store` 项指定的缓存数据 | 根据提示进行修复即可。 |
| E00046 | Redis 连接池在使用过程中未提前初始化，可能是未设置全局配置文件启用 Redis 连接池 | 检查 global.php 是否设置 Redis 服务器。 |
| E00047 | Redis 连接池初始化失败 | 根据提示报错信息进行修复，先检查 global.php 是否设置 Redis 服务器。 |
| E00048 | LightCache 未初始化 | LightCache 会根据 global.php 初始化申请内存，如果申请出错请根据启动时的报错信息调整配置。 |
| E00049 | LightCache 不能接收字符串、数组、int 之外的变量数据 | 检查传入的数据类型。 |
| E00050 | 系统内存不足，LightCache 申请内存失败 | 让 PHP 可使用的内存或系统内存变大，也可以调小全局配置中设置的 LightCache 配置项。 |
| E00051 | LightCache 的 Hash 冲突过多，导致无法动态空间分配内存 | 设置 `hash_conflict_proportion` 大一些（范围 0-1，默认是 0.6）。 |
| E00052 | 在 /src/ 目录下不可以直接标记为模块(zm.json)，因为命名空间不能为根空间 | 将模块标记文件 zm.json 放到子目录下，不能直接放在 src 目录下。 |
| E00053 | 框架检测到了重名模块 | 更改模块名称。 |
| E00054 | 打包好的模块文件（phar）内检测不到 zm.json 原始模块标记文件存在 | 检查 phar 模块是否完整。 |
| E00055 | 打包好的模块文件（phar）不能正常读取模块标记文件（zm.json） | 检查 phar 模块是否完整。 |
| E00056 | 未开启 TaskWorker 进程 | 请先修改 global 配置文件启用。 |
| E00057 | 调用 `DataProvider::saveToJson()` 失败，因为传入了多级目录 | `saveToJson()` 方法的 `$filename` 参数只能最多到第二级子目录，不能有三级，例如 `foo/bar`。 |
| E00058 | 调用 `DataProvider::scanDirFiles()` 失败，因为传入的 `$relative` 错误 | `$relative` 参数只能传入 `string/false` 两种类型。 |
| E00059 | 使用 `MessageUtil::downloadCQImage()` 失败，因为指定下载的目录不存在 | 新建目录，检查目录地址是否是绝对路径，如果手动指定了目录，最好为绝对路径。 |
| E00060 | 使用 `MessageUtil::downloadCQImage()` 失败，因为图片下载失败 | 检查下载图片的链接地址是否能正常的访问。 |
| E00061 | 使用 `set_coroutine_params()` 失败，因为不能在非协程环境使用此函数 | 检查调用此函数的位置，注意不能在非协程环境（比如 Master 进程）下调用。 |
| E00062 | 注解事件非法或不可回溯 | 不能在非注解调用的类中的方法调用 `EventTracer` 方法。 |
| E00063 | 模块检测到依赖版本问题 | 检查是否部署或正确配置依赖的模块/插件版本。 |
| E00064 | 模块系统检测到依赖的模块不存在或未安装部署 | 检查依赖的模块是否正确存在于源码目录。 |
| E00065 | 模块系统检测到打包的模块文件中未含有 `light_cache_store.json` 文件 | 可能是打包此模块后打包的文件损坏，请询问原开发者打包一个新的没有损坏的 phar 文件。 |
| E00066 | 模块打包时 `zmdata-store` 指定的文件或目录不存在 | 检查是否存在，检查写的相对路径是否有误（相对路径的初始路径为框架当前的 `zm_data` 配置的目录。 |
| E00067 | 模块解包合并 `composer.json` 时没有找到项目原文件 | 检查项目的工作目录下是否有 `composer.json` 文件存在。 |
| E00068 | 模块解包时无法正常拷贝文件 | 检查文件夹是否正常可以创建和写入。 |
| E00069 | 框架不能启动两个 ConsoleApplication 实例 | 不要重复使用 `new ConsoleApplication()`。 |
| E00070 | 框架找不到 `zm_data` 目录 | 检查配置中指定的 `zm_data` 目录是否存在。 |
| E00071 | 框架找不到对应类型的 API 调用类 | 检查 `getExtendedAPI($name)` 传入的 `$name` 是否正确 |
| E00072 | 上下文无法找到 | 检查上下文环境，如是否处于协程环境中 |
| E00073 | 在类中找不到方法 | 检查调用对象是否存在对应的方法（method）或检查是否插入了对应的macro宏方法 |
| E00074 | 参数非法 | 检查调用的参数是否正常（此处可能有多处问题，请看具体调用栈炸掉的地方） |
| E00075 | Cron表达式非法 | 检查 @Cron 中的表达式是否书写格式正确 |
| E00076 | Cron检查间隔非法 | 检查 @Cron 中的检查间隔（毫秒）是否在1000-60000之间 |
| E00077 | 输入了非法的消息匹配参数类型 | 检查传入 `@CommandArgument` 或 `checkArguments()` 方法有没有传入非法的 `type` 参数 |
| E00078 | 配置文件读取失败，未找到 base 配置文件 | 检查配置文件是否存在（一般是由于没找到基类配置文件产生的此错误） |
| E00079 | 配置文件读取失败 | 根据报错信息修复配置文件（或将 debug 日志发给框架开发者或反馈 Issue） |
| E00080 | 调用 `FileSystem::scanDirFiles()` 失败，因为传入的不是目录或无法读取 | 使用 scanDirFiles() 传入一个可读取的目录 |
| E00081 | 传入了未知类型的 Driver | 使用受支持的 Driver 名称，例如 `swoole` 或 `workerman`（如需支持其他驱动，请反馈） |
| E99999 | 未知错误 | |

76
docs/guide/get_started.md Normal file
View File

@@ -0,0 +1,76 @@
# 快速上手
在这里，我们将会以一个基础的复读机为例，帮助你快速熟悉框架的开发流程。
在开始之前，你需要先准备一个可用的 OneBot 机器人实现端（客户端）。
其中一些可用的选项为：
- Walle-Q
- 更多…
## 机器人实现端
> 机器人实现端与炸毛框架相互独立。关于实现端本身的问题请向对应的开发者反馈。如果你确定相关问题由炸毛框架引起（例如缺少适配或代码问题等）请向我们报告。
框架支持多种通信方式，这里将以反向 WebSocket 为例，即框架充当 WS 服务端，实现端作为 WS 客户端连接到框架。
这里以 Walle-Q 实现端为例，在实际使用中，你可以自由选用不同的实现端。
你可以前往 Walle-Q 的[发布页面](https://github.com/onebot-walle/walle-q/releases)下载最新的发行版本，并运行以进行初始化。
在登录成功后，请关闭 Walle-Q 以修改配置文件。
首次运行后，将会在当前目录下生成 `walle-q.toml` 文件。在大多数场景下，这是你唯一需要接触的文件。
在于框架对接的情况中，我们只需要关注 `onebot.websocket_rev` 配置。
```toml
[onebot]
http = []
http_webhook = []
websocket = []
[[onebot.websocket_rev]]
url = "ws://127.0.0.1:20001" # 这里是框架的监听地址
reconnect_interval = 4
```
修改完成并保存后，重新启动 Walle-Q 并登录即可。如果出现连接失败也请勿惊慌，因为框架此时尚未启动，失败是正常现象。
## 编写第一个功能
在框架中，几乎所有事件的绑定都是通过注解进行的，详情可以参阅 注解的使用。
让我们在 `src/Module/Repeater.php` 中开发我们的第一个功能。
```php
namespace Module;
class Repeater
{
#[BotCommand('echo')]
public function repeat(OneBotEvent $event, BotContext $context): void
{
$context->reply($event->getMessage());
}
}
```
借助容器的依赖注入功能，我们可以直接指定相应的类，相关实例会在调用时自动传入。
## 启动框架
在保存了上述的代码后，你就可以通过 `./zhamao server` 启动框架了。
启动后，Walle-Q 的日志应当会显示连接成功的信息。
此时，你可以通过任意账号向机器人发送 `echo 给我复读` 消息，机器人会回复 `给我复读`。
至此，你的第一个功能，复读机，也就开发完成了。
## 使用机器人 API 和更多事件
如果你希望机器人进行其他复杂的动作（操作），请参见 机器人 API。
关于更多可以注册绑定的事件，请参见 注解事件。

96
docs/guide/installation.md
View File

@@ -1,88 +1,46 @@
# 安装
> 这篇为炸毛框架以及环境的部署教程。
我们希望尽可能轻松地使用炸毛，不论是本地开发或是部署都提供多种选择，尽量覆盖所有需求。
框架部署分为两部分，一部分是安装 PHP 环境，另一部分是通过 Composer 或 GitHub 拉取框架的脚手架。
- 一键脚本
- Docker
- Composer
## 一键下载静态 PHP 环境和框架脚手架
## 一键脚本
从 2.4.4 版本起，炸毛框架支持一键拉取一个静态的 PHP 运行时和脚手架（如果本机内安装的 PHP 已符合要求，则不安装），只需运行下面的脚本即可。
炸毛框架提供了一键脚本来设置运行环境并拉取脚手架，帮助你快速进行开发。
```bash
# 将会把 PHP、框架都安装在此目录下
如果检测到本机未安装 PHP 或不符合运行要求，脚本将会自动拉取提前编译好的静态 PHP 运行时。
```shell
# 将静态 PHP 和框架安装在当前目录
bash <(curl -fsSL https://zhamao.xin/go.sh)
# 安装完成后的启动框架命令（2.5.0 版本后可省略掉 runtime/php 前缀）
cd zhamao-app
# 安装完成后启动
./zhamao server
```
> 有关静态 PHP 的多种用法（如 Composer），见 [进阶 - PHP 环境高级](/advanced/php-env)
> 关于静态运行时的更多用法，请参见 这里是链接
## 使用 Docker 部署 PHP 和框架
你也可以使用 Docker 进行拉取 PHP 环境。
## Docker
```bash
# 拉取 Docker 镜像
docker pull zmbot/swoole
待完善
# 再通过 GitHub 或其他方式拉取框架脚手架
git clone --depth=1 https://github.com/zhamao-robot/zhamao-framework-starter.git
cd zhamao-framework-starter/
## Composer
# Docker 内使用 Composer 更新依赖
docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole composer update
docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole vendor/bin/start init
如果你已经有了必要的 PHP 环境和 Composer 工具，你可以直接在任意目录下初始化框架。
# 使用 Docker 启动框架
docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole vendor/bin/start server
> 由于目前 3.0 仍处于预发布阶段，请使用 `composer require zhamao/framework:^3` 来安装
```shell
# 在当前目录初始化框架
composer require zhamao/framework
./vendor/bin/zhamao init
## 安装完成后启动
./zhamao server
```
启动后你会看到和下方类似的初始化内容，表明启动成功了
## 更多的环境部署和开发方式
```verilog
$ vendor/bin/start server
=================================================================
working_dir: /app/zhamao-framework-starter
listen: 0.0.0.0:20001 | worker: 4 (auto)
environment: default | log_level: 2
version: 2.7.0 | master_pid: 28449
=================================================================
______
|__ / |__ __ _ _ __ ___ __ _ ___
/ /| '_ \ / _` | '_ ` _ \ / _` |/ _ \
/ /_| | | | (_| | | | | | | (_| | (_) |
/____|_| |_|\__,_|_| |_| |_|\__,_|\___/
[03-20 22:30:56] [S] [#1] Worker #1 started
[03-20 22:30:56] [S] [#2] Worker #2 started
[03-20 22:30:56] [S] [#3] Worker #3 started
[03-20 22:30:56] [S] [#0] Worker #0 started
```
单纯运行 炸毛框架 后，如果不部署或安装启动任何机器人客户端的话，仅仅相当于启动了一个 监听 20001 端口的WebSoket + HTTP 服务器。你可以通过浏览器访问：http://127.0.0.1:20001 ，或者你部署到了服务器后需要输入服务器地址。
## 命令总结
1. 对于框架的启动，必须 cd 到项目的跟目录，比如 `cd zhamao-app/` 进入到项目根目录。
2. 无论何种方式启动，启动框架的命令格式都为这个格式：`{php二进制路径} vendor/bin/start server {--如果需要参数的话这样跟}`
3. 第二条的 `php 二进制路径` 指的是，比如使用第一种静态 PHP 环境，这里写 `runtime/php` 就好了，如果是安装到系统的 PHP 的话，这里为空，如果是 Docker 部署的环境，则这里填 `docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole`
## 使用 IDE 等工具开发代码
我们使用文本编辑器进行炸毛框架开发，在使用集成开发环境 **IDEA** 或 **PhpStorm** 时，推荐通过插件市场搜索并安装 **PHP Annotations** 插件以提供注解命名空间自动补全、注解属性代码提醒、注解类跳转等，非常有助于提升开发效率的功能。
## 进阶环境部署和开发
炸毛框架还支持更多种启动方式，如源码模式、守护进程模式，具体后续有关环境和部署的进阶教程，请查看 [进阶开发](/advanced/) 部分！
## Windows 注意事项
由于 Swoole 扩展目前无法原生支持 Windows 环境的 PHP，所以以上方式都是默认在 Linux、macOS 系统下的命令。
如果需要在 Windows 上开发和运行，可以使用 WSL（1 和 2 均可）、Linux 虚拟机、Docker 或 cygwin。
如果使用 WSL、虚拟机或 Docker，方式可以直接参考上方相关命令。如果使用 cygwin，可先从 [Swoole 官方仓库](https://github.com/swoole/swoole-src) 下载 swoole 的 cygwin 构建版本，然后下载 Composer 后安装依赖，直接运行框架即可。
## macOS 注意事项
macOS 理论上运行环境和 Linux 无异，但 macOS 由于不能静态编译，所以不能使用静态编译的 PHP 直接运行，需自行从 `Homebrew` 下载最新版 PHP（命令 `brew install php`），然后使用命令 `pecl install swoole` 来安装 Swoole 后运行框架。
除了上述方式之外，框架还支持源码模式、守护进程等运行方式，详情请参阅 [进阶开发]。

25
docs/guide/onebot-choose.md
View File

@@ -1,25 +0,0 @@
# OneBot 实例
## 什么是 OneBot
OneBot 是一个聊天机器人应用接口标准，详情戳 [这里](https://github.com/howmanybots/onebot)。
## OneBot 实现选择
如果你使用炸毛框架作为聊天机器人的开发框架，请先选择一种兼容 OneBot 标准的机器人接口。理论上，基于 OneBot 标准开发的**任何** SDK、框架和机器人应用，都可以无缝地在下面的不同实现中切换。当然，在一小部分细节上各实现可能有一些不同。
| 项目地址 | 平台 | 核心作者 | 备注 |
| ------------------------------------------------------------ | --------------------------------------------- | -------------- | ------------------------------------------------------------ |
| [richardchien/coolq-http-api](https://github.com/richardchien/coolq-http-api) | CKYU | richardchien | 可在 Mirai 平台使用 [mirai-native](https://github.com/iTXTech/mirai-native) 加载 |
| [Mrs4s/go-cqhttp](https://github.com/Mrs4s/go-cqhttp) | [MiraiGo](https://github.com/Mrs4s/MiraiGo) | Mrs4s | 炸毛框架推荐使用此项目机器人应用 |
| [yyuueexxiinngg/cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai) | [Mirai](https://github.com/mamoe/mirai) | yyuueexxiinngg | |
| [takayama-lily/onebot](https://github.com/takayama-lily/onebot) | [OICQ](https://github.com/takayama-lily/oicq) | takayama | |
| [ProtobufBot](https://github.com/ProtobufBot) | [Mirai](https://github.com/mamoe/mirai) | lz1998 | 事件和 API 数据内容和 OneBot 一致，通信方式不兼容 |
::: warning 注意
因为目前炸毛框架 2.0 只支持 WebSocket 方式的 OneBot 实现，所以目前上述项目的连接方式均只可选支持反向 WebSocket 通信的。后期会兼容 HTTP 和正向 WebSocket 通信方式。
:::
如果你还没有自己的 QQ，或者是其他原因导致的暂时无法使用上述 OneBot 实例，可以使用炸毛项目中的 OneBot 协议聊天模拟器。但目前还处在开发中，暂不可用。

9
docs/guide/quickstart-http.md
View File

@@ -1,9 +0,0 @@
# 快速上手 - HTTP 服务器篇
HTTP 服务器篇主要讲解如何通过炸毛框架来实现微服务、API 通用接口等等这些东西的。
- [HTTP 服务器 - 路由和静态文件篇](/event/route-annotations/)
- [HTTP 服务器 - 存储 - LightCache 轻量缓存](/component/light-cache/)
- [HTTP 服务器 - 存储 - Redis](/component/redis/)
- [HTTP 服务器 - 存储 - MySQL](/component/mysql/)
- [HTTP 客户端](/component/zmrequest/)

175
docs/guide/quickstart-robot.md
View File

@@ -1,175 +0,0 @@
# 快速上手 - 机器人篇
## 简介
看到这里，你已经完成了前面的环境部署，到了最关键的第一步了！
一切都安装成功后，你就已经做好了进行简单配置以运行一个最小的 **机器人问答模块** 的准备。
炸毛框架和机器人客户端是什么关系呢？炸毛框架就好比我们传统的一系列例如 Spring 框架、ThinkPHP 框架等，是服务端，而机器人客户端是一个 HTTP / WebSocket 客户端，时刻准备着连接到炸毛框架。
## 机器人客户端
开发之前请注意，**机器人客户端和框架相互独立！**故有关**机器人客户端**出现的问题请到对应机器人客户端开发者或 GitHub 项目中咨询和讨论，炸毛框架为对接机器人客户端的一个快速开发的框架。
机器人客户端是炸毛框架以外的程序或软件，目前炸毛框架支持的机器人客户端通信标准为 OneBot 标准（原 CQHTTP），只要你的机器人客户端是 OneBot 标准的，就可以和炸毛框架进行无缝对接。
OneBot 机器人部分的选择详情见 [OneBot 实例](/guide/OneBot实例/)。
这里以炸毛框架开发过程中使用的 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 来举例进行第一个机器人的配置工作。
简要步骤描述为：
1. 下载 go-cqhttp 对应平台的 [release 文件](https://github.com/Mrs4s/go-cqhttp/releases)
2. 双击 exe 文件或者使用 `./go-cqhttp` 启动
3. 生成默认配置文件并修改默认配置
::: warning 注意
由于 go-cqhttp 项目还处于开发期，而且配置文件格式也发生了多次变化，但大体内容没有变（比如编写此文档时发布的版本中配置文件格式变成了 `hjson` 取代了原来的 `json`。
:::
config.yml（最新格式）：
```yaml {2,3,78,83}
account: # 账号相关
uin: 1233456 # QQ账号
password: '' # 密码为空时使用扫码登录
encrypt: false # 是否开启密码加密
status: 0 # 在线状态 请参考 https://github.com/Mrs4s/go-cqhttp/blob/dev/docs/config.md#在线状态
relogin: # 重连设置
delay: 3 # 首次重连延迟, 单位秒
interval: 3 # 重连间隔
max-times: 0 # 最大重连次数, 0为无限制
# 是否使用服务器下发的新地址进行重连
# 注意, 此设置可能导致在海外服务器上连接情况更差
use-sso-address: true
heartbeat:
# 心跳频率, 单位秒
# -1 为关闭心跳
interval: 5
message:
# 上报数据类型
# 可选: string,array
post-format: string
# 是否忽略无效的CQ码, 如果为假将原样发送
ignore-invalid-cqcode: false
# 是否强制分片发送消息
# 分片发送将会带来更快的速度
# 但是兼容性会有些问题
force-fragment: false
# 是否将url分片发送
fix-url: false
# 下载图片等请求网络代理
proxy-rewrite: ''
# 是否上报自身消息
report-self-message: false
# 移除服务端的Reply附带的At
remove-reply-at: false
# 为Reply附加更多信息
extra-reply-data: false
output:
# 日志等级 trace,debug,info,warn,error
log-level: warn
# 是否启用 DEBUG
debug: false # 开启调试模式
# 默认中间件锚点
default-middlewares: &default
# 访问密钥, 强烈推荐在公网的服务器设置
access-token: ''
# 事件过滤器文件目录
filter: ''
# API限速设置
# 该设置为全局生效
# 原 cqhttp 虽然启用了 rate_limit 后缀, 但是基本没插件适配
# 目前该限速设置为令牌桶算法, 请参考:
# https://baike.baidu.com/item/%E4%BB%A4%E7%89%8C%E6%A1%B6%E7%AE%97%E6%B3%95/6597000?fr=aladdin
rate-limit:
enabled: false # 是否启用限速
frequency: 1 # 令牌回复频率, 单位秒
bucket: 1 # 令牌桶大小
database: # 数据库相关设置
leveldb:
# 是否启用内置leveldb数据库
# 启用将会增加10-20MB的内存占用和一定的磁盘空间
# 关闭将无法使用 撤回 回复 get_msg 等上下文相关功能
enable: true
# 连接服务列表
servers:
# 添加方式，同一连接方式可添加多个，具体配置说明请查看文档
#- http: # http 通信
#- ws: # 正向 Websocket
#- ws-reverse: # 反向 Websocket
#- pprof: #性能分析服务器
# Zhamao Framework 所需要的服务器配置
- ws-reverse:
# 是否禁用当前反向WS服务
disabled: false
# 反向WS Universal 地址
# 注意 设置了此项地址后下面两项将会被忽略
universal: ws://127.0.0.1:20001/
# 反向WS API 地址
api: ws://your_websocket_api.server
# 反向WS Event 地址
event: ws://your_websocket_event.server
# 重连间隔 单位毫秒
reconnect-interval: 3000
middlewares:
<<: *default # 引用默认中间件
```
其中 ws://127.0.0.1:20001/ 中的 127.0.0.1 和 20001 应分别对应炸毛框架配置的 HOST 和 PORT
## 第一次对话
一旦新的配置文件正确生效之后，所在的控制台（如果正在运行的话）应该会输出类似下面的内容：
```verilog
[15:26:34] [I] [#2] 机器人 你的QQ号 已连接！
```
表明机器人已成功连接到炸毛框架了！
这时，如果你是根据安装教程走下来并且未编写任何模块，炸毛自带一个示例模块，里面含有命令：`你好`，`随机数`。如果你对机器人回复：`你好`，它会回复你 `你好啊，我是由炸毛框架构建的机器人！`。这一历史性的对话标志着你已经成功地运行了炸毛框架，开始了编写更强大的 QQ 机器人的创意之旅！
## 编写一个命令
让我们转到框架的模块源代码部分，目录是 `src/Module/Example`，文件是 `Hello.php`。我们插入一段这样的代码：
```php
/**
* @CQCommand("echo")
*/
public function repeat() {
$repeat = ctx()->getFullArg("请输入你要回复的内容");
ctx()->reply($repeat);
//return $repeat; // 这样的效果等同于 ctx()->reply()
}
```
这样，一个简易的复读机就做好了！回到 QQ 机器人聊天，向机器人发送 `echo 你好啊`，它会回复你 `你好啊`。
<chat-box :my-chats="[
{type:0,content:'echo 你好啊'},
{type:1,content:'你好啊'},
{type:0,content:'echo'},
{type:1,content:'请输入你要回复的内容'},
{type:0,content:'哦豁'},
{type:1,content:'哦豁'},
]"></chat-box>
> 如果你只回复 `echo` 的话，它会先和你进入一个会话状态，并问你 `请输入你要回复的内容`，这时你再次说一些内容例如 `哦豁`，会回复你 `哦豁`。效果和直接输入 `echo 哦豁` 是一致的，这是炸毛框架内的一个封装好的命令参数对话询问功能。有关参数询问功能，请看后面的进阶模块。
## 使用机器人 API 和事件
如果你想不只是回复消息，还要做其他复杂的动作（Action），使用 OneBot Action（又名 OneBot API）进行发送即可，见 [机器人 API](/component/bot/robot-api)。
如果想处理其他类型的事件，比如 QQ 群通知事件等，见 [机器人注解事件](/event/robot-annotations/)。

69
docs/guide/register-event.md
View File

@@ -1,69 +0,0 @@
# 注册事件响应（机器人篇）
现在模块已经创建完毕，我们可以开始编写实际代码了。本段以机器人会话为例子来讲述事件注册和响应，有关 HTTP 服务器等注册事件响应请看后面事件和注解章节。
## 机器人聊天事件处理
首先知道，QQ 等聊天机器人的消息我们的处理逻辑为如下简单的模式：
- QQ 用户消息 -> 机器人客户端 -> 连接客户端的框架（炸毛框架）
- 框架处理逻辑后返回给用户的消息 -> 机器人客户端 -> QQ用户
第一步，我们以框架这边的角度考虑，我们称之为“事件”，我们编写代码所做的就是要响应这一事件。
首先我们以一句简单的功能——查天气，我们要从零实现一个查天气的功能进行示范如何快捷有效地开发一个功能。
### 确定问法
我们首先要确定的用户问法是一般由我们自己定义，但最好贴合用户的自然语言来进行定义。比如我们这里提到的天气功能，用户一般就会询问“北京天气”，“北京天气怎么样”，“天气 北京”。
### 注册消息事件
我们以最简单的命令方式“天气 北京”进行处理。问法为参数化的，通过空格来分开，这也是炸毛框架默认支持最基本的聊天事件之一。我们通过上一部分的方式新建一个单文件模块 `Weather.php` 在 `src/Module` 目录下，并编写：
```php
<?php
namespace Module;
use ZM\Annotation\CQ\CQCommand;
class Weather {
/**
* @CQCommand("天气")
* @return string
*/
public function searchWeather() {
$city = ctx()->getNextArg("请告诉我你要查询的城市"); // 发送 “天气 北京”时，变量为“北京”
// 这里假设是天气API接口的对接，返回了天气的数据
$weather = "2020年12月22日，晴，-2~9℃ blablabla";
return "$city 天气情况：".$weather;
}
}
```
::: tip 提示
为了简单起见，我们在这里的例子中没有接入真实的天气数据，但要接入也非常简单，你可以使用中国天气网、和风天气等网站提供的 API，本教程的进阶一栏后期会详细编写如何对接一个天气 API 接口。
:::
在上方代码编写完毕后，运行框架（或运行过程中终端输入 `reload`），然后使用机器人客户端连接到炸毛框架，即可实现我们的第一个功能。我们在代码中编写了一个**注解事件**：`@CQCommand`，此注解事件是用于接收用户的普通消息并切分成各类命令规则的一个注解事件绑定。代码中的注解事件省去了注解中的键名，也可以写作 `@CQCommand(match="天气")`。
这里注解事件的概念请看 [事件和注解](/event/) 一栏描述的概念即可。到这里，我们就完成一个可以处理命令 `天气 xxx` 的方法了！
### 处理消息事件
第一行 `ctx()` 是炸毛框架内的上下文获取方式，每条用户聊天信息发过来，被炸毛框架收到，都会创建一次上下文，同时这次聊天的全部信息，比如用户的 ID（QQ 号码），发消息的时间，如果是群消息的话所在的群号等等，都被存到了上下文中。`ctx()` 获取的是一个上下文对象，内部有许多可操作上下文的方法，其中代码的 `getNextArg()`，作用是根据空格分隔获取命令中的下一个参数。
在之前我们知道：`天气 北京` 是我们发送的消息，我们要获取到用户发送的参数 `北京`。`getNextArg()` 是框架封装好的一个快速获取下一个参数的方法，我们这里直接使用它来获取。
对于 `getNextArg()` 中的文本，可为空，不为空的时候如果用户只发送天气两个字，机器人还是会响应，但是它会询问你这句话，然后你回复机器人“北京”，这里 `$city` 变量就接受到并赋值为“北京”了，代码会继续执行，和直接一次性发送机器人“天气 北京”是一个效果，此为框架封装的消息会话机制，以贴近自然会话的方式来编写代码逻辑。
最后，函数直接返回了一个字符串，作为事件的响应，炸毛框架会自动处理并调用机器人客户端的接口，最后返回给用户消息。这里也可以使用上下文的 `ctx()->reply("xxx")` 方法替代，不返回字符串。注意两者只能选择一种方式，取决于开发者的开发习惯。
<chat-box :my-chats="[
{type:0,content:'天气 北京'},
{type:1,content:'北京 天气情况：2020年12月22日，晴，-2~9℃ blablabla'},
{type:0,content:'天气'},
{type:1,content:'请告诉我你要查询的城市'},
{type:0,content:'北京'},
{type:1,content:'北京 天气情况：2020年12月22日，晴，-2~9℃ blablabla'},
]"></chat-box>

48
docs/guide/structure.md Normal file
View File

@@ -0,0 +1,48 @@
# 目录结构
## 根目录
### Config 目录
`config` 目录包含框架、应用的所有配置文件。最好把这些文件都浏览一遍，并熟悉所有可用的选项。
### Src 目录
`src` 目录包含应用的核心代码，你的大部分工作都将在这里进行。
### Tests 目录
`tests` 目录通常是你编写 PHPUnit 单元测试和功能测试的地方。你可以使用 `composer test` 运行其中的测试。
> 该目录并不自带
>
### Vendor 目录
`vendor` 目录包含你通过 Composer 安装的所有依赖。
## Src 目录
你的大多数代码都位于 `src` 目录中。
### Globals 目录
`globals` 目录包含你的全局定义文件，例如全局函数和常量等。
需要注意的是，框架本身并不会为你自动加载其中的文件，你需要自行使用 Composer 自动加载或其他方式加载其中的代码。
例如 `Globals/my_functions.php` 可以被添加到 `composer.json` 当中。
```json
{
"autoload": {
"files": [
"src/Globals/my_functions.php"
]
}
}
```
### Module 目录
`module` 目录包含你机器人或是服务的主体代码，其中的所有类都会被框架自动扫描并解析，你可以在其中利用注解来注册事件绑定并进行相应处理。

37
docs/guide/upgrade.md
View File

@@ -1,37 +0,0 @@
# 升级指南
因为框架在随着需求以及 Bug 在不断更新，所以在未来框架会发布新版本。为了方便从旧版本安装并使用框架的开发者无损更新到新版本，这里提供了升级版本上需要注意的事项。
## 版本约定
炸毛框架的版本号一般情况均按照 [Semantic Versioning 2.0.0](https://semver.org/) 标准进行滚动发行，规则简述如下：
假设版本号为 x.y.z：
- `x` 为大版本，一般只有在发生完全无法兼容的更新时增加，需要开发者最重视。
- `y` 为小发行版本，默认情况下会新增组件功能，但会尽可能兼容旧版本，存在不兼容情况极少。
- `z` 为补丁版本，在不进行任何大功能更新情况下提供 Bug 的修复，完全兼容前版本。
例如，炸毛框架的 `2.4.2` 版本，在 `2.5.0` 发行后，框架提供了大量新组件，但是对旧版本的配置和组件完全兼容，无任何额外的说明，则可以直接升级。
## 升级方法
根据安装方法不同，升级的方法也不同。
框架安装方式有多种，但主要分为三类：
- Composer 加载库的方式
- 框架源码模式
- Phar 打包模式
在 Composer 加载库的方式下，一般是指使用命令 `composer require zhamao/framework` 或 `composer create-project zhamao/framework-starter` 的方式安装框架，框架的核心文件都在 `vendor` 目录下。
此方式安装的框架升级最方便，直接执行命令 `composer update` 即可。
框架源码模式安装一般为直接使用 `git clone` 框架本体的 GitHub 仓库或下载 master 分支安装，这种情况不可升级版本（或使用 `git pull` 拉取）。
Phar 打包模式更新则必须重新自行打包新版本，例如从 Composer 加载库方式打包的框架，则需在原目录使用 `composer update` 后再次打包一个新版本。
## 升级提示
如果在升级过程中遇到了提示，则可能是需要升级某些配置文件需要手动进行合并更新。如果提示了更新，建议到 `vendor/zhamao/framework/config/global.php` 框架的最新库内配置文件与 `config/global.php` 文件进行对比。

75
docs/guide/write-module.md
View File

@@ -1,75 +0,0 @@
# 编写模块
到现在为止，我们还在使用框架的默认模块 `Example/Hello.php`，在开始编写自己的模块应用之前，我们先说明一些编写代码的约定。
## 加载模块
框架默认使用脚手架构建好后，目录结构大致为下面这样：
```
zhamao-framework-starter/
├── config/ # 项目的配置文件文件夹，如 global.php
├── src/ # 项目的主要源码目录
│ ├── Module/ # 用户编写的模块目录
│ │ └── Example/ # 模块文件夹名称
│ │ └── Hello.php # 模块内的类
│ └── Custom/ # 用户自定义的全局方法、全局注解类等存放的目录
├── vendor/ # Composer 依赖加载目录
└── composer.json # Composer 配置文件
```
其中我们脚手架包含的默认模块 `Example` 下的 `Hello` 类，就是用户写模块的位置。你也可以根据实际情况，自行添加更多的模块文件夹甚至单文件模块。
需要注意的是，所有文件夹名称和 `.php` 文件必须遵循 [psr-4 规范](https://learnku.com/docs/psr/psr-4-autoloader/1608)，简单来说，`src/` 目录下的文件夹，子文件夹要写成命名空间，比如默认框架中 `Example/` 下的 `.php` 文件的命名空间为 `namespace Module\Example;`，且一个 `.php` 文件推荐只包含一个 `class`、`trait` 或 `interface`。
```php
<?php
namespace Module\<your-module-dir>;
class ModuleA {}
```
::: danger 警告
如果没有遵守上方的类和文件命名规则的话（文件名、文件夹名和命名空间的统一性），在加载框架时就会报错，无法找到对应的类。因为框架的注解解析依赖于 Composer 中 psr-4 规则的自动加载。
:::
## 创建模块
### 标准形式
我们这里以 `Entertain` 娱乐模块的创建为例，新建一个内有 `Dice.php` 掷骰子功能的模块，目录结构如下，在 `Module/` 下新建文件夹 `Entertain/`，再在此子目录下新建 `Dice.php` 文件。
```
zhamao-framework-starter/
└── src/
└── Module/
└── Entertain/
└── Dice.php
```
新建的 PHP 文件按照如下方式编写：
```php
<?php
namespace Module\Entertain;
class Dice {
}
```
这个时候它已经可以被称为一个模块了，尽管它还什么都没做。
### 单文件形式
如果你只开发很简单的一些功能，如一个 PHP 文件就可以实现的，可以少去创建模块文件夹的一步，直接将 `.php` 文件新建到 `Module/` 文件夹下，这时此文件的命名空间需要更正为 `namespace Module;` 即可，而文件夹结构也更加简单：
```
zhamao-framework-starter/
└── src/
└── Module/
└── Dice.php
```
### Composer 外部引入形式
（暂未支持，敬请期待，TODO：已经支持了，但缺少文档编写）