Rust 快速接入

使用 Rust 1.86+、Tokio 和 crates.io 0.1.0 完成在线收发。支持原生程序，不支持浏览器/WASM。

1. 准备接入

业务后端返回当前用户的 uid、短期 token 和 websocketUrl。按认证与 Token保护注册和轮换流程；客户端不应直接调用 Product HTTP 管理接口。

Auth::new 默认设备类别是 PC/Desktop 2。协议值为 APP 0、WEB 1、PC 2，Token 必须按同一设备类别保存。若你的原生宿主使用 APP 类别，显式设置 auth.device_flag = DeviceFlag::App，并同步后端注册类别。

Auth::new 生成的 device_id 在同一个客户端重连时保持不变；需要跨进程保留设备身份时，由应用读取并设置自己的稳定设备 ID。每个身份创建一个 Client；clone() 共享同一条连接，适合在 Tokio 任务之间传递。

想先看到实际收发效果，可按运行官方示例准备两端；下文说明如何接入自己的应用。

2. 安装 SDK

官方仓库：WuKongIM/WuKongEasySDK-Rust。已发布 crates.io 0.1.0，需要 Rust 1.86+ 和 Tokio。使用以下精确版本：

[dependencies]
wukong-easy-sdk = "=0.1.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde_json = "1"

包名是 wukong-easy-sdk，Rust 导入名是 wukong_easy_sdk。提交应用的 Cargo.lock，让后续构建复用已解析的依赖。当前实现支持原生 TCP/TLS，WSS 使用 rustls 与 WebPKI 根证书；不支持浏览器/WASM。

3. 连接与监听

这个完整程序先订阅事件，再连接并向 Bob 发一条消息，随后清理。把环境变量换成业务后端提供的材料。Alice 和 Bob 必须是不同 UID，且 Bob 已在线。

use serde_json::json;
use wukong_easy_sdk::{Auth, ChannelType, Client, Event, Options};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(
        std::env::var("WK_WS_URL")?,
        Auth::new(std::env::var("WK_UID")?, std::env::var("WK_TOKEN")?),
        Options::default(),
    )?;
    let mut events = client.subscribe();
    let listener = tokio::spawn(async move {
        loop {
            match events.recv().await {
                Ok(Event::Message(message)) => {
                    // 在应用 UI 中展示或保存 message.payload，不记录完整正文。
                    let _ = &message.payload;
                }
                Ok(Event::CustomEvent(event)) => {
                    // event.event_type 和 event.data 由业务协议定义。
                    let _ = (&event.event_type, &event.data);
                }
                Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {
                    // 已丢失事件；通知应用通过业务后端补偿状态。
                    break;
                }
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
                _ => {}
            }
        }
    });
    let result = async {
        client.connect().await?;
        let ack = client.send(
            "bob", ChannelType::Person,
            json!({"type": 1, "content": "你好，Rust 🦀"}),
        ).await?;
        // ack 是服务端发送结果，不是 Bob 已读或业务处理完成。
        let _ = ack;
        Ok::<_, wukong_easy_sdk::Error>(())
    }.await;
    client.destroy().await;
    listener.abort();
    let _ = listener.await;
    result?;
    Ok(())
}

成功的 send 返回 SendResult，包括字符串 message_id、u64 类型的 message_seq 和 reason_code。业务错误返回 Error::Server { code }，保留服务端数值，不把失败响应当成功。不要将 SENDACK 等同于接收、展示或业务完成，详见消息收发。

4. 收发第一条消息

要验证持续双向通信，运行仓库里的终端 example，而不是上面发送后立即退出的程序：

git clone https://github.com/WuKongIM/WuKongEasySDK-Rust.git
cd WuKongEasySDK-Rust
git checkout v0.1.0
cargo build --locked --example chat

由受信开发终端按运行官方示例准备两组 Token，将 Alice 与 Bob 的 device_flag 都设为 2。在两个终端分别运行：

