netease_qq_music_api/
lib.rs

1//! 网易云与 QQ 音乐的统一异步 API 封装库。
2//!
3//! # Overview
4//!
5//! 本 crate 提供统一入口 [`MusicClient`]，并通过 typed builder 约束请求构建流程。
6//! 调用方可以在一致的 API
7//! 语义下完成搜索、详情、播放、发现、歌单和登录请求，而无需直接处理平台实现差异。
8//!
9//! # Quick Start
10//!
11//! ```no_run
12//! # async fn run() -> Result<(), netease_qq_music_api::MusicClientError> {
13//! let client = netease_qq_music_api::MusicClient::new();
14//! let result = client.search().song().keyword("江南").limit(10).send().await?;
15//! println!("songs: {}", result.songs.len());
16//! # Ok(())
17//! # }
18//! ```
19//!
20//! # Core Concepts
21//!
22//! - [`MusicClient`] - 全部请求的统一入口。
23//! - typed builders: 通过 `Kind` 类型态限制“当前可调用步骤”。
24//! - [`Platform`][`models::Platform`] - 平台选择，默认值为
25//!   [`Platform::Netease`][`models::Platform::Netease`]。
26//! - [`LoginTokenRef`][`client::LoginTokenRef`] - 平台登录 token 的统一借用包装，用于受保护接口。
27//!
28//! # Terminology
29//!
30//! - “请求构建器”：指 `*Request<'a, K>` 链式类型。
31//! - “类型态（Kind）”：指 `*Kind` 标记类型，用于编译期约束调用顺序。
32//! - “登录 token”：指平台登录凭证对象（如
33//!   [`models::NeteaseLoginToken`]、[`models::TencentLoginToken`]）。
34//! - “token 所属平台”：指登录 token 对应的平台，必须与请求平台一致。
35//!
36//! # Common Workflow
37//!
38//! 1. 创建 [`MusicClient`]。
39//! 2. 选择业务域（如 [`MusicClient::search`]、[`MusicClient::detail`]、
40//!    [`MusicClient::playback`]）。
41//! 3. 选择具体子能力并设置必填参数。
42//! 4. 需要鉴权时调用对应请求构建器的登录注入方法并传入平台 token。
43//! 5. 调用对应请求构建器的发送方法并 `await` 结果。
44//!
45//! # Errors and Limits
46//!
47//! - 参数缺失会返回 [`MusicClientError`] 的对应变体（如
48//!   [`MusicClientError::MissingKeyword`]、[`MusicClientError::MissingId`]）。
49//! - token 所属平台与请求平台不一致时返回 [`MusicClientError::AuthTokenPlatformMismatch`]。
50//! - 网络与响应解析异常统一为 [`MusicClientError::NetworkError`]。
51//! - 公开 API 通过 [`MusicClientResult`] 返回失败信息，不以 panic 作为业务错误路径。
52//!
53//! # See Also
54//!
55//! - [`client`] - 对外请求构建器与入口类型。
56//! - [`models`] - 跨平台统一数据模型。
57//! - [`error`] - 统一错误类型与结果别名。
58
59/// 对外请求构建器与 API 入口模块。
60pub mod client;
61/// 全局统一错误定义模块。
62pub mod error;
63/// 跨平台统一数据模型模块。
64pub mod models;
65mod platform;
66
67/// 统一异步 API 入口。
68pub use client::MusicClient;
69/// 对外暴露的错误与结果类型别名。
70pub use error::{MusicClientError, MusicClientResult};
netease_qq_music_api/lib.rs

netease_qq_music_api/
lib.rs
