Skip to main content

yang_base/table/
record.rs

1//! 数据库记录类型
2//!
3//! 提供 `Record` 类型,用于在不知道具体 Rust 实体时安全读取 MySQL 查询结果。
4//! 每一行数据以 `serde_json::Map<String, serde_json::Value>` 的形式存储,
5//! 支持所有常见 MySQL 类型到 JSON 类型的映射。
6//!
7//! # MySQL 类型映射规则
8//!
9//! | MySQL 类型 | JSON 类型 |
10//! |-----------|----------|
11//! | INT / BIGINT | Number (i64) |
12//! | FLOAT / DOUBLE | Number (f64) |
13//! | DECIMAL / NUMERIC | String(保留精度,NEWDECIMAL 协议本就是字符串编码) |
14//! | VARCHAR / TEXT / CHAR | String |
15//! | BOOLEAN / TINYINT(1) | Bool |
16//! | DATE / DATETIME / TIMESTAMP | String (ISO 8601) |
17//! | NULL | Null |
18//! | BLOB / BINARY | String (Base64) |
19//! | JSON | Object / Array |
20//!
21//! # 示例
22//!
23//! ```rust,ignore
24//! use yang_base::table::Record;
25//!
26//! // 通过 sqlx::FromRow 自动从查询结果构建
27//! let rows: Vec<Record> = query.all().await?;
28//! for row in rows {
29//!     println!("{:?}", row.as_map());
30//! }
31//! ```
32
33use crate::error::BaseError;
34use serde::de::DeserializeOwned;
35use serde::{Deserialize, Serialize};
36
37/// 动态数据库记录
38///
39/// 以键值对形式存储一行数据库查询结果,支持任意表结构。
40/// 字段名为键,字段值为 JSON 值。
41///
42/// # 字段
43///
44/// - `columns`:列名到 JSON 值的映射
45///
46/// # 示例
47///
48/// ```rust,ignore
49/// use yang_base::table::Record;
50/// use serde_json::json;
51///
52/// let row = Record::new()
53///     .set("id", json!(1))
54///     .set("name", json!("Alice"));
55/// ```
56#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
57#[serde(transparent)]
58#[schemars(transparent)]
59pub struct Record {
60    columns: serde_json::Map<String, serde_json::Value>,
61}
62
63impl Record {
64    /// 创建空记录。
65    pub fn new() -> Self {
66        Self {
67            columns: serde_json::Map::new(),
68        }
69    }
70
71    /// 链式写入字段值。
72    pub fn set(mut self, key: impl Into<String>, value: impl Into<serde_json::Value>) -> Self {
73        self.columns.insert(key.into(), value.into());
74        self
75    }
76
77    /// 写入字段值并返回被替换的旧值。
78    pub fn insert(
79        &mut self,
80        key: impl Into<String>,
81        value: impl Into<serde_json::Value>,
82    ) -> Option<serde_json::Value> {
83        self.columns.insert(key.into(), value.into())
84    }
85
86    /// 获取指定列的原始 JSON 值。
87    ///
88    /// # 参数
89    ///
90    /// - `key`:列名
91    ///
92    /// # 返回
93    ///
94    /// - `Some(&Value)`:列存在时返回值的引用
95    /// - `None`:列不存在
96    pub fn get(&self, key: &str) -> Option<&serde_json::Value> {
97        if key.trim().is_empty() {
98            return None;
99        }
100
101        self.columns.get(key)
102    }
103
104    /// 读取必需字段并转换为目标类型。
105    pub fn require<T>(&self, key: &str) -> Result<T, BaseError>
106    where
107        T: DeserializeOwned,
108    {
109        let value = self
110            .get(key)
111            .ok_or_else(|| BaseError::FieldNotFound("record".to_string(), key.to_string()))?;
112        serde_json::from_value(value.clone())
113            .map_err(|error| BaseError::InvalidFieldType(key.to_string(), error.to_string()))
114    }
115
116    /// 读取可选字段;字段不存在或为 `null` 时返回 `None`。
117    pub fn optional<T>(&self, key: &str) -> Result<Option<T>, BaseError>
118    where
119        T: DeserializeOwned,
120    {
121        let Some(value) = self.get(key) else {
122            return Ok(None);
123        };
124        if value.is_null() {
125            return Ok(None);
126        }
127        serde_json::from_value(value.clone())
128            .map(Some)
129            .map_err(|error| BaseError::InvalidFieldType(key.to_string(), error.to_string()))
130    }
131
132    /// 返回字段映射的只读引用。
133    pub fn as_map(&self) -> &serde_json::Map<String, serde_json::Value> {
134        &self.columns
135    }
136
137    /// 消费记录并返回字段映射。
138    pub fn into_map(self) -> serde_json::Map<String, serde_json::Value> {
139        self.columns
140    }
141
142    /// 消费记录并返回查询写入层使用的 HashMap。
143    #[cfg(feature = "mysql")]
144    pub(crate) fn into_columns(self) -> std::collections::HashMap<String, serde_json::Value> {
145        self.columns.into_iter().collect()
146    }
147}
148
149impl Default for Record {
150    fn default() -> Self {
151        Self::new()
152    }
153}
154
155impl From<serde_json::Map<String, serde_json::Value>> for Record {
156    fn from(columns: serde_json::Map<String, serde_json::Value>) -> Self {
157        Self { columns }
158    }
159}
160
161/// 将 Record 转换为 serde_json::Value(Object 类型)。
162impl From<Record> for serde_json::Value {
163    fn from(row: Record) -> Self {
164        serde_json::Value::Object(row.columns)
165    }
166}
167
168/// 实现 sqlx::FromRow,支持从 MySQL 查询结果动态解码
169///
170/// 按 MySQL 列类型将值映射到对应的 JSON 类型:
171/// - INT/BIGINT → i64
172/// - FLOAT/DOUBLE → f64
173/// - DECIMAL/NUMERIC → String(保留精度)
174/// - VARCHAR/TEXT/CHAR → String
175/// - BOOLEAN/TINYINT(1) → Bool
176/// - DATE/DATETIME/TIMESTAMP → ISO 8601 字符串
177/// - NULL → Null
178/// - BLOB/BINARY → Base64 字符串
179/// - JSON → Object/Array
180#[cfg(feature = "mysql")]
181impl<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> for Record {
182    fn from_row(row: &'r sqlx::mysql::MySqlRow) -> Result<Self, sqlx::Error> {
183        use sqlx::Column;
184        use sqlx::Row;
185        use sqlx::TypeInfo;
186        use sqlx::ValueRef;
187
188        let mut columns = serde_json::Map::new();
189
190        // 遍历所有列,按类型解码
191        for col in row.columns() {
192            let col_name = col.name().to_string();
193            let type_name = col.type_info().name().to_uppercase();
194
195            // 先检查是否为 NULL
196            let is_null: bool = row
197                .try_get_raw(col.ordinal())
198                .map(|v| v.is_null())
199                .unwrap_or(false);
200
201            if is_null {
202                // NULL 值映射为 JSON Null
203                columns.insert(col_name, serde_json::Value::Null);
204                continue;
205            }
206
207            // 按 MySQL 类型名称解码
208            let json_value = decode_mysql_column(row, col.ordinal(), &type_name)?;
209            columns.insert(col_name, json_value);
210        }
211
212        Ok(Record { columns })
213    }
214}
215
216/// 根据 MySQL 列类型解码列值为 JSON 值
217///
218/// # 参数
219///
220/// - `row`:MySQL 行
221/// - `ordinal`:列索引
222/// - `type_name`:MySQL 类型名称(大写)
223///
224/// # 返回
225///
226/// - `Ok(Value)`:解码成功
227/// - `Err(sqlx::Error)`:解码失败
228#[cfg(feature = "mysql")]
229fn decode_mysql_column(
230    row: &sqlx::mysql::MySqlRow,
231    ordinal: usize,
232    type_name: &str,
233) -> Result<serde_json::Value, sqlx::Error> {
234    use base64::Engine;
235    use sqlx::Row;
236
237    // 整数类型:INT、BIGINT、MEDIUMINT、SMALLINT
238    if type_name.contains("INT") && !type_name.contains("TINYINT") {
239        let val: i64 = row.try_get(ordinal)?;
240        return Ok(serde_json::Value::Number(val.into()));
241    }
242
243    // TINYINT(1) 通常用作 BOOLEAN,但 MySQL 中 BOOLEAN 实际上是 TINYINT
244    // 按照 MySQL 约定,TINYINT 映射为 bool(0 = false,非 0 = true)
245    if type_name == "BOOLEAN" || type_name == "TINYINT" {
246        let val: i8 = row.try_get(ordinal)?;
247        return Ok(serde_json::Value::Bool(val != 0));
248    }
249
250    // 定点类型:DECIMAL、NUMERIC
251    // NEWDECIMAL 协议本就是字符串编码,读字符串以保留精度,避免 f64 舍入误差。
252    if type_name == "DECIMAL" || type_name == "NUMERIC" {
253        let val: String = row.try_get_unchecked(ordinal)?;
254        return Ok(serde_json::Value::String(val));
255    }
256
257    // 浮点类型:FLOAT、DOUBLE
258    if type_name == "FLOAT" || type_name == "DOUBLE" {
259        let val: f64 = row.try_get(ordinal)?;
260        // NaN 或 Infinity 无法编码为 JSON Number,返回结构化解码错误而非静默归零
261        let json_num = serde_json::Number::from_f64(val).ok_or_else(|| {
262            sqlx::Error::Decode("浮点数值为 NaN 或 Infinity 无法编码为 JSON Number".into())
263        })?;
264        return Ok(serde_json::Value::Number(json_num));
265    }
266
267    // 日期时间类型:DATE、DATETIME、TIMESTAMP
268    if type_name == "DATE" {
269        let val: chrono::NaiveDate = row.try_get(ordinal)?;
270        // 转换为 ISO 8601 格式字符串
271        return Ok(serde_json::Value::String(
272            val.format("%Y-%m-%d").to_string(),
273        ));
274    }
275
276    if type_name == "DATETIME" || type_name == "TIMESTAMP" {
277        let val: chrono::NaiveDateTime = row.try_get(ordinal)?;
278        // 转换为 ISO 8601 格式字符串
279        return Ok(serde_json::Value::String(
280            val.format("%Y-%m-%dT%H:%M:%S").to_string(),
281        ));
282    }
283
284    if type_name == "TIME" {
285        let val: chrono::NaiveTime = row.try_get(ordinal)?;
286        return Ok(serde_json::Value::String(
287            val.format("%H:%M:%S").to_string(),
288        ));
289    }
290
291    // 二进制类型:BLOB、BINARY、VARBINARY、LONGBLOB、MEDIUMBLOB、TINYBLOB
292    if type_name.contains("BLOB") || type_name.contains("BINARY") {
293        let val: Vec<u8> = row.try_get(ordinal)?;
294        // 转换为 Base64 字符串
295        let encoded = base64::engine::general_purpose::STANDARD.encode(&val);
296        return Ok(serde_json::Value::String(encoded));
297    }
298
299    // JSON 类型:直接解析为 JSON 值
300    if type_name == "JSON" {
301        let val: serde_json::Value = row.try_get(ordinal)?;
302        return Ok(val);
303    }
304
305    // 字符串类型:VARCHAR、TEXT、CHAR、LONGTEXT、MEDIUMTEXT、TINYTEXT、ENUM、SET
306    // 以及其他未知类型,尝试作为字符串读取
307    let val: String = row.try_get(ordinal)?;
308    Ok(serde_json::Value::String(val))
309}
310
311#[cfg(test)]
312mod tests {
313    use super::*;
314    use serde_json::json;
315
316    #[test]
317    fn get_rejects_blank_column_name() {
318        let mut row = Record::new();
319        row.insert("", json!(1));
320        row.insert("   ", json!(2));
321        row.insert("name", json!("Alice"));
322
323        assert_eq!(
324            row.get("name").and_then(|value| value.as_str()),
325            Some("Alice")
326        );
327        assert_eq!(row.get(""), None);
328        assert_eq!(row.get("   "), None);
329    }
330
331    #[test]
332    fn serializes_as_plain_object_and_checks_types() {
333        let row = Record::new().set("id", 7).set("name", "Alice");
334
335        assert_eq!(
336            serde_json::to_value(&row).expect("记录应可序列化"),
337            json!({
338                "id": 7,
339                "name": "Alice"
340            })
341        );
342        assert_eq!(row.require::<i64>("id").expect("id 应为整数"), 7);
343        assert!(row.require::<String>("id").is_err());
344        assert!(row.require::<String>("missing").is_err());
345    }
346}