# Alice
WK_WS_URL=ws://127.0.0.1:5200 WK_UID=alice WK_TOKEN=alice-token \
  WK_PEER_UID=bob cargo run --locked --example chat

# Bob
WK_WS_URL=ws://127.0.0.1:5200 WK_UID=bob WK_TOKEN=bob-token \
  WK_PEER_UID=alice cargo run --locked --example chat

两端都显示连接成功后再输入内容。示例会报告服务端接受发送、收到消息和连接状态，避免把消息正文写入日志；应用可以从 Event::Message 中读取 from_uid、Channel 和 Payload。输入 /quit 或 Ctrl-C 清理退出。

5. 清理连接

任务	Rust API 与语义
订阅/取消订阅	`subscribe()` 返回 Tokio broadcast 接收器；drop 接收器取消订阅
并发连接	`connect().await` 共享当前尝试；取消一个 Future 不会取消共享连接
首次失败	返回错误，由应用决定是否再次连接
网络重连	已建立的连接异常断开后，默认最多 5 次指数退避重连，包含抖动
手动断开	`disconnect().await` 取消鉴权、I/O 和重连；之后可再次 connect
账号退出	`destroy().await` 永久关闭所有 clone，并结束订阅任务
最后一个句柄 drop	取消后台连接；需要确认清理完成时显式 await

鉴权拒绝、服务端 disconnect 和手动退出不会自动重连。默认心跳间隔 25 秒，等待 pong 10 秒；连接超时 5 秒，发送总超时 15 秒，写入超时 5 秒。

默认在队列中和等待响应的 SEND 总数不超过 256，超限返回 Backpressure；事件保留 256 条，慢监听器收到 RecvError::Lagged。单个完整 JSON-RPC 报文默认限制 1 MiB，包含 Base64 膨胀。通过 Options 按实际负载调整。

自动 RECVACK 表示网络接收，不表示监听器已处理。即使没有监听器或监听器落后，也会确认接收；EasySDK 没有持久收件箱，需要可靠恢复时由业务层提供存储、去重和补偿。不要忽略 Lagged。

发送不会自动重放。超时、取消或断线时服务端是否接受可能未知；业务决定重试时保留 SendOptions.client_msg_no 并遵循服务端幂等约定。SendOptions 还支持 Header、Setting 和 Topic；red_dot 默认 true，尊重显式 false。群聊使用 ChannelType::Group，成员与权限由后端准备。

6. 常见问题

发送超时或断线后能否直接重发？ 服务端可能已接受，先保留“结果未知”并按 SendOptions.client_msg_no 对账。

监听器收到 Lagged？ 应用消费落后，事件已丢失。停止增长的处理队列并通过业务后端补偿，重连不会自动补历史。

使用私有 CA 时，将 DER 根证书字节加入 Options.additional_root_certificates。最多 16 张，每张不超过 64 KiB，不接收私钥；公共 WebPKI 根仍保留，域名与有效期校验始终启用。

let options = wukong_easy_sdk::Options {
    additional_root_certificates: vec![std::fs::read("company-root.der")?],
    ..Default::default()
};

可选：群聊

可信后端通过 Product HTTP 建群并管理成员。后端确认入群后，使用群 ID 和 ChannelType::Group 发送：

let ack = client.send(
    "project-team",
    wukong_easy_sdk::ChannelType::Group,
    serde_json::json!({"type": 1, "content": "大家好！"}),
).await?;

接收方仍通过 Event::Message 获取消息，检查 channel_type、channel_id、 from_uid 和 payload。SENDACK 表示服务端接受消息，不表示每位成员已经处理。禁止陌生人发送的群中，非成员或已移除成员发送会得到 Error::Server { code: 3 }，被加入黑名单的成员得到原因码 4。应用应处理这些权限错误；成员管理凭证由可信后端保管。

下一步

继续阅读消息收发与上线检查。需要离线恢复、会话、未读或推送时，先查看 SDK 选择。版本与验证记录保留各次验证的完整环境和范围。

Rust 快速接入

本页内容