Frankenstein

Rust 的 Telegram 机器人 API 客户端。

它是 Telegram 机器人 API 的完整封装，并更新到 API 的 7.9 版本。

Frankenstein 的数据结构（Rust 结构体和枚举）与 Telegram 机器人 API 对象和方法参数一一对应。

安装

运行 cargo add frankenstein 或将以下内容添加到您的 Cargo.toml 文件中。

[dependencies]
frankenstein = "0.32"

功能

默认功能

• http-client - 一个阻塞式 HTTP 客户端（使用 ureq），它是唯一默认功能
• telegram-trait - 一个阻塞式 API 特性，它包含在 http-client 功能中。对于想要创建自定义阻塞客户端（例如，替换 HTTP 客户端）的人来说可能很有用

可选功能

• async-http-client - 一个异步 HTTP 客户端，它使用 reqwest，默认情况下是禁用的
• async-telegram-trait - 一个异步 API 特性，它用于 async-http-client。对于想要创建自定义异步客户端的人来说可能很有用

要使用异步客户端，请将以下行添加到您的 Cargo.toml 文件中

frankenstein = { version = "0.32", default-features = false, features = ["async-http-client"] }

您也可以禁用所有功能。在这种情况下，crate 只会提供 Telegram 类型。

frankenstein = { version = "0.32", default-features = false }

用法

本节中的示例使用阻塞式客户端（frankenstein::Api），但异步示例的格式相同（只需将 frankenstein::Api 替换为 frankenstein::AsyncApi 即可）

数据结构

API 文档中描述的所有对象在 Frankenstein 中都有直接对应项。例如，在文档中存在用户类型

id	Integer	Unique identifier for this user or bot. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier.
is_bot	Boolean	True, if this user is a bot
first_name	String	User's or bot's first name
last_name	String	Optional. User's or bot's last name
username	String	Optional. User's or bot's username
language_code	String	Optional. IETF language tag of the user's language
can_join_groups	Boolean	Optional. True, if the bot can be invited to groups. Returned only in getMe.
can_read_all_group_messages	Boolean	Optional. True, if privacy mode is disabled for the bot. Returned only in getMe.
supports_inline_queries	Boolean	Optional. True, if the bot supports inline queries. Returned only in getMe.

在 Frankenstein 中描述如下

pub struct User {
    pub id: u64,
    pub is_bot: bool,
    pub first_name: String,
    pub last_name: Option<String>,
    pub username: Option<String>,
    pub language_code: Option<String>,
    pub can_join_groups: Option<bool>,
    pub can_read_all_group_messages: Option<bool>,
    pub supports_inline_queries: Option<bool>,
}

可选字段用Option表示。

每个结构体都可以使用关联的构建器创建。只需设置必需的字段，如果未提供，可选字段将设置为None

let send_message_params = SendMessageParams::builder()
    .chat_id(message.chat.id)
    .text("hello")
    .reply_to_message_id(message.message_id)
    .build();

对于 API 参数，使用相同的方法。参数的唯一区别是 Frankenstein 中的结构体名称以Params后缀结尾。

例如，leaveChat方法的参数

pub struct LeaveChatParams {
    chat_id: ChatId,
}

发起请求

要向 Telegram 机器人 API 发送请求，请初始化Api结构体。

use frankenstein::Api;
use frankenstein::TelegramApi;

...

let token = "My_token";
let api = Api::new(token);

然后使用此 API 对象向 Bot API 发送请求

let update_params = GetUpdatesParams::builder()
    .allowed_updates(vec![AllowedUpdate::Message])
    .build();

let result = api.get_updates(&update_params);

每个函数都返回一个包含成功响应或失败响应的Result枚举。

在examples目录中查看完整的示例。

上传文件

API 中的一些方法允许上传文件。在 Frankenstein 中，对于此类文件，使用FileUpload枚举

pub enum FileUpload {
    InputFile(InputFile),
    String(String),
}

pub struct InputFile {
    path: std::path::PathBuf
}

它有两个变体

• FileUpload::String用于传递已上传文件的 ID
• FileUpload::InputFile用于使用多部分上传上传新文件。

自定义 HTTP 客户端

可以使用它们的构建器自定义异步（reqwest）和阻塞（ureq）HTTP 客户端。

自定义阻塞客户端

use frankenstein::ureq;
use frankenstein::Api;
use std::time::Duration;

let request_agent = ureq::builder().timeout(Duration::from_secs(100)).build();
let api_url = format!("{}{}", BASE_API_URL, TOKEN);

Api::builder()
     .api_url(api_url)
     .request_agent(request_agent)
     .build()

自定义异步客户端

use frankenstein::reqwest;
use frankenstein::AsyncApi;
use std::time::Duration;

let client = reqwest::ClientBuilder::new()
    .connect_timeout(Duration::from_secs(100))
    .timeout(Duration::from_secs(100))
    .build()
    .unwrap();
let api_url = format!("{}{}", BASE_API_URL, TOKEN);

AsyncApi::builder().api_url(api_url).client(client).build()

文档

Frankenstein 实现了所有 Telegram 机器人 API 方法。要查看应传递哪些参数，请检查docs.rs

您可以使用此库查看使用此库创建的实际机器人

• El Monitorro - RSS/Atom/JSON 源订阅阅读器。
• subvt-telegram-bot - 用于 Polkadot 和 Kusama 验证者的 Telegram 机器人。
• wdr-maus-downloader - 检查 WDR Maus 的新剧集并将其下载。
• weather_bot_rust - 提供全球天气信息的 Telegram 机器人。

替换默认 HTTP 客户端

库默认使用ureq HTTP 客户端，但可以轻松替换为任何选择的 HTTP 客户端。

ureq自带默认功能（impl）。因此，应该禁用该功能。

frankenstein = { version = "0.32", default-features = false, features = ["telegram-trait"] }

然后为您的 HTTP 客户端实现TelegramApi特质，该特质需要两个函数

• request_with_form_data用于上传文件
• request用于没有文件上传的请求

您可以在ureq 的默认 TelegramApi 特质实现中查看。

此外，您还可以查看examples目录中的isahc HTTP 客户端的实现。

没有默认的ureq实现，frankenstein只有一个依赖项 - serde。

贡献

1. 进行分支操作！
2. 创建您的功能分支（git checkout -b my-new-feature）
3. 提交您的更改（git commit -am '添加一些功能'）
4. 推送到分支（git push origin my-new-feature）
5. 创建新的拉取请求

作者

Ayrat Badykov (@ayrat555)