OsynicOsuapi

🚀 高性能 · 🏗️ 结构优良 · 🔧 易于扩展
功能完整的 Rust osu! API 客户端库，支持 WASM 和 Native 环境

🇨🇳 中文 · 🇺🇸 English

📚 目录

• 📄 OSU!API 官方文档
• 🧻 API体验网站
• ✨ 特性
• 🚀 快速开始
• 🍕 API检查表
• ❤️ 鸣谢
• ⚠️ 特别注意
• 🤝 贡献指南
• 📜 开源协议

📄 OSU!API 官方文档

• V1文档
• V2文档

🧻 API体验网站

网站特色

🌐 在线体验：基于 leptos 框架构建的 osynic_osuapi 在线体验平台

✨ 核心功能：

• 支持 V1 和 V2 API 的 WASM 客户端演示
• 基于 gloo-net 的网络请求
• 通过 osynic-cors.deno.dev 代理解决 CORS 跨域问题
• 多语言支持：中文、英语、日语、韩语、德语、法语、俄语

🚀 部署方式：使用 Deno 部署在 osynic-osuapi.deno.dev

💡 技术说明：由于浏览器 CORS 限制，WASM 客户端需要通过代理服务器来访问 osu! API

✨ 特性

• 🔄 新旧 API 全支持: 完整支持 V1 所有端点 + V2 大部分端点（除文档未归类接口）
• 🌐 WASM 兼容性: V1 和 V2 接口均提供 WebAssembly 支持，可直接在网页应用中使用
• 🏗️ 架构设计优良: 基于 client、interface、model 三层模块设计，易于扩展和维护
• 📖 完整示例支持: examples 目录提供丰富的示例代码和返回数据，详见 API检查表
• 🎓 示例驱动学习: 通过查看示例代码或运行 cargo run --example 示例名 快速上手

🚀 快速开始

步骤一：申请 OSU! API 授权

访问您的 osu! 设置页面，在以下位置申请相应的 API 授权：

• V2 API: 在 "OAuth" 或 "开放授权" 部分申请
• V1 API: 在 "Legacy API" 或 "旧版本 API" 部分申请

步骤二：配置环境变量

在项目根目录创建 .env 文件：

# V2 API 配置
CLIENT_ID="你的client_id"
CLIENT_SECRET="你的client_secret"
REDIRECT_URI="你的redirect_uri"
CODE="你的code"  # Authorization Code Grant 认证时需要

# V1 API 配置
API_KEY="你的api_key"

步骤三：添加依赖

在 Cargo.toml 中添加依赖：

[dependencies]
osynic_osuapi = "0.1.1"
dotenvy = "0.15"  # 用于读取 .env 文件

# WASM 环境配置（可选）
# osynic_osuapi = { version = "0.1.1", default-features = false, features = ["v1", "v2", "wasm"] }

💡 特性说明：

• 默认特性：["v1", "v2", "not-wasm"]（适用于 Native 环境）
• WASM 环境：需要关闭 not-wasm 并启用 wasm 特性

使用示例

示例一：V2 API - CCG 认证获取用户信息

使用 Client Credentials Grant 认证方式获取 peppy 的用户信息：

// examples/peppy.rs - 可运行 cargo run --example peppy 查看效果
use osynic_osuapi::error::Result;
use osynic_osuapi::v2::client::request::client::OsynicOsuApiV2Client;
use osynic_osuapi::v2::interface::oauth::IOauth;
use osynic_osuapi::v2::interface::users::IUsers;

// 也可以通过 prelude 导入所有客户端和接口模块
// use osynic_osuapi::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    dotenvy::dotenv().ok();
    let client_id = std::env::var("CLIENT_ID").expect("CLIENT_ID not set");
    let client_secret = std::env::var("CLIENT_SECRET").expect("CLIENT_SECRET not set");
    
    let client = OsynicOsuApiV2Client::default();
    
    // 获取访问令牌
    let token = client
        .oauth
        .get_token_without_code(client_id.parse()?, &client_secret)
        .await?;
    println!("Token: {:?}", token);

    // 获取用户信息
    let peppy = client
        .users
        .get_user_by_username("peppy", None, None)
        .await?;
    println!("User: {:?}", peppy);

    Ok(())
}

