Coordinate SDK 技术解析

1. 系统概述

Coordinate SDK 是 Coordinate 项目的客户端开发工具包，采用纯 Rust 实现，旨在为开发者提供便捷的 API 来接入 Coordinate 协作平台。

从架构层面来看，SDK 依赖两个核心组件：coordinate-core 提供共享的数据模型和参数定义，coordinate-connector 实现 MQTT 协议（基于 WebSocket 和 RustTLS）。这种分层设计确保了代码的可维护性和复用性。

从功能定位角度来看，SDK 主要承担三类职责：第一是作为 HTTP API 客户端，封装 RESTful 调用，提供简洁的异步接口；第二是作为 MQTT 客户端，维护实时连接和事件推送；第三是作为本地存储管理器，提供 SQLite 缓存支持。

2. 核心特性

2.1 连接与传输

SDK 支持两种 MQTT 连接方式：MQTT over WebSocket（默认端口 8000）和 MQTT over WSS/TLS（默认端口 443）。连接配置通过 ConnectOptions 结构体定义：

rust 复制代码

pub struct ConnectOptions {
    pub id: String,
    pub endpoint: (String, u16),
    pub username: String,
    pub password: String,
}

MQTT 连接参数包括 5 秒 Keep-Alive 间隔、最大 1000 条飞行中消息限制、以及 100KB 最大包大小。在 mqtt_options 方法中通过 MqttOptions::set_last_will 配置遗嘱消息，用于异常掉线时通知其他客户端，便于实现用户在线状态管理。

2.2 事件回调机制

SDK 实现了灵活的事件回调接口，开发者可以通过实现 BroadcastCallback trait 来处理各类实时事件：

rust 复制代码

pub trait BroadcastCallback: Send + Sync {
    fn on_connecting(&self) {}
    fn on_unauthorized(&self, reason: String) {}
    fn on_connected(&self) {}
    fn on_net_broken(&self, reason: String) {}
    fn on_kick_out(&self, reason: String) {}
    fn on_event(&self, event: BroadcastEvent) -> bool { false }
    fn on_unknown_event(&self, event: Vec<u8>, reason: String) {}
}

事件类型覆盖了消息收发、频道变更、用户状态、反应表情等协作场景。这种设计使得开发者可以专注于业务逻辑，无需关心底层协议细节。

2.3 本地存储

SDK 内置 SQLite 本地存储支持，通过 ClientStore 结构体提供用户、文件和频道的缓存能力。这种设计在网络不可用时仍能提供基本的功能体验。

2.4 错误处理

统一的错误类型定义简化了问题排查：

rust 复制代码

pub enum ClientError {
    Err(String),
    Permission(String),
    BadParams(String),
    DBNotFound(String),
    IoError(std::io::Error),
    JsonError(serde_json::Error),
    HTTP(String),
    Forbidden(String),
    TokenExpired(String),
    MQTTError(coordinate_connector::ClientError),
    SqlxError(sqlx::Error),
}

3. API 概览

SDK 提供了完整的 REST API 封装，涵盖认证、用户、频道、消息、团队和媒体等功能模块。所有 API 调用都支持 async/await 模式。

3.1 认证模块

rust 复制代码

let auth_info = auth::login(
    "http://localhost:8065",
    "username",
    "password",
    "device-id",
).await?;

登录成功后返回用户信息、访问令牌、MQTT 服务器地址和 CSRF 令牌。

3.2 消息收发

rust 复制代码

let req = CreatePostReq {
    message: "Hello World".to_string(),
    channel_id: 123,
    // ...
};

post::create_post("http://localhost:8065", token, args, req).await?;

3.3 文件上传

SDK 支持带进度回调的文件上传，通过实现 UploadCallback 接口可以监听上传进度：

rust 复制代码

let attachment = Attachment {
    file_path: "/path/to/file.pdf".to_string(),
    channel_id: 123,
    file_name: "document.pdf".to_string(),
};

media::upload_file(endpoint, token, attachment, Arc::new(MyUploadCallback::new())).await?;

3.4 文件下载

SDK 支持带进度回调的文件下载，通过实现 DownloadCallback 接口可以监听下载进度：

rust 复制代码

let file_info = FileInfo {
    id: "file-123".to_string(),
    name: "document.pdf".to_string(),
    channel_id: 123,
};

media::download_file(endpoint, token, file_info, Arc::new(MyDownloadCallback::new())).await?;

3.6 API 模块总览

