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