lark_bot_sdk

飞书/Lark的开放接口Rust SDK，参考go sdk lark。

特点

• 支持Mock以支持测试
• 支持UserAccessToken
• 支持流式上传下载
• 详细的注释

安装

为了加快编译速度，参照go sdk lark，sdk根据接口功能聚合成不同的service，每个service对应一个feature，如果要使用对应的api接口，请启用对应的feature。(默认启用了message)

[dependencies]
lark_bot_sdk = { version = "0.1", features = ["message", "ai",...] }

查询api方法参考: cargo doc (ctrl + shift + f)

使用

创建Lark客户端

let lark = Lark::new("<APP_ID>", "<APP_SECRET>");

client可复用，所以一般来说实例化一次client即可。

fn client() -> &'static DefaultLarkClient {
    static CLIENT: OnceLock<DefaultLarkClient> = OnceLock::new();

    CLIENT.get_or_init(|| Lark::new("<APP_ID>", "<APP_SECRET>"))
}

配置Lark客户端

使用LarkBuilder配置客户端，具体参数参见:参数。

let client = LarkBuilder::default()
    .timeout(Duration::from_secs(10))
    .is_isv(false)
    .normal()
    .build(dotenv!("app_id"), dotenv!("app_secret"));

let custom_client = LarkBuilder::default().build_with_store_and_client(
    RWStoreMemory::default(),
    DefaultClient::default(),
    dotenv!("app_id"),
    dotenv!("app_secret"),
);

具体代码参见:./examples/build_client.rs

例子: 发送消息

api的调用格式为client.{service}.{func}。发送消息的方法为send_raw_message，属于message service下，所以调用方法为

let req = SendRawMessageReq {
    receive_id_type: "open_id".to_owned(),
    receive_id: "".to_owned(),
    msg_type: "text".into(),
    content: "{\"text\":\"test content\"}".into(),
    ..Default::default()
};
client().message().send_raw_message(req).await;

具体代码参见:./examples/send_message.rs

例子: 上传api

上传接口需要传递buffer类型的数据。

let file = tokio::fs::File::open("test.jpg").await.unwrap();
let buffer = tokio::io::BufReader::new(file);
let req = UploadFileReq {
    file_name: "test.jpg".into(),
    file_type: "stream".into(),
    duration: None,
    data: buffer,
};
client().file().upload_file(req).await;

具体代码参见:./examples/upload_file.rs

例子: 下载api

下载接口会返回一个stream。

let req = DownloadFileReq {
    file_key: dotenv!("download_file_id").into(),
};
let res = client().file().download_file(req).await.unwrap();
let mut file = tokio::fs::File::create("test.jpg").await.unwrap();
while let Some(data) = resp.data.next().await {
    file.write_all(&data.unwrap()).await.unwrap();
}

具体代码参见:./examples/download_file.rs

例子: 原生api调用

有些老版本的开放接口，不能生成结构化的API，导致SDK内无法提供结构化的使用方式，这时可使用原生模式进行调用

#[derive(Debug, Serialize, Deserialize, Clone, Default)]
struct ReqBody {
    name: String,
}

#[derive(Debug, Serialize, Deserialize, Clone, lark_macros::ApiBaseResp)]
struct Resp {
    #[serde(flatten)]
    pub data: Option<String>,
    #[serde(flatten)]
    pub base: BaseResp,
}
#[tokio::main]
async fn main() {
    let req = ApiRequest {
        param_data: ReqParam {
            body: Some(ReqBody {
                name: "test".into(),
            }),
            ..Default::default()
        },
        ..Default::default()
    };
    client().do_req::<_, Resp>(req).await.ok();
}

提示：可以使用宏简化构建参数过程，具体使用方法请参考示例和文档。

具体代码参见：./examples/do_req.rs

Mock方法

sdk支持Mock以支持测试。要使用mock方法，需要启用test-util feature。为了避免mock代码对正常逻辑的影响，要在dev-dependencies中开启测试feature。

[dev-dependencies]
lark_bot_sdk = { version = "0.1", features = ["test-util"] }

当前mock支持times（最大mock次数）和when（mock生效条件）功能。使用变量的生命周期绑定mock生效时间，在函数结束后mock自动解除。

! 使mock生效必须调用build方法。在mock范围内再次mock相同函数会导致panic。

普通方法mock

在创建client后，使用client.{service}.{service}.mock().mock_{func_name}即可获取对应的mocker实例

let _mocker = client()
    .message()
    .mock()
    .mock_send_raw_message(|_| {
        Ok((
            SendRawMessageResp {
                data: MessageSubResp {
                    message_id: "test".into(),
                    ..Default::default()
                },
            },
            CommonResponse::default(),
        ))
    })
    .times(2)
    .when(|req| req.receive_id == "1")
    .build();

具体代码参见:./examples/mock_send_message.rs

原生API调用Mock

原生API的Mock方法相对特殊。Mock方法的原理为每个类型生成一个对应的mocker。如果需要防止相同的函数类型相互覆盖（比如两个方法A、B的输入输出共用相同的结构体，如果不做区分的话那么方法A的mock会覆盖方法B的mock），在mock时需要提供一个额外的marker类型

let _mocker = client()
        .mock()
        .mock_do_marker_req::<A, _, _>(|req| {
            Ok((
                Resp {
                    data: Some(req.param_data.body.unwrap()),
                    base: BaseResp::default(),
                },
                Default::default(),
            ))
        })
        .build();

let req = ApiRequest {
    param_data: ReqParam {
        body: Some("req_body".to_string()),
        ..Default::default()
    },
    ..Default::default()
};

assert!(client().do_marker_req::<A, _, Resp>(req.clone()).await.is_ok());
// B 类型的调用不生效
assert!(client().do_marker_req::<B, _, Resp>(req.clone()).await.is_err());

具体代码参见: ./examples/mock_do_req.rs

待办事项

• 常用接口封装
• 处理事件回调
• 事件回调支持WebSocket
• 消息卡片支持
• 旧API生成
• API自动更新

鸣谢

• chyroc/lark