robotech 1.6.0

Backend service implementation for the RoboTech platform, providing RESTful APIs and business logic for web applications.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! # Response Object (RO) 模块，用于统一API响应格式

use crate::ro::ro_result::RoResult;
use chrono::Utc;
use derive_setters::Setters;
use serde::{Deserialize, Serialize};
use serde_with::skip_serializing_none;
use std::fmt::Debug;
use typed_builder::TypedBuilder;
use utoipa::ToSchema;
use wheel_rs::serde::u64_serde;

/// # 统一API响应结构体
///
/// 用于封装所有API的返回结果，提供统一的响应格式
/// 包含结果状态、消息、时间戳以及可选的额外数据、详情和错误码
///
/// ## 泛型参数
/// * `E` - 额外数据的类型，用于携带具体的业务数据
#[skip_serializing_none]
#[derive(ToSchema, Debug, Serialize, Deserialize, Setters, TypedBuilder)]
#[builder]
pub struct Ro<E> {
    /// 响应结果枚举值，表示请求处理的结果状态
    pub result: RoResult,
    /// 响应消息，对结果的简要描述
    pub message: String,
    /// 时间戳，记录响应生成的时间（毫秒）
    /// 这里默认值为当前时间戳，懒得考虑系统时间错误的问题
    #[builder(default = Utc::now().timestamp_millis() as u64)]
    #[serde(with = "u64_serde")]
    pub timestamp: u64,
    /// 额外数据，可选的响应数据内容
    #[builder(default, setter(strip_option))]
    pub extra: Option<E>,
    /// 详细信息，可选的详细描述信息
    #[builder(default, setter(strip_option))]
    pub detail: Option<String>,
    /// 编码，可选的业务编码
    #[builder(default, setter(strip_option))]
    pub code: Option<String>,
}

impl<E> Ro<E> {
    /// # 判断结果是否为成功
    ///
    /// ## 返回值
    /// 如果结果为Success，则返回true；否则返回false
    pub fn is_ok(&self) -> bool {
        self.result == RoResult::Success
    }

    /// # 判断结果是否有错误
    ///
    /// ## 返回值
    /// 如果结果不为Success，则返回true；否则返回false
    pub fn is_err(&self) -> bool {
        self.result != RoResult::Success
    }

    /// # 创建一个成功的响应对象
    ///
    /// ## 参数
    /// * `message` - 成功消息
    ///
    /// ## 返回值
    /// 返回一个结果为Success的Ro实例
    pub fn success(message: String) -> Self {
        Self::builder()
            .result(RoResult::Success)
            .message(message)
            .build()
    }

    /// # 创建一个非法参数的响应对象
    ///
    /// ## 参数
    /// * `message` - 错误消息
    ///
    /// ## 返回值
    /// 返回一个结果为IllegalArgument的Ro实例
    pub fn illegal_argument(message: String) -> Self {
        Self::builder()
            .result(RoResult::IllegalArgument)
            .message(message)
            .build()
    }

    /// # 创建一个警告的响应对象
    ///
    /// ## 参数
    /// * `message` - 警告消息
    ///
    /// ## 返回值
    /// 返回一个结果为Warn的Ro实例
    pub fn warn(message: String) -> Self {
        Self::builder()
            .result(RoResult::Warn)
            .message(message)
            .build()
    }

    /// # 创建一个失败的响应对象
    ///
    /// ## 参数
    /// * `message` - 失败消息
    ///
    /// ## 返回值
    /// 返回一个结果为Fail的Ro实例
    pub fn fail(message: String) -> Self {
        Self::builder()
            .result(RoResult::Fail)
            .message(message)
            .build()
    }
}