169 lines
5.1 KiB
Markdown
169 lines
5.1 KiB
Markdown
# DingTalk Stream SDK for Rust
|
||
|
||
[](https://crates.io/crates/dingtalk-stream)
|
||
[](https://docs.rs/dingtalk-stream)
|
||
[](LICENSE)
|
||
[](https://www.rust-lang.org)
|
||
|
||
钉钉 Stream 模式 SDK 的 Rust 实现，完整对齐 Python 版 [dingtalk-stream-sdk-python](https://github.com/open-dingtalk/dingtalk-stream-sdk-python)。
|
||
|
||
> 对齐的 Python SDK 版本: commit [`6381a7b`](https://github.com/open-dingtalk/dingtalk-stream-sdk-python/commit/6381a7bacb0353e1e0cd425688a02ff785fda44c)
|
||
|
||
## 功能特性
|
||
|
||
- 基于 WebSocket 的钉钉 Stream 协议连接（自动重连、60s Keepalive）
|
||
- 聊天机器人消息收发（文本、Markdown、卡片）
|
||
- 交互式卡片（Markdown / AI 流式 / 按钮 / 轮播 / RPA 插件）
|
||
- Graph API 支持
|
||
- 事件订阅
|
||
- OAuth2 Token 自动管理（带缓存与 5 分钟提前刷新）
|
||
- 统一 async/await（基于 tokio）
|
||
|
||
## 快速开始
|
||
|
||
将依赖添加到 `Cargo.toml`：
|
||
|
||
```toml
|
||
[dependencies]
|
||
dingtalk-stream = "0.1"
|
||
```
|
||
|
||
最小示例：
|
||
|
||
```rust
|
||
use async_trait::async_trait;
|
||
use dingtalk_stream::*;
|
||
|
||
struct MyHandler;
|
||
|
||
#[async_trait]
|
||
impl CallbackHandler for MyHandler {
|
||
async fn process(&self, message: &messages::frames::MessageBody) -> (u16, String) {
|
||
println!("Received: {}", message.data);
|
||
(AckMessage::STATUS_OK, "OK".to_owned())
|
||
}
|
||
}
|
||
|
||
fn main() {
|
||
let credential = Credential::new("your_client_id", "your_client_secret");
|
||
let handler = MyHandler;
|
||
|
||
let mut client = DingTalkStreamClient::builder(credential)
|
||
.register_callback_handler(ChatbotMessage::TOPIC, handler)
|
||
.build();
|
||
|
||
client.start_forever().unwrap();
|
||
}
|
||
```
|
||
|
||
更多示例见 [`examples/`](examples/) 目录。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── lib.rs # 公共 API 导出
|
||
├── client.rs # DingTalkStreamClient + Builder
|
||
├── credential.rs # Credential（Debug 遮蔽 secret）
|
||
├── error.rs # 统一错误类型
|
||
├── handlers/ # Handler traits (Callback/Event/System/Chatbot/Graph)
|
||
├── messages/ # 消息类型 (Frames/Chatbot/CardCallback/Graph)
|
||
├── card/ # 卡片系统 (Replier/Instances/Templates)
|
||
└── transport/ # 传输层 (HTTP/Token/WebSocket)
|
||
```
|
||
|
||
## 文档
|
||
|
||
- [整体架构图](docs/architecture.md)
|
||
- [连接生命周期时序图](docs/connection-lifecycle.md)
|
||
- [卡片操作时序图](docs/card-operations.md)
|
||
|
||
## 端到端测试
|
||
|
||
1. 复制配置模板并填入凭证：
|
||
```bash
|
||
cp examples/secret.example.toml examples/secret.toml
|
||
# 编辑 examples/secret.toml，填入 client_id 和 client_secret
|
||
```
|
||
|
||
2. 运行测试机器人：
|
||
```bash
|
||
cargo run --example e2e_test
|
||
```
|
||
|
||
3. 带媒体下载测试：
|
||
```bash
|
||
cargo run --example e2e_test -- --download-dir /tmp/dingtalk_downloads
|
||
```
|
||
|
||
4. 通过钉钉向机器人发送消息测试：
|
||
- `ping` → 回复 pong
|
||
- `echo <text>` → 回声
|
||
- `card` → 发送 Markdown 卡片
|
||
- `info` → 显示消息详情
|
||
|
||
## 与 Python SDK 的设计差异
|
||
|
||
| Python | Rust | 说明 |
|
||
|---|---|---|
|
||
| sync + async 双版本 | 统一 async | 消除代码重复 |
|
||
| 类继承 | Trait + 组合 | Rust 惯用模式 |
|
||
| ThreadPoolExecutor | tokio::spawn | 更高效的异步调度 |
|
||
| dict 动态类型 | 强类型 struct + serde | 编译期类型安全 |
|
||
|
||
## Rust SDK 独有功能
|
||
|
||
以下功能为 Rust SDK 独有，Python SDK 中不存在。同步 Python SDK 时请勿删除（代码中均有 `Rust SDK exclusive` 标注）。
|
||
|
||
### 扩展消息类型
|
||
|
||
Rust SDK 支持解析钉钉机器人可接收的全部 6 种消息类型，Python SDK 仅支持 text / richText / picture：
|
||
|
||
| 消息类型 | 结构体 | 场景限制 |
|
||
|---------|--------|---------|
|
||
| audio 语音 | `AudioContent` | 仅单聊 |
|
||
| file 文件 | `FileContent` | 仅单聊 |
|
||
| video 视频 | `VideoContent` | 仅单聊 |
|
||
|
||
```rust
|
||
let msg = ChatbotMessage::from_value(&json)?;
|
||
if let Some(fc) = &msg.file_content {
|
||
println!("文件名: {:?}, 下载码: {:?}", fc.file_name, fc.download_code);
|
||
}
|
||
```
|
||
|
||
### 统一下载码提取
|
||
|
||
`get_all_download_codes()` 一次性获取消息中所有媒体的下载码，覆盖 picture / richText 图片 / audio / file / video：
|
||
|
||
```rust
|
||
for (media_type, download_code) in msg.get_all_download_codes() {
|
||
let url = replier.get_image_download_url(&download_code).await?;
|
||
let bytes = replier.download_bytes(&url).await?;
|
||
}
|
||
```
|
||
|
||
### 文件下载
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `download_bytes(url)` | 下载文件字节内容 |
|
||
| `download_bytes_with_limit(url, max_size)` | 带大小限制的流式下载（Content-Length 预检 + 累计检查） |
|
||
|
||
### 主动单聊消息
|
||
|
||
`send_oto_message()` 通过 OpenAPI 向指定用户发送单聊消息（对应 `POST /v1.0/robot/oToMessages/batchSend`）：
|
||
|
||
```rust
|
||
replier.send_oto_message(user_id, "sampleText", r#"{"content":"hello"}"#).await?;
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Rust ≥ 1.85.0（edition 2024）
|
||
- tokio 异步运行时
|
||
|
||
## License
|
||
|
||
MIT
|