NcatBot 文档

外观

BotAPI 统一接口层

约 747 字大约 2 分钟

2025-09-26

BotAPI：统一的上行接口门面

BotAPI 通过多重继承聚合五大接口域：

  • 账号域：AccountAPI
  • 群域：GroupAPI
  • 消息域：MessageAPI
  • 私聊/文件域：PrivateAPI
  • 支持域：SupportAPI

所有接口最终都通过一个统一的异步回调 async_callback(path, params) 下发到底层适配器（Adapter）。这种设计让上层 API 的形态与底层传输解耦，既便于对外暴露一致的易用接口，也方便未来替换适配器或扩展新平台。

接口设计理念

  • 部分接口使用互斥参数校验（check_exclusive_argument），确保 group_id 与 user_id 等不会同时/同时缺失；
  • 底层返回统一包装为 APIReturnStatus/MessageAPIReturnStatus，非 0 retcode 会抛出 NapCatAPIError；
  • 消息体通常使用 MessageArray/MessageSegment/Forward 等结构描述，API 内部负责序列化为 NapCat 需要的 JSON。
  • 提供诸如 post_group_msg/post_private_msg 等组合接口，减少上层手动拼装消息片段的成本。
  • 全局只持有一个 BotAPI 实例，位于 status.global_api，但其他组件会创建对它的引用。

提示

BotAPI 接口很多，这里不逐一罗列。详细列表。

与其他组件的协作机理

与 Adapter

  • 构造注入：BotAPI.__init__(async_callback=Adapter.send)；
  • 调用路径：上层调用 await bot.api.some_method(...) → 进入对应 API 方法 → 统一 await self.async_callback('/some_action', params) → Adapter 生成 echo 并通过 WebSocket 下发 → 收到带 echo 的响应后唤醒并返回结果 → BotAPI 用 APIReturnStatus 解析并抛错或返回数据；
  • 线程/循环安全：Adapter.send 内部使用线程安全结构与 to_thread 桥接，保障在插件线程、BotClient 线程、主事件循环等任意上下文调用都可工作。

与 BotClient

  • BotClient 在初始化时创建 BotAPI(self.adapter.send) 并赋值到 status.global_api 作为全局易取入口；
  • 事件处理器（无论在 BotClient 还是插件里）都可以直接使用 bot.api 发消息、管群、取状态等；
  • run_backend() 会返回 BotAPI，便于在外部业务中直接操作 API 而不必持有 BotClient 引用。

与 EventBus

  • EventBus 负责事件的分发处理（下行事件），BotAPI 负责上行调用；

与 PluginLoader

  • PluginLoader 将 event_bus/rbac_manager/plugin_loader 注入到插件实例；
  • 插件通常在 on_load 中订阅事件，并在处理器内通过 self.api 调用上行接口；

与事件数据结构

  • GroupMessageEvent/PrivateMessageEvent 等事件数据结构中有 reply/reply_sync 便捷方法。可以调用它们快速回复。其实现中使用了 status.global_api。

实践建议

  • 优先使用组合/便捷接口（如 post_group_msg、post_private_msg、post_*_array_msg）组织消息体，提高可读性；
  • 捕获 NapCatAPIError 做业务兜底，必要时开启 debug 以获得更详细的堆栈定位；
  • 在插件处理器中调用 API 时注意耗时操作，必要时拆分任务或使用并发控制，避免阻塞自己的工作线程或总线；
  • 同步接口仅适合少量简单调用，复杂或频繁调用请使用异步接口以获得更好性能。

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot