# CQAPI

不推荐

CQAPI 为旧的调用 coolq-http-api 插件的方式，由于写法比较落后和繁琐，将在 2.0 版本移除。现在推荐使用新的 ZMRobot 对象进行 API 的调用。

在框架内，不仅可以使用基类函数来进行操作，也可以直接使用封装好的 CQHTTP API 接口。此接口组件所有调用方式均为静态方法，可在模块任意位置调用。

注意

由于框架本身支持多机器人同时连接，所以所有 API 请求操作均需要带有要请求到的机器人的 id 或链接对象。

# 调用方式

首先就是需要在模块最上面 use ZM\API\CQAPI; 才能使用。

用法：CQAPI::API名称($robot, $param = [], $yield = null);

API 名称为 CQHTTP 对应的 API 名称，例如 send_private_msg，get_status 等。可到 CQHTTP 文档 - API 查看。

参数解释：

$robot 为机器人的 QQ 或连接对象。连接对象可通过 $this->getConnection() 获取。对象解释请见 WebSocket 服务器 一章。
$param 对应 CQHTTP API 接口需要的参数，参见 CQHTTP 文档 - API (opens new window)。
$yield 为 API 请求返回结果后处理的方式。如果 $yield 是匿名函数的话，则会在 API 请求返回后回调匿名函数。如果是 true 的话，则会在发送 API 请求后协程等待，收到结果后作为 API 函数调用的返回值。

注意

当使用 $yield = true 时，会将处理当前消息的整个协程挂起，直到 CQHTTP 插件返回此 API 执行的结果。结果返回值自动处理成了数组，返回内容参见 CQHTTP 文档 - API (opens new window)。

框架封装方式为 PHP 的魔术方法映射对应 API 进行操作，所以对应 API 可以查阅 CQHTTP 文档 - API (opens new window)。

例子：

CQAPI::send_private_msg($this->getConnection(), ["user_id" => 123456, "message" => "我是复读机"]);

# API 兼容性

当你在使用 PhpStorm 或 IDEA 等 IDE 编写代码时，如果为了保证代码风格统一，在写 CQAPI 调用时，不仅可以写上面提到的和 CQHTTP 文档相同的 API，也可以使用驼峰命名法编写 API名称。例如 CQAPI::send_group_msg 可以写成 CQAPI::sendGroupMsg。

如果在使用过程中调用了未知的 API 时，框架会抛出异常，中断此次事件。

# 响应处理

对于上面提到的 $yield 参数，就是用来处理 API 响应结果的。当其为匿名函数，如下，你可以像下面这样处理结果。比如向终端报告消息处理正常：

CQAPI::send_group_msg(12345, ["group_id" => 100000, "message" => "test"], function ($response, $origin){
    if($response["retcode"] == 200){
        echo "成功地发出了消息: ".$origin["params"]["message"];
    }
});

1
2
3
4
5

也可以使用 $yield = true 协程等待，在返回结果后会作为 API 调用的返回值。

$msg = CQAPI::send_group_msg(123, ["group_id" => 12345, "message" => "test"], true);
if($msg["retcode"] == 200) {
    echo "成功发出了消息：".$msg["params"]["message"];
}

1
2
3
4

提示

对于模块基类的快速回复方法，也可以使用如上的响应方式，因为 $this->reply()的第二个参数也是 $yield，和上方相同。

← ZMRobot CQ 码 →