示例二：V1 API - 查询谱面信息

通过谱面哈希值查询谱面详细信息：

// examples/gb.rs - 可运行 cargo run --example gb 查看效果
use osynic_osuapi::error::Result;
use osynic_osuapi::v1::client::request::client::OsynicOsuApiV1Client;
use osynic_osuapi::v1::interface::beatmap::IBeatmap;
use osynic_osuapi::v1::model::beatmap::GetBeatmapsParams;

#[tokio::main]
async fn main() -> Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("API_KEY").expect("API_KEY is not set.");
    let client = OsynicOsuApiV1Client::new(api_key);
    
    // 通过哈希值查询谱面
    let params = GetBeatmapsParams::default()
        .hash("69f77b0dfe67d288c1bf748f91ceb133".to_string());

    let beatmaps = client.beatmap.get_beatmaps(params).await?;
    println!("Beatmaps: {:?}", beatmaps);

    Ok(())
}

🎯 更多示例：查看 examples/ 目录获取完整示例，或运行 cargo run --example 示例名 查看实际效果。

🍕 API检查表

可通过 cargo run --example 示例名 来运行API对应示例

V1

本条目基于V1官方文档的API大类进行划分，分类如下

其中接口模块对应可以在 src/v1/interface 中找到，相应实现则在 src/v1/client/request/api 或者 src/v1/client/gloo/api 中可以找到

V2

本条目基于V2官方文档的API大类进行划分，分类如下

其中接口模块对应可以在 src/v2/interface 中找到，相应实现则在 src/v2/client/request/api 中可以找到，示例代码和相应数据在 src/v2/examples 中可以找到

Authentication

Beatmaps

Beatmapsets

Changelog

Chat

Comments

Events

Forum

Home

Matches

Multiplayer

News

Notifications

Rankings

Scores

Users

Wiki

❤️ 鸣谢

最开始项目本来是打算直接用rosu-v2这个库的，但是由于当时看到rosu-v2已经就大几个月没更新了，并且项目组织和使用方式也不太习惯（可能是rosu-v2至今已经有四年历史的缘故，库里面有很多早期Rust代码，也不是很方便直接修改），所以就另起炉灶决定自己写一个了；

在osynic_osuapi的开发过程中，还是参考了rosu-v2的接口设计（但并未沿用）和部分类型（比如u64和u32的选取），感谢rosu-v2的作者们！

rosu-v2项目基于MIT License，项目证书放置在licenses/LICENSE-rosu-v2中

⚠️ 特别注意

使用本库时，最常见的问题来源于 osu! API 官方实体结构的变动：

常见问题类型

• 🔄 实体结构变动：osu! API 的结构可能随时变化，官方文档更新可能不及时
• 📝 返回字段变动：某些接口的返回字段可能发生变化，尤其是较少使用的端点
• ❓ 异常空值：某些字段可能在特定情况下返回 null，但文档中未标明为可选

问题反馈

如果您在使用过程中遇到解析错误或类型不匹配等问题，请直接提交 Issue 并附上：

1. 使用的 API 端点
2. 请求参数
3. 错误信息或异常堆栈

我会尽快处理并更新库以适应 API 的变化。本库的大部分模型都是基于实际请求返回结果构建的，但仍可能存在遗漏或错误。您的反馈对完善本库至关重要！

🤝 贡献指南

项目概述

本库主要为 Osynic 应用开发，同时也是一个功能完整的 osu! API Rust 封装库。

当前状态

✅ 已完成：

• V1 和 V2 大部分 API 接口（除文档未归类的接口）
• V1 和 V2 的 WASM 支持

⚠️ 开发中：可能存在 bug 或不完善的地方

如何贡献

欢迎提交 PR 或 Issue！如果您发现任何问题或有改进建议，请遵循以下规则：

代码贡献规范

• 编码规范：遵循 Rust 官方编码规范
• 测试要求：新增功能需附带测试用例
• 代码质量：提交前运行 cargo fmt 和 cargo clippy
• 文档更新：必要时更新相关文档和示例

Issue 提交指南

• 描述问题的具体场景
• 提供复现步骤和错误信息
• 附上相关的 API 端点和参数信息

📜 开源协议

本项目基于 MIT License 开源，请尊重原作者的著作权。