opgg

Rust 异步客户端，用于访问 OP.GG 提供的英雄统计 API。

crate 封装了常见的接口（英雄元信息、英雄列表、英雄详情），并提供结构化的返回类型，方便在命令行工具、后端服务或数据分析管道中复用。

特性

• 异步请求：基于 reqwest 与 tokio，默认使用 rustls TLS 实现。
• 类型安全：将主要响应字段（如英雄角色、位置、趋势数据等）映射为 Rust 结构体/枚举，减少序列化/反序列化开销。
• 输入校验：在请求前校验 GameMode 与 ChampionPosition 的组合是否合法，防止无效调用。
• 轻量依赖：仅依赖核心网络与序列化库，适合嵌入到现有项目中。

快速开始

在你的 Cargo.toml 中加入：

[dependencies]
opgg = "*"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

示例程序：

use opgg::{ChampionPosition, Client, GameMode};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();

    let meta = client.champion_meta().await?;
    println!("meta version: {}", meta.meta.version);

    let ranked_list = client.champion_list(GameMode::Ranked).await?;
    println!("ranked champions: {}", ranked_list.data.len());

    let info = client
        .champion_info(GameMode::Ranked, 202, ChampionPosition::Top)
        .await?;
    println!("{}", info.data.summary.average_stats.kda);

    Ok(())
}

使用默认构造即可直接访问线上 API；如需自定义 HTTP 客户端（代理、超时等），可通过 Client::builder() 自行配置并注入。

API 概览

• Client::champion_meta()：获取当前数据版本与全局元信息。
• Client::champion_list(mode)：返回指定模式下的英雄概览 Response<Vec<Summary>>，其中 Summary 包含平均胜率、常用位置等字段。
• Client::champion_info(mode, champion_id, position)：获取特定模式、英雄与位置的详细数据 Response<Info>，包括常用出装、符文、技能加点及趋势。

所有接口都会在查询字符串中自动附带 hl=zh_CN，获取中文环境下的数据。

枚举与数据结构

• GameMode：目前支持 Aram 与 Ranked，并提供 allows_position 方法用于校验位置是否合法。
• ChampionPosition：涵盖 Top/Mid/Jungle/Support/ADC/None，用于指定英雄在某模式下的分路。
• champion 模块：定义了 Meta、Summary、Info、Role、Item、Rune 等结构体，可直接访问响应中的细粒度数据。
• Error：统一错误类型，覆盖 URL 构造、HTTP 错误与模式/位置组合错误。

更多字段定义可查看 src/champion.rs。

测试

仓库提供了一个实时集成测试 tests/client_live.rs，用于验证端点是否可用：

cargo test -- --nocapture

⚠️ 该测试会直接请求线上 OP.GG API，需要能够访问外网。运行前请确认网络状况及频率限制，避免触发风控。

如果你只需要验证编译是否通过，可使用：

cargo test --no-run

开发指南

• Client::builder() 返回 reqwest::ClientBuilder，可在此配置代理、超时、连接池等设置。
• 如需扩展更多接口，建议参考 client.rs 中的 get 辅助方法，并复用 Response<T> 类型作为统一响应包装。
• 新增字段时，请同步更新 champion 模块下相关结构体，确保序列化标签 (serde 属性) 与字段名称保持一致。

许可证

本项目采用 MIT 许可证，欢迎在遵循许可条款的前提下自由使用与贡献。