OsynicOsuapi

高性能, 结构优良, 拓展性好的 Rust osu! API 客户端 支持 WASM 和 native 环境.

中文版本 | English Version

📄 OSU!API 官方文档

• V1文档
• V2文档

🧻 API体验网站

LeptosOsuapiPlayground是基于leptos框架快速搭建了一个osynic_osuapi体验网站，主要使用了的V1的WASM客户端支持（基于gloo-net）,不过很显然，由于CORS的问题，不代理直接在浏览器中使用V1的API会遇到跨域问题（毕竟WASM部分是浏览器前端发的请求嘛），所以用Deno来搭建了一个中转服务器osynic-cors.deno.dev，配合WASM客户端的proxy_url来实现代理请求；

目前网站通过Deno部署在osynic-osuapi.deno.dev，支持中日韩德法俄英等多种语言；

📜 特性

• 新旧 API 支持: 支持 V1 的所有端点 以及 V2 的大部分端点（除了文档未归类的接口）
• WASM 兼容性: 为 V1 接口 提供了 WebAssembly 支持，支持直接从网页应用访问 OSU API（但是会遇到CORS）
• 项目结构良好: 基于client、interface、model三重模块划分；client部分聚合interface接口并支持多种HTTP客户端，便于拓展
• 非常完整的示例支持: 在examples目录下，我们提供了非常完整的示例代码与返回数据，详见下方的API检查表部分
• 在示例中学习使用: 学习使用本库的最佳方式就是直接查看examples中丰富的示例代码，或者直接运行cargo run --example 示例名来查看对应的返回数据，只要习惯示例的代码风格，很快就能上手使用

🚀 快速开始

1. 申请OSU!API的开放授权(V2)或者旧版本API(V1)

申请网址就在你的osu设置页，在开放授权(V2)或者旧版本API(V1)中申请即可

2. 设置环境变量

在你的项目根目录下创建一个.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"

然后我们就可以通过dotenvy依赖来读取.env中的环境变量了

3. 添加依赖并使用

首先在Cargo.toml中添加依赖

[dependencies]
osynic_osuapi = "0.1.0"
# 默认features是 ["v1", "v2", "not-wasm"]，如果需要在WASM环境中使用，需要关闭`not-wasm`特性，然后添加`wasm`特性，例如：
# osynic_osuapi = { version = "0.1.0", default-features = false, features = ["v1", "v2", "wasm"] }

然后在代码中使用即可~

示例一：用V2完成CCG认证并获取peppy的用户信息

下面的代码来自examples/peppy.rs，可以直接运行cargo run --example peppy来查看效果

// Client Credentials Grant and Get Peppy's User Info
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;

// You can also import all the client and interface modules by 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);

    let peppy = client
        .users
        .get_user_by_username("peppy", None, None)
        .await?;
    println!("{:?}", peppy);

    Ok(())
}

示例二：用V1查阅谱面信息

下面的代码来自examples/gb.rs，可以直接运行cargo run --example gb来查看效果

// Get beatmap by hash
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;

// You can also import all the client and interface modules by prelude
// use osynic_osuapi::prelude::*;

#[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.clone());
    let params = GetBeatmapsParams::default().hash("69f77b0dfe67d288c1bf748f91ceb133".to_string());

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

    Ok(())
}

🍕 API检查表

可通过cargo run --exmaple 示例名来运行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，但在文档中未标明为可选

这些问题的主要原因是osu!API官方文档对实体属性的描述不够全面。如果您在使用过程中遇到解析错误或类型不匹配等问题，请不要犹豫，直接提交Issue并附上：

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

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

🤝 贡献指南

这个库基本上只是为Osynic这个应用开发的一个模块，但是同时也是一个功能完整的osu!api的Rust封装；

目前，v1和v2的大部分(除了文档未归类的接口)已经实现，v2的WASM支持暂时还没有做。

这个库仍然在开发中，可能会有一些bug或者不完善的地方；

所以，如果代码有任何问题，或者你有任何建议，欢迎提交PR或者Issue，我会尽快处理~

如果你想贡献代码，请遵循以下规则：

• 遵循Rust官方编码规范
• 新增功能需附带测试用例
• 提交前运行cargo fmt和cargo clippy

📜 开源协议

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