模块	文件路径	功能
auth	`/src/api/auth.rs`	登录、登出、创建用户、密码重置
user	`/src/api/user.rs`	获取用户、搜索、用户统计、线程管理
channel	`/src/api/channel.rs`	频道 CRUD、成员管理、搜索
team	`/src/api/team.rs`	团队 CRUD、成员管理
post	`/src/api/post.rs`	消息发布、获取、删除
file	`/src/api/file.rs`	获取文件信息
media	`/src/api/media.rs`	文件上传下载（带进度回调）
reaction	`/src/api/reaction.rs`	消息反应（emoji）

4. 使用示例

4.1 建立 MQTT 连接

rust 复制代码

let opts = ConnectOptions {
    id: "client-123".to_string(),
    endpoint: ("localhost".to_string(), 8000),
    username: "user".to_string(),
    password: "pass".to_string(),
};

let client = Client::connect(
    opts,
    None,  // 可选的 CA 证书
    Arc::new(MyCallback::new()),
).await;

4.2 处理实时事件

在连接成功后，开发者可以订阅各类实时事件。SDK 会通过回调接口推送 BroadcastEvent，包括新消息、消息编辑、消息删除、频道变更、用户加入离开、反应表情等。

4.3 消息链路

SDK 采用混合模式处理消息：发送消息通过 HTTP API，接收消息通过 MQTT 订阅。

flowchart LR subgraph Client ["客户端 SDK"] direction TB HTTP["HTTP POST
/api/v4/posts"] MQTT["MQTT 订阅
/channels/{id}"] end subgraph Server ["coordinate-server"] HTTP_API["HTTP :8065"] MQTT_CLIENT["MQTT 客户端
→ broadcast"] end subgraph Broadcast ["coordinate-broadcast"] WS["WebSocket :8000"] end HTTP -->|发送消息| HTTP_API HTTP_API -->|发布| MQTT_CLIENT MQTT_CLIENT -->|MQTT| WS WS -->|推送| MQTT

bash 复制代码

发送消息: 客户端 → HTTP POST /api/v4/posts → coordinate-server → coordinate-broadcast → 订阅者
接收消息: coordinate-broadcast (MQTT) → 客户端回调 on_event()

发送流程：

客户端调用 post::create_post 发送 HTTP POST 请求到 coordinate-server
coordinate-server 处理业务逻辑后，通过 MQTT 客户端发布到 coordinate-broadcast
coordinate-broadcast 根据主题将消息推送给订阅者

接收流程：

客户端连接成功后，由服务端动态管理订阅（增加/移除频道订阅）
当有消息发布到订阅主题时，SDK 通过 BroadcastCallback::on_event 回调通知客户端
开发者可以在回调中处理 BroadcastEvent::Posted 等事件类型

5. 技术规格

指标	规格
支持语言	Rust（规划支持多语言：WASM via wasm-bindgen，其他 via uniffi_bindgen）
传输协议	MQTT over WebSocket, MQTT over WSS
HTTP 客户端	reqwest
本地存储	SQLite (sqlx)
异步运行时	tokio

6. 设计模式总结

6.1 架构模式

系统采用以下架构模式实现高性能和易用性：

生产者-消费者模式：应用程序作为生产者，通过 API 调用发送请求；SDK 作为消费者，处理请求并返回结果。这种模式解耦了业务逻辑和网络通信。

事件驱动模式：MQTT 连接基于事件驱动，开发者通过实现回调接口来处理各类事件。这种模式使得异步编程更加直观。

6.2 扩展性设计

系统提供了良好的扩展性支持：通过 wasm-bindgen 支持 WebAssembly，通过 uniffi_bindgen 支持其他多语言绑定，可用于 Bot 开发；通过回调接口可以自定义事件处理逻辑；通过 ConnectOptions 可以灵活配置连接参数。

7. 适用场景

场景	说明
Bot 开发	开发自动化机器人接入平台（规划支持多语言）
桌面客户端开发	基于 SDK 开发自定义桌面客户端
服务端集成	服务端应用程序通过 SDK 调用 API
数据分析	通过 SDK 获取数据进行分析

8. 总结

Coordinate SDK 提供了一套完整、易用的客户端开发方案。其特性包括：完整的 REST API 封装、MQTT 实时消息推送、灵活的事件回调机制、本地 SQLite 存储、以及统一的错误处理。对于需要集成 Coordinate 协作能力的应用，直接使用 SDK 是推荐的选择。

源码位于 coordinate-sdk/ 目录，核心文件包括 src/lib.rs（入口）、src/client/mod.rs（MQTT 客户端）、src/api/（各功能模块）和 src/callback.rs（回调接口）。