客户端 API 参考

Client 是创建和管理 QQ 频道机器人的主要入口点。它处理 WebSocket 连接、身份验证，并将事件分派给您的事件处理器。

概述

use botrs::{Client, EventHandler, Intents, Token};

pub struct Client<H: EventHandler> {
    // 内部字段...
}

Client 管理：

• 到 QQ 频道网关的 WebSocket 连接
• 与 QQ 服务器的身份验证
• 事件分派到您的 EventHandler
• 自动重连和心跳处理
• 速率限制和请求管理

构造函数

new

创建新的客户端实例。

pub fn new(
    token: Token,
    intents: Intents,
    handler: H,
    use_sandbox: bool,
) -> Result<Self>

参数

• token: 包含您的应用 ID 和密钥的身份验证令牌
• intents: 事件订阅配置
• handler: 实现 EventHandler trait 的事件处理器
• use_sandbox: 是否使用沙盒环境进行测试

返回值

返回 Result<Client<H>, BotError> - 客户端实例或初始化失败时的错误。

示例

use botrs::{Client, EventHandler, Intents, Token};

struct MyHandler;

#[async_trait::async_trait]
impl EventHandler for MyHandler {
    // 事件处理方法...
}

let token = Token::new("你的应用ID", "你的密钥");
let intents = Intents::default().with_public_guild_messages();
let handler = MyHandler;

let client = Client::new(token, intents, handler, false)?;

方法

start

启动机器人并开始监听事件。此方法会阻塞直到连接关闭。

pub async fn start(&mut self) -> Result<()>

返回值

返回 Result<(), BotError> - 机器人优雅停止时返回 Ok(())，连接失败时返回错误。

示例

let mut client = Client::new(token, intents, handler, false)?;
client.start().await?;

stop

优雅地停止机器人并关闭 WebSocket 连接。

pub async fn stop(&mut self) -> Result<()>

返回值

返回 Result<(), BotError> - 成功停止时返回 Ok(())，停止失败时返回错误。

示例

// 在另一个任务或信号处理器中
client.stop().await?;

is_connected

检查客户端当前是否连接到网关。

pub fn is_connected(&self) -> bool

返回值

连接时返回 true，否则返回 false。

示例

if client.is_connected() {
    println!("机器人在线");
} else {
    println!("机器人离线");
}

get_session_info

获取当前会话的信息。

pub fn get_session_info(&self) -> Option<&ConnectionSession>

返回值

连接时返回 Some(&ConnectionSession)，断开连接时返回 None。

示例

if let Some(session) = client.get_session_info() {
    println!("会话 ID: {}", session.session_id);
    println!("分片: {}/{}", session.shard_id, session.shard_count);
}

配置

环境 URL

客户端自动选择适当的 API 端点：

• 生产环境: https://api.sgroup.qq.com
• 沙盒环境: https://sandbox.api.sgroup.qq.com

连接设置

默认连接设置：

• WebSocket URL: wss://api.sgroup.qq.com/websocket
• 超时: HTTP 请求 30 秒
• 心跳: 根据服务器要求自动
• 重连: 自动重连，指数退避

错误处理

客户端可能返回各种错误：

use botrs::BotError;

match client.start().await {
    Ok(_) => println!("机器人优雅停止"),
    Err(BotError::Authentication(e)) => eprintln!("认证错误: {}", e),
    Err(BotError::Network(e)) => eprintln!("网络错误: {}", e),
    Err(BotError::Gateway(e)) => eprintln!("网关错误: {}", e),
    Err(e) => eprintln!("其他错误: {}", e),
}

事件流程

1. 连接: 客户端连接到 WebSocket 网关
2. 身份验证: 发送包含令牌和 intent 的识别负载
3. 就绪: 接收就绪事件，机器人现在在线
4. 事件循环: 持续接收和分派事件
5. 重连: 如果连接断开自动重连

线程安全

Client 设计为从单个异步任务使用。对于多线程应用程序，请将其包装在适当的同步原语中：

use std::sync::Arc;
use tokio::sync::Mutex;

let client = Arc::new(Mutex::new(client));

示例

基础机器人

use botrs::{Client, Context, EventHandler, Intents, Message, Ready, Token};

struct BasicBot;

#[async_trait::async_trait]
impl EventHandler for BasicBot {
    async fn ready(&self, _ctx: Context, ready: Ready) {
        println!("机器人就绪: {}", ready.user.username);
    }

    async fn message_create(&self, ctx: Context, message: Message) {
        if let Some(content) = &message.content {
            if content == "!ping" {
                let _ = message.reply(&ctx.api, &ctx.token, "Pong!").await;
            }
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = Token::new("应用ID", "密钥");
    let intents = Intents::default().with_public_guild_messages();
    let mut client = Client::new(token, intents, BasicBot, false)?;
    
    client.start().await?;
    Ok(())
}

带优雅关闭的机器人

use tokio::signal;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = Token::new("应用ID", "密钥");
    let intents = Intents::default().with_public_guild_messages();
    let mut client = Client::new(token, intents, MyHandler, false)?;
    
    // 在后台任务中启动机器人
    let client_handle = tokio::spawn(async move {
        client.start().await
    });
    
    // 等待 Ctrl+C
    signal::ctrl_c().await?;
    println!("收到关闭信号");
    
    // 停止机器人
    client_handle.abort();
    
    Ok(())
}

多个 Intent

let intents = Intents::default()
    .with_public_guild_messages()
    .with_direct_message()
    .with_guilds()
    .with_guild_members();

let mut client = Client::new(token, intents, handler, false)?;

另请参阅

• EventHandler - 定义机器人如何响应事件
• Context - 在事件处理器中访问 API 客户端和令牌
• Intents - 配置要接收的事件
• Token - 身份验证和凭据管理