opgg 0.1.0

# opgg

Rust 异步客户端，用于访问 [OP.GG](https://op.gg) 提供的英雄统计 API。

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

---

## 特性

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

## 快速开始

在你的 `Cargo.toml` 中加入：

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

示例程序：

```rust
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`，用于验证端点是否可用：

```bash
cargo test -- --nocapture
```

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

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

```bash
cargo test --no-run
```

## 开发指南

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

## 许可证

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