serenity

Serenity是一个针对Discord API的Rust库。

查看如何使用Serenity API的示例。要创建具有slash命令或文本命令的机器人，请参阅在Serenity之上构建的poise框架。要发送和接收语音通道中的数据，请参阅songbird库。

Serenity支持通过使用Client::builder进行机器人登录。

您还可以通过使用validate_token在登录前检查您的令牌。

登录后，您可以通过实现一个特质，如EventHandler::message，将处理器添加到您的客户端以分发Event。这将导致在接收到Event::MessageCreate时调用您的处理器。每个处理器都提供了一个Context，其中包含有关事件的信息。请参阅客户端的模块级文档。

库透明地处理了Shard，消除了不必要的复杂性。分片连接会自动为您处理。有关更多信息，请参阅网关的文档。

还提供了一个 Cache。当从 Discord API 通过事件接收数据时，它将自动为您更新。在调用 Context 的方法时，缓存将首先搜索相关数据，以避免对 Discord API 进行不必要的 HTTP 请求。有关更多信息，请参阅缓存的模块级文档。

请注意，尽管本文档将努力保持最新和准确，但 Discord 提供了官方文档。如果您需要确保某些信息准确无误，请参考他们的文档。

示例机器人

一个基本的ping-pong机器人的样子

use std::env;

use serenity::async_trait;
use serenity::model::channel::Message;
use serenity::prelude::*;

struct Handler;

#[async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!ping" {
            if let Err(why) = msg.channel_id.say(&ctx.http, "Pong!").await {
                println!("Error sending message: {why:?}");
            }
        }
    }
}

#[tokio::main]
async fn main() {
    // Login with a bot token from the environment
    let token = env::var("DISCORD_TOKEN").expect("Expected a token in the environment");
    // Set gateway intents, which decides what events the bot will be notified about
    let intents = GatewayIntents::GUILD_MESSAGES
        | GatewayIntents::DIRECT_MESSAGES
        | GatewayIntents::MESSAGE_CONTENT;

    // Create a new instance of the Client, logging in as a bot.
    let mut client =
        Client::builder(&token, intents).event_handler(Handler).await.expect("Err creating client");

    // Start listening for events by starting a single shard
    if let Err(why) = client.start().await {
        println!("Client error: {why:?}");
    }
}

完整示例

完整示例，详细说明了库的基本功能的使用方法，可以在 examples 目录中找到。

安装

将以下内容添加到您的 Cargo.toml 文件中

[dependencies]
serenity = "0.12"
tokio = { version = "1.21.2", features = ["macros", "rt-multi-thread"] }

MSRV 策略

Serenity 的最低支持 Rust 版本 (MSRV) 是 Rust 1.74。

我们选择在 current 分支上保持 MSRV 稳定。这意味着它将在小版本发布之间保持不变。偶尔，依赖项可能会违反 SemVer 并以破坏性的方式更新其 MSRV。因此，需要将其版本锁定以成功使用较旧的 Rust 版本构建 Serenity。

next 分支跟踪最新的 Rust 发布作为其 MSRV。这允许在新的语言功能稳定后快速开发，并在长期内减少技术债务。当发布新的大版本时，current 上的 MSRV 将更新到 next 的版本，并且我们将承诺支持该 MSRV，直到下一个主要版本。

功能

可以通过通过 Cargo.toml 配置库来启用或禁用功能

[dependencies.serenity]
default-features = false
features = ["pick", "your", "feature", "names", "here"]
version = "0.12"

默认功能包括：builder、cache、chrono、client、framework、gateway、http、model、standard_framework、utils 和 rustls_backend。

还有这些替代默认功能，需要设置 default-features = false

• default_native_tls：使用 native_tls_backend 而不是默认的 rustls_backend。
• default_no_backend：排除默认后端，选择自己的后端。

如果您不确定选择哪一个，请使用默认功能，不设置 default-features = false。

以下是一个功能的全列表

• builder：与模型方法一起使用的构建器。
• cache：缓存将存储有关公会、频道、用户和其他数据的信息，以避免执行 REST 请求。如果您内存不足，请勿启用此功能。
• collector：收集器等待事件，例如接收用户的消息或消息上的反应，并允许以方便的方式响应对事件。收集器可以配置为强制执行事件必须满足的某些标准。
• client：一个用于碎片和事件处理程序的管理器，抽象化了处理碎片事件和（如果启用）更新缓存的工作。
• framework：启用框架，这是一个实用工具，允许简单的命令解析、命令执行前/后的处理、前缀设置等。
• 网关：一个分片，用作与Discord网关通过WebSocket客户端进行通信的高级接口。
• http：提供在足够低级别上包装Discord REST API的功能，可以通过JsonMap随意提供可选参数。
• 模型：模型实现的方法，作为HTTP函数的辅助方法。
• 标准框架：框架的标准、默认实现。注意：从v0.12.1版本开始已弃用。建议使用poise框架。
• utils：为用户提供的常见用例的实用函数。
• voice：使客户端能够注册一个语音插件，该插件将处理来自Discord的实际语音连接。《a href="https://gitlab.com/vicky5124/lavalink-rs/" rel="ugc noopener">lavalink-rs》或《a href="https://github.com/serenity-rs/songbird" rel="ugc noopener">Songbird》是推荐的语音插件。
• default_native_tls：默认功能，但使用native_tls_backend而不是rustls_backend。
• tokio_task_builder：启用tokio的tracing功能，并使用tokio::task::Builder在设置RUSTFLAGS="--cfg tokio_unstable"时创建带名称的任务。
• unstable_discord_api：启用不具有稳定界面的Discord API功能。这些功能可能没有官方文档或可能发生变化。
• simd_json：如果目标CPU架构支持，则启用SIMD加速的JSON解析和渲染API调用。
• temp_cache：启用通过HTTP API检索数据的函数中的临时缓存。
• chrono：使用chrono crate来表示时间戳。如果禁用，则使用time crate。
• interactions_endpoint：启用与Discord的Interactions Endpoint URL功能相关的工具。

要启用代码库的所有部分，请使用"full"功能。

对于可能更详细的信息，请检查Cargo.toml。

Serenity提供两个TLS后端，默认为rustls_backend，如果您不使用默认功能，则需要选择一个。

• rustls_backend：在所有平台上使用Rustls，这是一个纯Rust TLS实现。
• native_tls_backend：在Windows上使用SChannel，在macOS上使用Secure Transport，在其他平台上使用OpenSSL。

如果您想要所有默认功能，但不包括cache（例如），您可以列出所有其他功能。

[dependencies.serenity]
default-features = false
features = [
    "builder",
    "chrono",
    "client",
    "framework",
    "gateway",
    "http",
    "model",
    "standard_framework",
    "utils",
    "rustls_backend",
]
version = "0.12"

依赖项

如果您使用native_tls_backend并且您不是在macOS或Windows上开发，您将需要

• openssl

托管

如果您想快速轻松地托管您的机器人，可以使用shuttle，这是一个Rust原生云开发平台，允许免费部署Serenity机器人。

扩展Serenity的项目

• lavalink-rs：到Lavalink和Andesite的接口，一个基于Lavaplayer的音频发送节点
• Songbird：一个用于Discord语音API的异步Rust库。
• Poise：实验性的命令框架，具有高级功能，如编辑跟踪、单功能斜杠和前缀命令以及灵活的参数解析。