openlark_docs/common/
api_utils.rs

1/// API通用工具函数
2///
3/// 提供API实现的通用工具和辅助函数，减少重复代码，提高一致性
4use openlark_core::{error, SDKResult};
5/// 标准化API响应数据提取
6///
7/// # 参数
8/// - `response`: API响应对象
9/// - `context`: 错误上下文描述
10///
11/// # 返回
12/// - `Ok(T)`: 成功提取的数据
13/// - `Err(SDKError)`: 包含上下文信息的错误
14pub fn extract_response_data<T>(
15    response: openlark_core::api::ApiResponse<T>,
16    context: &str,
17) -> SDKResult<T> {
18    response.data.ok_or_else(|| {
19        error::validation_error(
20            &format!("{}响应数据为空", context),
21            "服务器没有返回有效的数据",
22        )
23    })
24}
25
26/// 标准化参数验证错误处理
27///
28/// # 参数
29/// - `field_name`: 字段名称
30/// - `field_value`: 字段值
31/// - `error_message`: 错误消息
32///
33/// # 返回
34/// - `Ok(())`: 验证通过
35/// - `Err(SDKError)`: 验证失败错误
36pub fn validate_required_field<T: AsRef<str>>(
37    field_name: &str,
38    field_value: Option<T>,
39    error_message: &str,
40) -> SDKResult<()> {
41    match field_value {
42        Some(value) if !value.as_ref().trim().is_empty() => Ok(()),
43        _ => Err(error::validation_error(field_name, error_message)),
44    }
45}
46
47/// 标准化API端点URL生成辅助宏
48///
49/// # 使用示例
50/// ```rust
51/// use openlark_docs::api_url;
52///
53/// let doc_token = "doc_token";
54/// let spreadsheet_token = "spreadsheet_token";
55///
56/// let doc_url = api_url!("/open-apis/doc/v2/{}", doc_token);
57/// let sheet_url = api_url!("/open-apis/sheets/v2/spreadsheets/{}/values", spreadsheet_token);
58///
59/// assert!(doc_url.contains(doc_token));
60/// assert!(sheet_url.contains(spreadsheet_token));
61/// ```
62#[macro_export]
63macro_rules! api_url {
64    ($base_url:expr) => {
65        $base_url.to_string()
66    };
67    ($base_url:expr, $($arg:expr),+) => {
68        format!($base_url, $($arg),+)
69    };
70}
71
72/// 标准化参数序列化错误处理
73///
74/// # 参数
75/// - `params`: 要序列化的参数
76/// - `context`: 序列化上下文
77///
78/// # 返回
79/// - `Ok(serde_json::Value)`: 序列化成功
80/// - `Err(SDKError)`: 包含详细信息的序列化错误
81pub fn serialize_params<T: serde::Serialize>(
82    params: &T,
83    context: &str,
84) -> SDKResult<serde_json::Value> {
85    serde_json::to_value(params).map_err(|e| {
86        error::validation_error(
87            &format!("{}参数序列化失败", context),
88            &format!("无法序列化请求参数: {}", e),
89        )
90    })
91}
openlark_docs/common/api_utils.rs

openlark_docs/common/
api_utils.rs
