easy_msr_api/
lib.rs

1//! # MSR API Rust 封装库
2//! 
3//! 这是一个为MSR API（明日方舟音乐API）提供Rust封装的库，支持直接API调用和Swagger-UI文档。
4//! 
5//! ## 功能特性
6//! 
7//! - **核心API封装**：完整的MSR API功能封装，可直接调用
8//! - **可选Web路由**：提供Axum Web路由集成，包含Swagger UI文档界面
9//! - **类型安全**：完整的DTO类型定义
10//! 
11//! ## 使用方式
12//! 
13//! ### 1. 使用默认客户端(推荐)
14//! 
15//! ```rust
16//! use easy_msr_api::MSRApiClient;
17//! 
18//! #[tokio::main]
19//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
20//!     // 使用默认的MSR API地址
21//!     let client = MSRApiClient::new();
22//!     
23//!     let albums = client.get_all_albums().await?;
24//!     println!("专辑数量: {}", albums.data.len());
25//!     
26//!     Ok(())
27//! }
28//! ```
29//! 
30//! ### 2. 作为库直接调用API
31//! 
32//! ```rust
33//! use easy_msr_api::client::remote::RemoteApiClient;
34//! 
35//! #[tokio::main]
36//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
37//!     // 创建API客户端
38//!     let client = RemoteApiClient::new("https://monster-siren.hypergryph.com/api".to_string());
39//!     
40//!     // 直接调用API方法
41//!     let song = client.get_song("123456".to_string()).await?;
42//!     println!("歌曲名称: {}", song.data.name);
43//!     
44//!     Ok(())
45//! }
46//! ```
47//! ### 3. 作为Web服务使用（需要启用web feature）
48//! 
49//! ```rust
50//! use easy_msr_api::{client::remote::RemoteApiClient, web};
51//! use std::net::Ipv4Addr;
52//! 
53//! #[tokio::main]
54//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
55//!     let client = RemoteApiClient::new("https://monster-siren.hypergryph.com/api".to_string());
56//!     let app = web::routes(client);
57//!     
58//!     // 启动服务器
59//!     let listener = tokio::net::TcpListener::bind((Ipv4Addr::LOCALHOST, 8080)).await?;
60//!     println!("服务器运行在 http://localhost:8080");
61//!     println!("Swagger UI文档: http://localhost:8080/swagger-ui/");
62//!     axum::serve(listener, app).await?;
63//!     
64//!     Ok(())
65//! }
66//! ```
67//! 或者直接在本项目下执行`cargo run --bin server --features web`
68//! 
69//! ## Cargo Features
70//! 
71//! - **default**: 无额外功能，仅包含核心API封装
72//! - **web**: 启用Web路由和Swagger UI界面支持
73//! 
74//! ## 模块结构
75//! 
76//! - [`client`] - API客户端实现
77//! - [`config`] - 配置管理
78//! - [`error`] - 错误处理
79//! - Web路由层（需要启用 `web` feature）
80#![cfg_attr(feature = "web", doc = "- [`web`] - Web 路由层")]
81
82pub mod client;
83pub mod config;
84pub mod error;
85pub mod dto;
86
87#[cfg(feature = "web")]
88pub mod web;
89
90use crate::{client::remote::RemoteApiClient, dto::*, error::AppError};
91
92/// 默认的MSR API客户端，使用官方API地址
93/// 
94/// 这个客户端提供了对MSR API的完整封装，使用官方的API地址作为默认配置。
95/// 支持所有主要的API调用，包括歌曲、专辑、新闻和搜索功能。
96pub struct MSRApiClient {
97    inner: RemoteApiClient,
98}
99
100impl MSRApiClient {
101    /// 创建默认的MSR API客户端，使用官方API地址
102    /// 
103    /// # 示例
104    /// 
105    /// ```rust
106    /// use easy_msr_api::MSRApiClient;
107    /// 
108    /// let client = MSRApiClient::new();
109    /// ```
110    pub fn new() -> Self {
111        Self {
112            inner: RemoteApiClient::new("https://monster-siren.hypergryph.com/api".to_string()),
113        }
114    }
115
116    /// 使用自定义API地址创建客户端
117    /// 
118    /// # 参数
119    /// 
120    /// * `base` - API的基础URL地址
121    /// 
122    /// # 示例
123    /// 
124    /// ```rust
125    /// use easy_msr_api::MSRApiClient;
126    /// 
127    /// let client = MSRApiClient::with_base("https://custom-api.com".to_string());
128    /// ```
129    pub fn with_base(base: String) -> Self {
130        Self {
131            inner: RemoteApiClient::new(base),
132        }
133    }
134
135    /// 获取指定ID的歌曲详情
136    pub async fn get_song(&self, id: String) -> Result<SongResp, AppError> {
137        self.inner.get_song(id).await
138    }
139
140    /// 获取所有歌曲列表
141    pub async fn get_all_songs(&self) -> Result<AllSongsResp, AppError> {
142        self.inner.get_all_songs().await
143    }
144
145    /// 获取指定ID的专辑信息
146    pub async fn get_album(&self, id: String) -> Result<AlbumResp, AppError> {
147        self.inner.get_album(id).await
148    }
149
150    /// 获取指定ID的专辑详情（包含歌曲列表）
151    pub async fn get_album_detail(&self, id: String) -> Result<AlbumDetailResp, AppError> {
152        self.inner.get_album_detail(id).await
153    }
154
155    /// 获取所有专辑列表
156    pub async fn get_all_albums(&self) -> Result<ApiResp<Vec<AllAlbumsItem>>, AppError> {
157        self.inner.get_all_albums().await
158    }
159
160    /// 获取所有新闻列表
161    /// 
162    /// # 参数
163    /// 
164    /// * `last_cid` - 可选参数，用于分页，从指定cid之后开始获取
165    pub async fn get_all_news(&self, last_cid: Option<String>) -> Result<SearchNewsResp, AppError> {
166        self.inner.get_all_news(last_cid).await
167    }
168
169    /// 获取指定ID的新闻详情
170    pub async fn get_news_detail(&self, id: String) -> Result<NewsDetailResp, AppError> {
171        self.inner.get_news_detail(id).await
172    }
173
174    /// 获取字体配置信息
175    pub async fn get_font(&self) -> Result<FontResp, AppError> {
176        self.inner.get_font().await
177    }
178
179    /// 综合搜索（同时搜索专辑和新闻）
180    /// 
181    /// # 参数
182    /// 
183    /// * `keyword` - 搜索关键词
184    pub async fn search(&self, keyword: String) -> Result<SearchResp, AppError> {
185        self.inner.search(keyword).await
186    }
187
188    /// 搜索专辑
189    /// 
190    /// # 参数
191    /// 
192    /// * `keyword` - 搜索关键词
193    /// * `last_cid` - 可选参数，用于分页
194    pub async fn search_albums(
195        &self,
196        keyword: String,
197        last_cid: Option<String>,
198    ) -> Result<SearchAlbumResp, AppError> {
199        self.inner.search_albums(keyword, last_cid).await
200    }
201
202    /// 搜索新闻
203    /// 
204    /// # 参数
205    /// 
206    /// * `keyword` - 搜索关键词
207    /// * `last_cid` - 可选参数，用于分页
208    pub async fn search_news(
209        &self,
210        keyword: String,
211        last_cid: Option<String>,
212    ) -> Result<SearchNewsResp, AppError> {
213        self.inner.search_news(keyword, last_cid).await
214    }
215}
216
217impl Default for MSRApiClient {
218    fn default() -> Self {
219        Self::new()
220    }
221}
easy_msr_api/lib.rs

easy_msr_api/
lib.rs
