diff --git a/README.md b/README.md index 10c84de0..f84d49b7 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,9 @@ **相关正在进行的版本任务见 Projects 一栏！** ## 简介 -炸毛框架使用 PHP 编写，采用 Swoole 扩展为基础，主要面向 API 服务，聊天机器人（OneBot 兼容的 QQ 机器人对接），包含 Websocket、HTTP 等监听和请求库，用户代码采用模块化处理，使用注解可以方便地编写各类功能。 + +炸毛框架使用 PHP 编写，采用 Swoole 扩展为基础，主要面向 API 服务，聊天机器人（OneBot 兼容的 QQ 机器人对接），包含 Websocket、HTTP +等监听和请求库，用户代码采用模块化处理，使用注解可以方便地编写各类功能。 框架主要用途为 HTTP 服务器，机器人搭建框架。尤其对于 QQ 机器人消息处理较为方便和全面，提供了众多会话机制和内部调用机制，可以以各种方式设计你自己的模块。 @@ -40,31 +42,40 @@ public function index() { } ``` +> 从 2.7.0 版本开始，框架已支持同时使用 Annotation 和原生 Attribute 注解，供开发者根据需要自由选用。 + ## 开始 + 如果你是初学者，可以直接使用以下脚本部署 PHP 环境和安装框架的脚手架： + ```bash -# 新建一个自己喜欢名字的文件夹，运行一键安装脚本 (仅限 x86_64 和 aarch64 平台) +# 新建一个自己喜欢名字的文件夹，运行一键安装脚本 (仅限 x86-64(AMD64) 和 AArch64(ARM64) 平台) mkdir zhamao-app/ cd zhamao-app/ +# 默认安装的 PHP 版本为 7.4，如需使用其他版本，请设置环境变量 ZM_DOWN_PHP_VERSION 为对应的 PHP 版本，例如： +# export ZM_DOWN_PHP_VERSION=8.1 bash -c "$(curl -fsSL https://api.zhamao.xin/go.sh)" # 启动 -vendor/bin/start server +./zhamao server:start ``` -## 文档（v2 版本） +关于其他安装方式，请参阅[文档](https://framework.zhamao.xin/guide/installation.html) 。 + +## 文档 + 查看文档（国内自建）： 备用链接（国外托管）： -自行构建文档：`mkdocs build -d distribute` - ## 特点 -- 原生为多账号设计，支持多个机器人负载均衡 + +- 原生支持多个机器人客户端同时连接 - 使用 Swoole 多工作进程机制和协程加持，尽可能简单的情况下提升了性能 -- 灵活的注解事件绑定机制，可兼容使用 PHP8 的 Attribute（>=2.7 可用） +- 灵活的注解事件绑定机制，可同时使用 Annotation 和原生 Attribute 注解 - 易用的上下文，模块内随处可用 -- 采用模块化编写，可自由搭配其他 composer 组件，也可单文件面向过程编写 +- 采用模块化编写，可自由搭配其他 Composer 组件，也可单文件面向过程编写 +- 支持模块打包、热加载，分享模块更方便 - 常驻内存，全局缓存变量随处使用，提供多种缓存方案 - 自带 MySQL、Redis 等数据库连接池等数据库连接方案 - 本身为 HTTP 服务器、WebSocket 服务器，可以构建属于自己的 HTTP API 接口 @@ -72,11 +83,13 @@ vendor/bin/start server - 自带 PHP + Swoole 环境，无需手动编译安装，by [crazywhalecc/static-php-cli](https://github.com/crazywhalecc/static-php-cli) ## 下载源码 -框架源码可直接克隆本仓库进行编辑，如果你在国内，访问 GitHub 和 clone 仓库比较慢，可以将 `github.com` 替换为 `fgit.zhamao.me` 进行加速。 + +框架源码可直接克隆本仓库进行编辑，如果你在国内，访问 GitHub 和克隆仓库比较慢，可以将 `github.com` 替换为 `fgit.zhamao.me` 进行加速。 例如：`git clone https://fgit.zhamao.me/zhamao-robot/zhamao-framework.git --depth 1`。 ## 贡献和捐赠 + 如果你在使用过程中发现任何问题，可以提交 Issue 或自行 Fork 后修改并提交 Pull Request。 目前项目仅一人维护，耗费精力较大，所以非常欢迎对框架的贡献。 @@ -85,15 +98,20 @@ vendor/bin/start server 我们会将捐赠的资金用于本项目驱动的炸毛机器人和框架文档的服务器开销上。[捐赠列表](https://github.com/zhamao-robot/thanks) +如果您不想直接参与框架的开发，也可以分享你编写的模块，帮助完善框架生态。 + ### 支付宝 + ![支付宝二维码](https://cdn.jsdelivr.net/gh/zhamao-robot/zhamao-framework/resources/images/alipay_img.jpg) ## 关于 + 框架和 SDK 是 炸毛机器人 项目的核心框架开源部分。炸毛机器人是作者写的一个高性能机器人，曾获全国计算机设计大赛一等奖。 作者的炸毛机器人已从2018年初起稳定运行了**四年半**，并且持续迭代。 -欢迎随时在 HTTP-API 插件群里提问，当然更好的话可以加作者 QQ（[627577391](http://wpa.qq.com/msgrd?v=3&uin=627577391&site=qq&menu=yes)）或提交 Issue 进行疑难解答。 +欢迎随时在 HTTP-API 插件群里提问，当然更好的话可以加作者 QQ（[627577391](http://wpa.qq.com/msgrd?v=3&uin=627577391&site=qq&menu=yes)） +或提交 [Issue](https://github.com/zhamao-robot/zhamao-framework/issues/new/choose) 进行疑难解答。 本项目在更新内容时，请及时关注 GitHub 动态，更新前请将自己的模块代码做好备份。 diff --git a/docs/event/index.md b/docs/event/index.md index f7b24373..fd762b35 100644 --- a/docs/event/index.md +++ b/docs/event/index.md @@ -2,13 +2,17 @@ ## 注解事件概念 -我们知道事件，是一个底层的 event loop 收到消息后调用对应的各类方法的一个模型，比如给机器人发送消息后框架要做的就是指定到一个你定义的函数上，处理你的业务逻辑代码。比如在默认模块中，提供了 **你好** 的回复：**你好啊，我是由炸毛框架构建的机器人！**。这项简单回复的任务就是一个事件的触发到响应的全过程。 +我们知道事件，是一个底层的 event loop 收到消息后调用对应的各类方法的一个模型，比如给机器人发送消息后框架要做的就是指定到一个你定义的函数上，处理你的业务逻辑代码。比如在默认模块中，提供了 **你好** 的回复：** +你好啊，我是由炸毛框架构建的机器人！**。这项简单回复的任务就是一个事件的触发到响应的全过程。 -**注解**（Annotation）又称标注，Java 最早在 2004 年的 JDK 5 中引入的一种注释机制。目前 PHP 官方版本并未提供内置元注解和注解概念，但我们通过 `ReflectionClass` 反射类解析 PHP 代码注释从而实现了自己的一套注解机制。如果你没有写过 Java，并且不了解注解是什么，你可以理解为对 function 或 class 的一个修饰，因为传统的 PHP 代码逻辑我们都知道，不能简单给原先存在的函数贴标签，就比如，你不能在原本的 PHP 代码中给函数贴上一个可以影响它一生并且改变它行为的标签，而有了注解，就相当于有了给函数贴标签的机会。 +**注解**（Annotation）又称标注，Java 最早在 2004 年的 JDK 5 中引入的一种注释机制。目前 PHP 官方版本并未提供内置元注解和注解概念，但我们通过 `ReflectionClass` 反射类解析 PHP +代码注释从而实现了自己的一套注解机制。如果你没有写过 Java，并且不了解注解是什么，你可以理解为对 function 或 class 的一个修饰，因为传统的 PHP +代码逻辑我们都知道，不能简单给原先存在的函数贴标签，就比如，你不能在原本的 PHP 代码中给函数贴上一个可以影响它一生并且改变它行为的标签，而有了注解，就相当于有了给函数贴标签的机会。 在常见框架如 Spring，Swoft 等代码结构里面，注解更是其核心的存在。 -在炸毛框架中，我们所有事件的绑定均采用这一方式进行调用模块内各个方法。包括 Swoole 自身的框架启动事件、WebSocket 连接握手事件、HTTP 请求事件等等，也包括 CQHTTP 发来的事件，如`message`，`notice`，`request` 等。 +在炸毛框架中，我们所有事件的绑定均采用这一方式进行调用模块内各个方法。包括 Swoole 自身的框架启动事件、WebSocket 连接握手事件、HTTP 请求事件等等，也包括 CQHTTP 发来的事件，如`message`，`notice` +，`request` 等。 ## 如何使用注解 @@ -29,9 +33,11 @@ class Hello { } ``` -其中 `@CQCommand()` 就是一个基本的注解应用。注意需引入相关注解（Annotation）类，**且必须** 以 `/**` 开始并以 `*/` 结束，否则会导致无法解析！上方 `@return` 为 IDE 自动生成的 PHPDoc，不需要管。 +其中 `@CQCommand()` 就是一个基本的注解应用。注意需引入相关注解（Annotation）类，**且必须** 以 `/**` 开始并以 `*/` 结束，否则会导致无法解析！上方 `@return` 为 IDE 自动生成的 +PHPDoc，不需要管。 -有什么用？大有妙用！这个例子内注解类的用途是收到 QQ 消息后如果消息第一个词匹配到 `你好` 的话，框架就会自动处理，最终执行调用此 `hello()` 方法。注意 `CQCommand` 和其他任何后面讲到的注解类一样，需先 `use ZM\Annotation\` 下的对应注解类，否则也不能正常使用。 +有什么用？大有妙用！这个例子内注解类的用途是收到 QQ 消息后如果消息第一个词匹配到 `你好` 的话，框架就会自动处理，最终执行调用此 `hello()` 方法。注意 `CQCommand` +和其他任何后面讲到的注解类一样，需先 `use ZM\Annotation\` 下的对应注解类，否则也不能正常使用。 ### 基本语法 @@ -47,11 +53,27 @@ class Hello { 对于没有参数的注解类，`@参数名()` 直接使用即可。 +### PHP8 原生 Attribute 使用 + +在 2.7.0 版本更新后，框架已经完全支持使用原生 Attribute 替代此前的 Annotation。如果你使用 PHP8.0 或以上版本，即可使用 Attribute 以取得最佳的原生编程体验。两者的参数和效果完全一致。 + +以 `@CQCommand` 为例，在 PHP8 中，你可以使用以下代码达成相同的效果。 + +```php +#[CQCommand('帮助', alias=['帮助列表', '菜单'])] +public function help() { +``` + +由于两者几乎完全一致，文档将不会加以区分，统称为注解。 + +> 关于原生注解的更多信息，请查阅[官方文档](https://www.php.net/manual/zh/language.attributes.php)。 + ## 注解和事件的关系 在炸毛框架里，注解常常被当作事件分发的一个重要角色，但注解本身又不是事件，更恰当的说，是注解代表了事件。 -机器人开发过程中常见的 `@CQCommand`，或者是 HTTP 服务器路由绑定 `@RequestMapping` 都是相当于由对应注解代表了事件，而 `@Middleware`，`@Closed` 等这类注解显然不代表任何事件，只能当作这个函数或类的修饰属性而已。代表了事件的注解，我们称之为**注解事件**，它会在某种事件达成条件后触发注解下方的函数本身。 +机器人开发过程中常见的 `@CQCommand`，或者是 HTTP 服务器路由绑定 `@RequestMapping` 都是相当于由对应注解代表了事件，而 `@Middleware`，`@Closed` +等这类注解显然不代表任何事件，只能当作这个函数或类的修饰属性而已。代表了事件的注解，我们称之为**注解事件**，它会在某种事件达成条件后触发注解下方的函数本身。 值得注意的是，注解事件本身概念是我凭空捏造的，我不好解释所以只能创造这么一个词来代指这一抽象的概念，硬要解释的话，大致就好比一个社区里有一个卖牛奶的，有几家人订阅了每日上门送牛奶的服务，只要你打了“给我配送牛奶”的注解，他就会上门。而它送的不止一种奶，可以给你个性化定制，比如让卖牛奶的给你带包糖带瓶水，而描述这个的注解就只能做一个之前注解的修饰。假设你只写了带包糖的注解，没有写给我配送牛奶的注解，那他永远也不会给你送牛奶和糖过来。