Bangumi API Rust 客户端 (bangumi-api)

一个现代、异步的 Bangumi API Rust 客户端库。

本项目基于 tokio 和 reqwest 构建，提供了一套完整的强类型数据模型，让您能以类型安全、符合人体工程学的方式与 Bangumi API 进行交互。

✨ 特性

• 完全异步: 基于 async/await 和 tokio 运行时，提供非阻塞 I/O。
• 强类型模型: 为所有 API 的请求和响应提供了完整的 serde 序列化/反序列化数据结构。
• 全面的 API 覆盖: 封装了大部分 V0 版本的 API，包括：
  • User: 用户信息
  • Subject: 条目（动画、书籍、音乐、游戏、三次元）
  • Character: 角色
  • Person: 人物（声优、制作人等）
  • Collection: 收藏管理
  • Episode: 章节
  • Index: 目录
  • Revision: 修订历史
• 简洁的调用方式: 统一的 BangumiClient 入口，链式调用构建请求。
• 统一的错误处理: 将 Bangumi API 返回的错误信息解析为 BangumiError 结构体，方便调试。
• 自带测试: 包含覆盖了大部分 API 端点的单元测试。

📦 安装

将此库添加到您的 Cargo.toml 文件中：

[dependencies]
bangumi-api = "0.1.0" # 请使用 crates.io 上的最新版本
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

🚀 快速开始

以下示例展示了如何使用 bangumi-api。

1. 实例化客户端

对于访问公开数据，可以直接使用默认客户端。

use bangumi_api::common::model::BangumiClient;

let client = BangumiClient::default();

如果需要访问需要授权的接口（如收藏、查看个人信息等），您需要在初始化客户端时提供 access_token。

use bangumi_api::common::model::BangumiClient;

let my_token = "YOUR_ACCESS_TOKEN".to_string();

let auth_client = BangumiClient::new(
    "https://api.bgm.tv".to_string(), // 默认 API 地址
    None, // 使用默认 User-Agent
    Some(my_token),
);

提示: 建议从环境变量或配置文件中读取 access_token，避免硬编码在代码中。

2. 调用 API

所有 API 方法都作为 BangumiClient 的方法提供。

use bangumi_api::common::model::BangumiClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // --- 调用公开 API (无需授权) ---
    let client = BangumiClient::default();

    // 获取条目详情 (ID: 2 -> "AIR")
    match client.get_subject(2).await {
        Ok(subject) => {
            println!("成功获取条目: {} / {}", subject.name, subject.name_cn);
            println!("简介: {}", subject.summary);
        }
        Err(e) => {
            eprintln!("获取条目失败: {}", e);
        }
    }

    // --- 调用需授权的 API ---
    let token = std::env::var("BANGUMI_ACCESS_TOKEN").ok();
    if let Some(access_token) = token {
        let auth_client = BangumiClient {
            access_token: Some(access_token),
            ..Default::default()
        };

        // 获取当前登录用户信息
        match auth_client.get_me().await {
            Ok(me) => {
                println!("\n成功获取当前用户信息, 你好, {}!", me.nickname);
            }
            Err(e) => {
                eprintln!("\n获取个人信息失败 (可能是 Token 无效或过期): {}", e);
            }
        }
    } else {
        println!("\n未设置 BANGUMI_ACCESS_TOKEN 环境变量，跳过授权接口测试。");
    }

    Ok(())
}

📚 API 模块

本库根据 Bangumi API 的功能对模块进行了划分，所有功能都通过 BangumiClient 的方法提供。

• character (角色): 搜索、获取角色详情、封面、关联条目/人物，以及收藏/取消收藏角色。
• collection (收藏): 管理用户收藏。获取、添加、更新用户的条目、章节、角色、人物收藏状态。
• episode (章节): 获取条目的分集列表和特定分集详情。
• indice (目录): 操作用户创建的目录。获取、创建、编辑、删除目录及目录中的条目。
• person (人物): 搜索、获取人物详情、封面、关联条目/角色，以及收藏/取消收藏人物。
• revision (修订): 查看条目、角色、人物等的编辑历史。
• subject (条目): 搜索、浏览、获取条目详情、封面、关联人物/角色/条目，以及每日放送日历。
• user (用户): 获取用户公开信息、头像以及当前登录用户（自己）的详细信息。

🧪 运行测试

克隆本仓库后，您可以使用 Cargo 运行内置的测试套件：

cargo test

注意:

• 大部分测试会向真实的 Bangumi API 发送请求。
• 涉及用户收藏、修改等需要授权的测试，在未提供有效 access_token 的情况下会请求失败，导致测试不通过。
• 如果需要完整测试，请修改对应 test.rs 文件，在 BangumiClient 中填入您的 access_token。

🤝 贡献

欢迎任何形式的贡献！如果您发现任何 Bug、有功能建议或希望改进代码，请随时：

1. 提交一个 Issue。
2. Fork 本项目并提交一个 Pull Request。

📜 许可证

本项目采用 MIT 许可证。详情请见 LICENSE 文件。