milky_rust_sdk/
error.rs

1//! 定义了 `MilkyClient` 及其相关操作中可能发生的各种错误类型。
2//!
3//! 本模块主要包含一个 [`MilkyError`] 枚举，它整合了来自不同库（如 `tungstenite`、`url`、`serde_json`、`reqwest`）的错误，
4//! 以及特定于本应用程序逻辑的自定义错误。
5//! 同时，提供了一个统一的 [`Result<T>`] 类型别名，以便在整个库中方便地使用。
6
7use reqwest;
8use thiserror::Error;
9use tokio_tungstenite::tungstenite;
10
11/// `MilkyClient` 操作中可能发生的错误枚举。
12///
13/// 使用 `thiserror::Error` 宏来自动派生 `std::error::Error` trait 的实现，
14/// 并为每个错误变体提供用户友好的描述信息。
15#[derive(Error, Debug)]
16pub enum MilkyError {
17    /// WebSocket 通信过程中发生的错误。
18    /// 通常由底层的 `tokio-tungstenite` 库引发。
19    #[error("WebSocket 错误: {0}")]
20    WebSocket(#[from] Box<tungstenite::Error>),
21
22    /// URL 解析失败时发生的错误。
23    /// 例如，当提供的服务器地址或API端点格式不正确时。
24    #[error("URL 解析错误: {0}")]
25    UrlParse(#[from] url::ParseError),
26
27    /// 当 URL 使用了不支持的协议方案（scheme）时发生的错误。
28    /// 例如，客户端可能只支持 "http" 和 "https" (以及对应的 "ws", "wss")。
29    #[error("不支持的协议方案: {0}")]
30    UnsupportedScheme(String),
31
32    /// JSON 序列化或反序列化过程中发生的错误。
33    /// 这可能发生在构造API请求或解析API响应时。
34    #[error("JSON 序列化/反序列化错误: {0}")]
35    Json(#[from] serde_json::Error),
36
37    /// 标准输入/输出 (I/O) 操作发生的错误。
38    /// 例如，在读取配置文件或写入日志时可能发生。
39    #[error("IO 错误: {0}")]
40    Io(#[from] std::io::Error),
41
42    /// API 请求失败，通常表示服务器成功处理了请求但返回了一个业务逻辑上的错误。
43    /// 例如，权限不足、参数错误等。
44    #[error("API 请求失败: {message}")]
45    ApiError {
46        /// 来自服务器的错误描述信息。
47        message: String,
48        /// 来自服务器的特定返回码（retcode），有助于定位具体错误原因。
49        retcode: Option<i64>,
50    },
51
52    /// HTTP API 请求返回了非成功状态码（例如 4xx, 5xx）。
53    /// 这表示 HTTP 请求本身可能已发送，但服务器响应了一个 HTTP 错误。
54    #[error("HTTP API 错误: {message}")]
55    HttpApiError {
56        /// HTTP 响应的状态码。
57        status: reqwest::StatusCode,
58        /// 从服务器响应体中获取的错误信息，或者一个通用的错误描述。
59        message: String,
60    },
61
62    /// 表示 WebSocket 连接尚未建立或已经丢失。
63    /// 尝试在未连接状态下进行需要连接的操作时可能发生。
64    #[error("连接未建立或已丢失")]
65    NotConnected,
66
67    /// 操作（如API请求）等待响应超时。
68    #[error("响应超时")]
69    Timeout,
70
71    /// 收到了非预期的响应类型。
72    /// 例如，期望一个特定的JSON结构但收到了其他格式。
73    #[error("收到了非预期的响应类型")]
74    UnexpectedResponse,
75
76    /// 当请求中的 `echo` 字段与响应中的 `echo` 字段不匹配时发生。
77    /// 用于验证异步请求和响应的对应关系。
78    #[error("操作的 echo 字段不匹配")]
79    EchoMismatch,
80
81    /// 底层 HTTP 请求库 (`reqwest`) 发生的错误。
82    /// 例如，网络连接问题、DNS解析失败等。
83    #[error("HTTP 请求错误: {0}")]
84    Reqwest(#[from] reqwest::Error),
85
86    #[error("内部错误: {0}")]
87    Internal(String),
88}
89
90/// 一个统一的 `Result` 类型别名，用于 `MilkyClient` 的所有操作。
91///
92/// 它简化了函数签名，其中 `T` 是成功情况下的返回值类型，
93/// 错误类型固定为 [`MilkyError`]。
94pub type Result<T> = std::result::Result<T, MilkyError>;
milky_rust_sdk/error.rs

milky_rust_sdk/
error.rs
