Riven

Riven 是 Riot Games API 的 Rust 库。

Riven 的目标是 速度、可靠性 和 可维护性。Riven 轻松处理速率限制和大型请求。数据结构和端点是自动从 Riot API 参考 (Swagger) 生成的。

设计

• 快速、异步、线程安全。
• 自动重试失败的请求，可配置。
• 支持所有端点，通过 riotapi-schema 保持最新。
• 可编译为 Wasm，用于服务器端或浏览器+代理使用。

用法

use riven::RiotApi;
use riven::consts::PlatformRoute;

// Enter tokio async runtime.
let rt = tokio::runtime::Runtime::new().unwrap();
rt.block_on(async {
    // Create RiotApi instance from key string.
    let api_key = std::env!("RGAPI_KEY"); // "RGAPI-01234567-89ab-cdef-0123-456789abcdef";
    let riot_api = RiotApi::new(api_key);

    // The region.
    let platform = PlatformRoute::NA1;

    // Get account data.
    let account = riot_api.account_v1()
        .get_by_riot_id(platform.to_regional(), "잘 못", "NA1").await
        .expect("Get summoner failed.")
        .expect("There is no summoner with that name.");

    // Print account name#tag.
    println!(
        "{}#{} Champion Masteries:",
        account.game_name.unwrap_or_default(),
        account.tag_line.unwrap_or_default(),
    );

    // Get champion mastery data.
    let masteries = riot_api.champion_mastery_v4()
        .get_all_champion_masteries_by_puuid(platform, &account.puuid).await
        .expect("Get champion masteries failed.");

    // Print champion masteries.
    for (i, mastery) in masteries.iter().take(10).enumerate() {
        println!("{: >2}) {: <9}    {: >7} ({})", i + 1,
            mastery.champion_id.name().unwrap_or("UNKNOWN"),
            mastery.champion_points, mastery.champion_level);
    }
});

输出

잘 못 Champion Masteries:
 1) Riven        1236866 (7)
 2) Fiora         230679 (5)
 3) Katarina      175985 (5)
 4) Lee Sin       156070 (7)
 5) Jax           102662 (5)
 6) Gnar           76373 (6)
 7) Kai'Sa         64271 (5)
 8) Caitlyn        46614 (5)
 9) Irelia         46465 (5)
10) Vladimir       37176 (5)

RiotApi 结构体文档 包含了额外的使用信息。测试用例和 示例代理 提供了更多示例用法。

特性标志

夜间版 vs 稳定版

启用 nightly 特性以使用仅夜间版的功能。这启用了 parking_lot crate 的夜间优化。

riven = { version = "...", features = [ "nightly" ] }

rustls

Riven 使用 reqwest 来发送请求。默认情况下，reqwest 使用本机 TLS 库。如果您想使用 rustls，可以通过关闭 Riven 默认功能并指定 rustls-tls 功能来实现。

riven = { version = "...", default-features = false, features = [ "rustls-tls" ] }

log 或 tracing

如果启用了 tracing 特性，Riven 还能够为请求生成 tracing 跨度。默认情况下，tracing 特性是禁用的，Riven 而是写入 log。

文档

在 docs.rs 上.

错误处理

Riven 返回 futures 中的 Result<T> 或 Result<Option<T>>。

如果 Result 出错，这表明 API 请求未能成功完成，可能是因为用户输入错误、Riot 服务器错误、错误的 API 密钥等。

如果 Option 是 None，这表明请求已成功完成但没有返回数据。这种情况发生在几种情况下，例如获取不存在的账户（通过 name#tag）或匹配（通过 id），或者获取不在游戏中的召唤师的观众数据。具体来说，API 返回了 HTTP 404（或 204）状态码。

Riven 返回的错误类型是 RiotApiError。它提供了一些基本的诊断信息，例如源 reqwest 错误、尝试重试的次数以及 reqwest Response 对象。

默认情况下，Riven 会重试最多 3 次（总共 4 次请求）。一些错误，如 400 客户端错误，不会重试，因为这些错误不可避免地会再次失败。

您可以通过创建一个 RiotApiConfig 实例来配置 Riven，设置所需的配置值，并将其传递给 RiotApi::new（而不是只是 API 密钥）。例如，您可以使用 RiotApiConfig::set_retries(...) 配置 Riven 重试的次数。

语义版本控制

本包在一定程度上遵循语义版本控制。然而，Riot API 本身经常变化且不遵循语义版本控制，这使得事情变得困难。请保持 Riven 的最新状态，因为过时的版本将逐渐停止工作。

当 API 发生变化时，这可能导致 models 模块、endpoints 模块和 consts 模块中的破坏性变化。模型可能会接收新字段（并且，较少的情况下，会删除字段），端点可能会添加或删除，并且可能会添加新的枚举变体。这些破坏性更改将增加 次版本号，而不是主版本号。（major.minor.patch）

Riven 中不依赖于 Riot API 变化的部分也遵循语义版本控制。

额外帮助

如果您对 Riven 有任何疑问或遇到任何问题，请随时 提交问题。

开发

NodeJS用于生成Riven的代码。代码和doT.js模板位于riven/srcgen文件夹中。index.js列出了下载并用于生成代码的JSON文件。

要设置srcgen，首先需要安装NodeJS。然后进入riven/srcgen文件夹，并运行npm ci（或npm install）来安装依赖项。

从仓库根目录运行srcgen，使用node riven/srcgen。