Skip to main content

yang_base/table/
field_type.rs

1//! 字段类型定义
2//!
3//! 提供数据表字段的类型系统,支持基本类型、时间类型、复杂类型和关联类型。
4
5/// MySQL utf8mb4 下 `VARCHAR` 的最大字符数(行上限 65535 字节 ÷ 4 字节/字符)。
6#[allow(dead_code)] // 单后端构建时另一个方言的常量仅供测试与文档对照。
7pub const MYSQL_MAX_VARCHAR_LENGTH: usize = 16_383;
8
9/// PostgreSQL `VARCHAR(n)` 的最大字符数(`n` 上限为 10485760)。
10#[allow(dead_code)] // 单后端构建时另一个方言的常量仅供测试与文档对照。
11pub const POSTGRES_MAX_VARCHAR_LENGTH: usize = 10_485_760;
12
13/// 构建期声明可用的 `VARCHAR` 最大字符数。
14///
15/// 构建期([`crate::table::Field::string`])没有“当前后端”概念:同时启用两种
16/// 数据库 feature 时取两者中更大的 PostgreSQL 上界,让合法声明不被收紧;
17/// 具体方言的 DDL 渲染再各自使用 [`MYSQL_MAX_VARCHAR_LENGTH`] /
18/// [`POSTGRES_MAX_VARCHAR_LENGTH`] 校验,超出 MySQL 上界的声明会在 MySQL
19/// 渲染阶段明确报错,而不是在构建期被静默拒绝。
20#[cfg(all(feature = "mysql", not(feature = "postgres")))]
21pub const MAX_VARCHAR_LENGTH: usize = MYSQL_MAX_VARCHAR_LENGTH;
22/// 构建期声明可用的 `VARCHAR` 最大字符数(PostgreSQL 构建,含双后端构建)。
23#[cfg(feature = "postgres")]
24pub const MAX_VARCHAR_LENGTH: usize = POSTGRES_MAX_VARCHAR_LENGTH;
25/// 当前后端方言的 `VARCHAR` 最大字符数(未启用数据库 feature 时的保守值)。
26#[cfg(not(any(feature = "mysql", feature = "postgres")))]
27pub const MAX_VARCHAR_LENGTH: usize = MYSQL_MAX_VARCHAR_LENGTH;
28
29use crate::error::BaseError;
30use serde::{Deserialize, Serialize};
31
32/// 获取 JSON 值的类型名称
33///
34/// # 参数
35///
36/// - `value`: JSON 值
37///
38/// # 返回值
39///
40/// 返回类型名称的字符串
41fn value_type_name(value: &serde_json::Value) -> &'static str {
42    match value {
43        serde_json::Value::Null => "null",
44        serde_json::Value::Bool(_) => "boolean",
45        serde_json::Value::Number(_) => "number",
46        serde_json::Value::String(_) => "string",
47        serde_json::Value::Array(_) => "array",
48        serde_json::Value::Object(_) => "object",
49    }
50}
51
52/// 字段类型
53///
54/// 定义数据表字段支持的所有类型,包括:
55/// - 基本类型:String, Integer, BigInt, Float, Double, Boolean
56/// - 时间类型:Date, DateTime, Timestamp
57/// - 复杂类型:Json, Text
58/// - 枚举类型:Enum
59///
60/// # 示例
61///
62/// ```rust
63/// use yang_base::table::FieldType;
64///
65/// // 创建字符串类型,最大长度 50
66/// let name_type = FieldType::String { max_length: 50 };
67///
68/// // 创建整数类型
69/// let age_type = FieldType::Integer;
70///
71/// // 创建枚举类型
72/// let status_type = FieldType::Enum {
73///     values: vec!["active".to_string(), "inactive".to_string()],
74/// };
75/// ```
76#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
77#[non_exhaustive]
78pub enum FieldType {
79    /// 字符串类型
80    ///
81    /// 用于存储文本数据,需要指定最大长度。
82    ///
83    /// # 字段
84    ///
85    /// - `max_length`: 字符串的最大长度(字符数)
86    ///
87    /// # 示例
88    ///
89    /// ```rust
90    /// use yang_base::table::FieldType;
91    ///
92    /// let field_type = FieldType::String { max_length: 100 };
93    /// ```
94    String {
95        /// 最大长度(字符数)
96        max_length: usize,
97    },
98
99    /// 整数类型
100    ///
101    /// 用于存储 32 位有符号整数(i32)。
102    ///
103    /// # 示例
104    ///
105    /// ```rust
106    /// use yang_base::table::FieldType;
107    ///
108    /// let field_type = FieldType::Integer;
109    /// ```
110    Integer,
111
112    /// 长整数类型
113    ///
114    /// 用于存储 64 位有符号整数(i64)。
115    ///
116    /// # 示例
117    ///
118    /// ```rust
119    /// use yang_base::table::FieldType;
120    ///
121    /// let field_type = FieldType::BigInt;
122    /// ```
123    BigInt,
124
125    /// 单精度浮点数类型
126    ///
127    /// 用于存储 32 位浮点数(f32)。
128    ///
129    /// # 示例
130    ///
131    /// ```rust
132    /// use yang_base::table::FieldType;
133    ///
134    /// let field_type = FieldType::Float;
135    /// ```
136    Float,
137
138    /// 双精度浮点数类型
139    ///
140    /// 用于存储 64 位浮点数(f64)。
141    ///
142    /// # 示例
143    ///
144    /// ```rust
145    /// use yang_base::table::FieldType;
146    ///
147    /// let field_type = FieldType::Double;
148    /// ```
149    Double,
150
151    /// 定点小数类型。
152    Decimal {
153        /// 总有效数字位数。
154        precision: u8,
155        /// 小数位数。
156        scale: u8,
157    },
158
159    /// 布尔类型
160    ///
161    /// 用于存储布尔值(true/false)。
162    ///
163    /// # 示例
164    ///
165    /// ```rust
166    /// use yang_base::table::FieldType;
167    ///
168    /// let field_type = FieldType::Boolean;
169    /// ```
170    Boolean,
171
172    /// 日期类型
173    ///
174    /// 用于存储日期(年-月-日),不包含时间信息。
175    ///
176    /// # 示例
177    ///
178    /// ```rust
179    /// use yang_base::table::FieldType;
180    ///
181    /// let field_type = FieldType::Date;
182    /// ```
183    Date,
184
185    /// 日期时间类型
186    ///
187    /// 用于存储日期和时间(年-月-日 时:分:秒)。
188    ///
189    /// # 示例
190    ///
191    /// ```rust
192    /// use yang_base::table::FieldType;
193    ///
194    /// let field_type = FieldType::DateTime;
195    /// ```
196    DateTime,
197
198    /// 时间戳类型
199    ///
200    /// 用于存储 Unix 时间戳(秒数)。
201    ///
202    /// # 示例
203    ///
204    /// ```rust
205    /// use yang_base::table::FieldType;
206    ///
207    /// let field_type = FieldType::Timestamp;
208    /// ```
209    Timestamp,
210
211    /// JSON 类型
212    ///
213    /// 用于存储 JSON 格式的复杂数据结构。
214    ///
215    /// # 示例
216    ///
217    /// ```rust
218    /// use yang_base::table::FieldType;
219    ///
220    /// let field_type = FieldType::Json;
221    /// ```
222    Json,
223
224    /// 文本类型
225    ///
226    /// 用于存储大文本数据,没有长度限制。
227    ///
228    /// # 示例
229    ///
230    /// ```rust
231    /// use yang_base::table::FieldType;
232    ///
233    /// let field_type = FieldType::Text;
234    /// ```
235    Text,
236
237    /// 枚举类型
238    ///
239    /// 用于存储预定义的可选值列表中的一个值。
240    ///
241    /// # 字段
242    ///
243    /// - `values`: 可选值列表
244    ///
245    /// # 示例
246    ///
247    /// ```rust
248    /// use yang_base::table::FieldType;
249    ///
250    /// let field_type = FieldType::Enum {
251    ///     values: vec![
252    ///         "pending".to_string(),
253    ///         "approved".to_string(),
254    ///         "rejected".to_string(),
255    ///     ],
256    /// };
257    /// ```
258    Enum {
259        /// 可选值列表
260        values: Vec<String>,
261    },
262
263    /// UUID 类型
264    ///
265    /// 运行期以连字符小写字符串表示。PostgreSQL 映射为原生 `uuid`;MySQL 没有
266    /// 原生 UUID,统一映射为定长 `CHAR(36)`(保留连字符文本形式,跨后端读写
267    /// 表示一致)。
268    ///
269    /// # 示例
270    ///
271    /// ```rust
272    /// use yang_base::table::FieldType;
273    ///
274    /// let field_type = FieldType::Uuid;
275    /// ```
276    Uuid,
277
278    /// 二进制类型
279    ///
280    /// 运行期以 Base64 字符串表示。PostgreSQL 映射为 `BYTEA`,MySQL 映射为
281    /// `BLOB`。
282    ///
283    /// # 示例
284    ///
285    /// ```rust
286    /// use yang_base::table::FieldType;
287    ///
288    /// let field_type = FieldType::Bytes;
289    /// ```
290    Bytes,
291
292    /// 数组类型(仅支持标量元素,如 `INTEGER[]` / `TEXT[]`)
293    ///
294    /// 运行期以 JSON 数组表示,元素按标量规则转换,数组内 NULL 保持 JSON
295    /// `null`。禁止嵌套数组与 `Json` 元素(无法无损映射到数据库数组字面量),
296    /// 构造/构建期会明确报错。MySQL 没有数组类型,渲染 DDL 时明确拒绝。
297    Array(Box<FieldType>),
298}
299
300impl FieldType {
301    /// 获取字段类型的显示名称
302    ///
303    /// # 返回值
304    ///
305    /// 返回字段类型的中文显示名称
306    ///
307    /// # 示例
308    ///
309    /// ```rust
310    /// use yang_base::table::FieldType;
311    ///
312    /// let field_type = FieldType::String { max_length: 50 };
313    /// assert_eq!(field_type.display_name(), "字符串");
314    ///
315    /// let field_type = FieldType::Integer;
316    /// assert_eq!(field_type.display_name(), "整数");
317    /// ```
318    pub fn display_name(&self) -> &str {
319        match self {
320            FieldType::String { .. } => "字符串",
321            FieldType::Integer => "整数",
322            FieldType::BigInt => "长整数",
323            FieldType::Float => "单精度浮点数",
324            FieldType::Double => "双精度浮点数",
325            FieldType::Decimal { .. } => "定点小数",
326            FieldType::Boolean => "布尔值",
327            FieldType::Date => "日期",
328            FieldType::DateTime => "日期时间",
329            FieldType::Timestamp => "时间戳",
330            FieldType::Json => "JSON",
331            FieldType::Text => "文本",
332            FieldType::Enum { .. } => "枚举",
333            FieldType::Uuid => "UUID",
334            FieldType::Bytes => "二进制",
335            FieldType::Array(_) => "数组",
336        }
337    }
338
339    /// 构造数组类型(标量元素)。
340    ///
341    /// 只做构造,不校验元素;构建期 `Table::build` 会拒绝嵌套数组与 `Json`
342    /// 元素等无法映射的声明。
343    ///
344    /// # 示例
345    ///
346    /// ```rust
347    /// use yang_base::table::FieldType;
348    ///
349    /// let field_type = FieldType::array(FieldType::Integer);
350    /// assert!(field_type.is_array());
351    /// ```
352    pub fn array(element: FieldType) -> Self {
353        FieldType::Array(Box::new(element))
354    }
355
356    /// 是否为 UUID 类型。
357    pub fn is_uuid(&self) -> bool {
358        matches!(self, FieldType::Uuid)
359    }
360
361    /// 是否为二进制类型。
362    pub fn is_binary(&self) -> bool {
363        matches!(self, FieldType::Bytes)
364    }
365
366    /// 是否为数组类型。
367    pub fn is_array(&self) -> bool {
368        matches!(self, FieldType::Array(_))
369    }
370
371    /// 检查字段类型是否为数值类型
372    ///
373    /// # 返回值
374    ///
375    /// 如果是数值类型(Integer, BigInt, Float, Double)返回 true,否则返回 false
376    ///
377    /// # 示例
378    ///
379    /// ```rust
380    /// use yang_base::table::FieldType;
381    ///
382    /// assert!(FieldType::Integer.is_numeric());
383    /// assert!(FieldType::Float.is_numeric());
384    /// assert!(!FieldType::String { max_length: 50 }.is_numeric());
385    /// ```
386    pub fn is_numeric(&self) -> bool {
387        matches!(
388            self,
389            FieldType::Integer
390                | FieldType::BigInt
391                | FieldType::Float
392                | FieldType::Double
393                | FieldType::Decimal { .. }
394        )
395    }
396
397    /// 检查字段类型是否为时间类型
398    ///
399    /// # 返回值
400    ///
401    /// 如果是时间类型(Date, DateTime, Timestamp)返回 true,否则返回 false
402    ///
403    /// # 示例
404    ///
405    /// ```rust
406    /// use yang_base::table::FieldType;
407    ///
408    /// assert!(FieldType::Date.is_temporal());
409    /// assert!(FieldType::DateTime.is_temporal());
410    /// assert!(!FieldType::String { max_length: 50 }.is_temporal());
411    /// ```
412    pub fn is_temporal(&self) -> bool {
413        matches!(
414            self,
415            FieldType::Date | FieldType::DateTime | FieldType::Timestamp
416        )
417    }
418
419    /// 检查字段类型是否为文本类型
420    ///
421    /// # 返回值
422    ///
423    /// 如果是文本类型(String, Text)返回 true,否则返回 false
424    ///
425    /// # 示例
426    ///
427    /// ```rust
428    /// use yang_base::table::FieldType;
429    ///
430    /// assert!(FieldType::String { max_length: 50 }.is_text());
431    /// assert!(FieldType::Text.is_text());
432    /// assert!(!FieldType::Integer.is_text());
433    /// ```
434    pub fn is_text(&self) -> bool {
435        matches!(self, FieldType::String { .. } | FieldType::Text)
436    }
437
438    /// 验证字段值是否符合字段类型要求
439    ///
440    /// # 参数
441    ///
442    /// - `field_name`: 字段名称(用于错误消息)
443    /// - `value`: 要验证的值
444    ///
445    /// # 返回值
446    ///
447    /// 如果验证通过返回 Ok(()),否则返回相应的错误
448    ///
449    /// # 示例
450    ///
451    /// ```rust
452    /// use yang_base::table::FieldType;
453    /// use serde_json::json;
454    ///
455    /// let field_type = FieldType::String { max_length: 10 };
456    /// assert!(field_type.validate("name", &json!("hello")).is_ok());
457    /// assert!(field_type.validate("name", &json!("this is too long")).is_err());
458    ///
459    /// let field_type = FieldType::Integer;
460    /// assert!(field_type.validate("age", &json!(25)).is_ok());
461    /// assert!(field_type.validate("age", &json!("not a number")).is_err());
462    /// ```
463    pub fn validate(&self, field_name: &str, value: &serde_json::Value) -> Result<(), BaseError> {
464        match self {
465            // 字符串类型验证
466            FieldType::String { max_length } => {
467                if let Some(s) = value.as_str() {
468                    let len = s.chars().count();
469                    if len > *max_length {
470                        return Err(BaseError::StringTooLong(
471                            field_name.to_string(),
472                            len,
473                            *max_length,
474                        ));
475                    }
476                    Ok(())
477                } else {
478                    Err(BaseError::InvalidFieldType(
479                        field_name.to_string(),
480                        format!("期望字符串类型,实际类型: {}", value_type_name(value)),
481                    ))
482                }
483            }
484
485            // 整数类型验证
486            FieldType::Integer => {
487                if value.is_i64() || value.is_u64() {
488                    // 检查是否在 i32 范围内
489                    if let Some(n) = value.as_i64() {
490                        if n >= i32::MIN as i64 && n <= i32::MAX as i64 {
491                            return Ok(());
492                        }
493                    }
494                    Err(BaseError::InvalidFieldType(
495                        field_name.to_string(),
496                        "整数值超出 i32 范围".to_string(),
497                    ))
498                } else {
499                    Err(BaseError::InvalidFieldType(
500                        field_name.to_string(),
501                        format!("期望整数类型,实际类型: {}", value_type_name(value)),
502                    ))
503                }
504            }
505
506            // 长整数类型验证
507            FieldType::BigInt => {
508                if value.as_i64().is_some() {
509                    Ok(())
510                } else {
511                    Err(BaseError::InvalidFieldType(
512                        field_name.to_string(),
513                        format!("期望 i64 范围内的长整数,实际值: {}", value),
514                    ))
515                }
516            }
517
518            // 单精度浮点数类型验证
519            FieldType::Float => {
520                if value.is_f64() || value.is_i64() || value.is_u64() {
521                    // 检查是否在 f32 范围内
522                    if let Some(n) = value.as_f64() {
523                        if n.is_finite() && n.abs() <= f32::MAX as f64 {
524                            return Ok(());
525                        }
526                    }
527                    Err(BaseError::InvalidFieldType(
528                        field_name.to_string(),
529                        "浮点数值超出 f32 范围".to_string(),
530                    ))
531                } else {
532                    Err(BaseError::InvalidFieldType(
533                        field_name.to_string(),
534                        format!("期望浮点数类型,实际类型: {}", value_type_name(value)),
535                    ))
536                }
537            }
538
539            // 双精度浮点数类型验证
540            FieldType::Double => {
541                if value.is_f64() || value.is_i64() || value.is_u64() {
542                    Ok(())
543                } else {
544                    Err(BaseError::InvalidFieldType(
545                        field_name.to_string(),
546                        format!("期望双精度浮点数类型,实际类型: {}", value_type_name(value)),
547                    ))
548                }
549            }
550
551            FieldType::Decimal { precision, scale } => {
552                validate_decimal(field_name, value, *precision, *scale)
553            }
554
555            // 布尔类型验证
556            FieldType::Boolean => {
557                if value.is_boolean() {
558                    Ok(())
559                } else {
560                    Err(BaseError::InvalidFieldType(
561                        field_name.to_string(),
562                        format!("期望布尔类型,实际类型: {}", value_type_name(value)),
563                    ))
564                }
565            }
566
567            // 日期类型验证
568            FieldType::Date => validate_date(field_name, value),
569
570            // 日期时间类型验证
571            FieldType::DateTime => validate_datetime(field_name, value),
572
573            // 时间戳类型验证
574            FieldType::Timestamp => validate_timestamp(field_name, value),
575
576            // 枚举类型验证
577            FieldType::Enum { values } => {
578                if let Some(s) = value.as_str() {
579                    if values.contains(&s.to_string()) {
580                        Ok(())
581                    } else {
582                        Err(BaseError::InvalidEnumValue(
583                            field_name.to_string(),
584                            s.to_string(),
585                        ))
586                    }
587                } else {
588                    Err(BaseError::InvalidFieldType(
589                        field_name.to_string(),
590                        format!(
591                            "期望字符串类型的枚举值,实际类型: {}",
592                            value_type_name(value)
593                        ),
594                    ))
595                }
596            }
597
598            // JSON 类型验证
599            FieldType::Json => {
600                if value.is_object() || value.is_array() {
601                    Ok(())
602                } else {
603                    Err(BaseError::InvalidFieldType(
604                        field_name.to_string(),
605                        format!("期望 JSON 对象或数组,实际类型: {}", value_type_name(value)),
606                    ))
607                }
608            }
609
610            // 文本类型验证:与 String 对等地要求字符串,但不施加长度上限
611            FieldType::Text => {
612                if value.as_str().is_some() {
613                    Ok(())
614                } else {
615                    Err(BaseError::InvalidFieldType(
616                        field_name.to_string(),
617                        format!("期望文本字符串类型,实际类型: {}", value_type_name(value)),
618                    ))
619                }
620            }
621
622            // UUID 类型:运行期以字符串表示,格式由数据库写入路径校验。
623            FieldType::Uuid => {
624                if value.as_str().is_some() {
625                    Ok(())
626                } else {
627                    Err(BaseError::InvalidFieldType(
628                        field_name.to_string(),
629                        format!("期望 UUID 字符串,实际类型: {}", value_type_name(value)),
630                    ))
631                }
632            }
633
634            // 二进制类型:运行期以 Base64 字符串表示。
635            FieldType::Bytes => {
636                if value.as_str().is_some() {
637                    Ok(())
638                } else {
639                    Err(BaseError::InvalidFieldType(
640                        field_name.to_string(),
641                        format!(
642                            "期望 Base64 二进制字符串,实际类型: {}",
643                            value_type_name(value)
644                        ),
645                    ))
646                }
647            }
648
649            // 数组类型:JSON 数组,元素按标量规则递归校验,数组内 NULL 允许。
650            FieldType::Array(element) => {
651                let Some(items) = value.as_array() else {
652                    return Err(BaseError::InvalidFieldType(
653                        field_name.to_string(),
654                        format!("期望 JSON 数组,实际类型: {}", value_type_name(value)),
655                    ));
656                };
657                for item in items {
658                    if !item.is_null() {
659                        element.validate(field_name, item)?;
660                    }
661                }
662                Ok(())
663            }
664        }
665    }
666}
667
668fn validate_decimal(
669    field_name: &str,
670    value: &serde_json::Value,
671    precision: u8,
672    scale: u8,
673) -> Result<(), BaseError> {
674    let text = match value {
675        serde_json::Value::String(value) => std::borrow::Cow::Borrowed(value.as_str()),
676        serde_json::Value::Number(value) => std::borrow::Cow::Owned(value.to_string()),
677        _ => {
678            return Err(BaseError::InvalidFieldType(
679                field_name.to_string(),
680                format!(
681                    "期望十进制数字或字符串,实际类型: {}",
682                    value_type_name(value)
683                ),
684            ));
685        }
686    };
687    let unsigned = text.strip_prefix('-').unwrap_or(text.as_ref());
688    let (integer, fraction) = unsigned.split_once('.').unwrap_or((unsigned, ""));
689    let digits = integer.len() + fraction.len();
690    let valid = !integer.is_empty()
691        && integer.bytes().all(|byte| byte.is_ascii_digit())
692        && fraction.bytes().all(|byte| byte.is_ascii_digit())
693        && digits <= usize::from(precision)
694        && fraction.len() <= usize::from(scale);
695    if valid {
696        Ok(())
697    } else {
698        Err(BaseError::InvalidFieldType(
699            field_name.to_string(),
700            format!("值 {text} 不符合 DECIMAL({precision}, {scale})"),
701        ))
702    }
703}
704
705fn validate_date(field_name: &str, value: &serde_json::Value) -> Result<(), BaseError> {
706    if let Some(s) = value.as_str() {
707        chrono::NaiveDate::parse_from_str(s, "%Y-%m-%d")
708            .map(|_| ())
709            .map_err(|_| {
710                BaseError::InvalidFieldType(
711                    field_name.to_string(),
712                    format!("日期格式无效,期望 YYYY-MM-DD,实际: {}", s),
713                )
714            })
715    } else {
716        Err(BaseError::InvalidFieldType(
717            field_name.to_string(),
718            format!("期望日期字符串类型,实际类型: {}", value_type_name(value)),
719        ))
720    }
721}
722
723fn validate_datetime(field_name: &str, value: &serde_json::Value) -> Result<(), BaseError> {
724    if let Some(s) = value.as_str() {
725        chrono::DateTime::parse_from_rfc3339(s)
726            .map(|_| ())
727            .map_err(|_| {
728                BaseError::InvalidFieldType(
729                    field_name.to_string(),
730                    format!("日期时间格式无效,期望 RFC 3339,实际: {s}"),
731                )
732            })
733    } else {
734        Err(BaseError::InvalidFieldType(
735            field_name.to_string(),
736            format!(
737                "期望日期时间字符串类型,实际类型: {}",
738                value_type_name(value)
739            ),
740        ))
741    }
742}
743
744fn validate_timestamp(field_name: &str, value: &serde_json::Value) -> Result<(), BaseError> {
745    if let Some(ts) = value.as_i64() {
746        chrono::DateTime::<chrono::Utc>::from_timestamp_secs(ts)
747            .map(|_| ())
748            .ok_or_else(|| {
749                BaseError::InvalidFieldType(
750                    field_name.to_string(),
751                    format!("时间戳超出有效范围,实际: {}", ts),
752                )
753            })
754    } else {
755        Err(BaseError::InvalidFieldType(
756            field_name.to_string(),
757            format!("期望 Unix 时间戳整数,实际类型: {}", value_type_name(value)),
758        ))
759    }
760}
761
762#[cfg(test)]
763mod tests {
764    use super::*;
765
766    /// 方言上界:MySQL 保持 utf8mb4 行上限,PostgreSQL 放宽到 varchar 的 10,485,760。
767    #[test]
768    fn varchar_limit_follows_backend_dialect() {
769        assert_eq!(MYSQL_MAX_VARCHAR_LENGTH, 16_383);
770        assert_eq!(POSTGRES_MAX_VARCHAR_LENGTH, 10_485_760);
771
772        #[cfg(all(feature = "mysql", not(feature = "postgres")))]
773        assert_eq!(MAX_VARCHAR_LENGTH, MYSQL_MAX_VARCHAR_LENGTH);
774        #[cfg(feature = "postgres")]
775        assert_eq!(MAX_VARCHAR_LENGTH, POSTGRES_MAX_VARCHAR_LENGTH);
776        #[cfg(not(any(feature = "mysql", feature = "postgres")))]
777        assert_eq!(MAX_VARCHAR_LENGTH, MYSQL_MAX_VARCHAR_LENGTH);
778    }
779
780    #[test]
781    fn test_field_type_display_name() {
782        assert_eq!(
783            FieldType::String { max_length: 50 }.display_name(),
784            "字符串"
785        );
786        assert_eq!(FieldType::Integer.display_name(), "整数");
787        assert_eq!(FieldType::BigInt.display_name(), "长整数");
788        assert_eq!(FieldType::Float.display_name(), "单精度浮点数");
789        assert_eq!(FieldType::Double.display_name(), "双精度浮点数");
790        assert_eq!(FieldType::Boolean.display_name(), "布尔值");
791        assert_eq!(FieldType::Date.display_name(), "日期");
792        assert_eq!(FieldType::DateTime.display_name(), "日期时间");
793        assert_eq!(FieldType::Timestamp.display_name(), "时间戳");
794        assert_eq!(FieldType::Json.display_name(), "JSON");
795        assert_eq!(FieldType::Text.display_name(), "文本");
796        assert_eq!(
797            FieldType::Enum {
798                values: vec!["a".to_string()]
799            }
800            .display_name(),
801            "枚举"
802        );
803    }
804
805    #[test]
806    fn test_is_numeric() {
807        assert!(FieldType::Integer.is_numeric());
808        assert!(FieldType::BigInt.is_numeric());
809        assert!(FieldType::Float.is_numeric());
810        assert!(FieldType::Double.is_numeric());
811        assert!(!FieldType::String { max_length: 50 }.is_numeric());
812        assert!(!FieldType::Boolean.is_numeric());
813    }
814
815    #[test]
816    fn test_is_temporal() {
817        assert!(FieldType::Date.is_temporal());
818        assert!(FieldType::DateTime.is_temporal());
819        assert!(FieldType::Timestamp.is_temporal());
820        assert!(!FieldType::String { max_length: 50 }.is_temporal());
821        assert!(!FieldType::Integer.is_temporal());
822    }
823
824    #[test]
825    fn test_is_text() {
826        assert!(FieldType::String { max_length: 50 }.is_text());
827        assert!(FieldType::Text.is_text());
828        assert!(!FieldType::Integer.is_text());
829        assert!(!FieldType::Boolean.is_text());
830    }
831
832    #[test]
833    fn test_field_type_equality() {
834        let type1 = FieldType::String { max_length: 50 };
835        let type2 = FieldType::String { max_length: 50 };
836        let type3 = FieldType::String { max_length: 100 };
837
838        assert_eq!(type1, type2);
839        assert_ne!(type1, type3);
840    }
841
842    #[test]
843    fn test_enum_type() {
844        let enum_type = FieldType::Enum {
845            values: vec![
846                "pending".to_string(),
847                "approved".to_string(),
848                "rejected".to_string(),
849            ],
850        };
851
852        assert_eq!(enum_type.display_name(), "枚举");
853        assert!(!enum_type.is_numeric());
854        assert!(!enum_type.is_temporal());
855        assert!(!enum_type.is_text());
856    }
857
858    // ==================== validate 方法测试 ====================
859
860    #[test]
861    fn test_validate_string_success() {
862        let field_type = FieldType::String { max_length: 10 };
863
864        // 正常情况
865        assert!(field_type
866            .validate("name", &serde_json::json!("hello"))
867            .is_ok());
868        assert!(field_type.validate("name", &serde_json::json!("")).is_ok());
869
870        // 边界情况:正好 10 个字符
871        assert!(field_type
872            .validate("name", &serde_json::json!("1234567890"))
873            .is_ok());
874    }
875
876    #[test]
877    fn test_validate_string_too_long() {
878        let field_type = FieldType::String { max_length: 10 };
879
880        // 超过最大长度
881        let result = field_type.validate("name", &serde_json::json!("this is too long"));
882        assert!(result.is_err());
883
884        assert!(
885            matches!(result, Err(BaseError::StringTooLong(ref field, 16, 10)) if field == "name"),
886            "期望 StringTooLong 错误,实际: {:?}",
887            result
888        );
889    }
890
891    #[test]
892    fn test_validate_string_invalid_type() {
893        let field_type = FieldType::String { max_length: 10 };
894
895        // 类型不匹配
896        assert!(field_type
897            .validate("name", &serde_json::json!(123))
898            .is_err());
899        assert!(field_type
900            .validate("name", &serde_json::json!(true))
901            .is_err());
902        assert!(field_type
903            .validate("name", &serde_json::json!(null))
904            .is_err());
905    }
906
907    #[test]
908    fn test_validate_integer_success() {
909        let field_type = FieldType::Integer;
910
911        // 正常情况
912        assert!(field_type.validate("age", &serde_json::json!(25)).is_ok());
913        assert!(field_type.validate("age", &serde_json::json!(0)).is_ok());
914        assert!(field_type.validate("age", &serde_json::json!(-100)).is_ok());
915
916        // 边界情况:i32 范围
917        assert!(field_type
918            .validate("age", &serde_json::json!(i32::MAX))
919            .is_ok());
920        assert!(field_type
921            .validate("age", &serde_json::json!(i32::MIN))
922            .is_ok());
923    }
924
925    #[test]
926    fn test_validate_integer_out_of_range() {
927        let field_type = FieldType::Integer;
928
929        // 超出 i32 范围
930        let result = field_type.validate("age", &serde_json::json!(i64::MAX));
931        assert!(result.is_err());
932    }
933
934    #[test]
935    fn test_validate_integer_invalid_type() {
936        let field_type = FieldType::Integer;
937
938        // 类型不匹配
939        assert!(field_type
940            .validate("age", &serde_json::json!("not a number"))
941            .is_err());
942        assert!(field_type
943            .validate("age", &serde_json::json!(true))
944            .is_err());
945        assert!(field_type.validate("age", &serde_json::json!(3.5)).is_err());
946    }
947
948    #[test]
949    fn test_validate_bigint_success() {
950        let field_type = FieldType::BigInt;
951
952        // 正常情况
953        assert!(field_type
954            .validate("id", &serde_json::json!(123456789))
955            .is_ok());
956        assert!(field_type
957            .validate("id", &serde_json::json!(i64::MAX))
958            .is_ok());
959        assert!(field_type
960            .validate("id", &serde_json::json!(i64::MIN))
961            .is_ok());
962    }
963
964    #[test]
965    fn test_validate_bigint_invalid_type() {
966        let field_type = FieldType::BigInt;
967
968        // 类型不匹配或超出 MySQL BIGINT 有符号范围
969        assert!(field_type
970            .validate("id", &serde_json::json!("not a number"))
971            .is_err());
972        assert!(field_type.validate("id", &serde_json::json!(3.5)).is_err());
973        assert!(field_type
974            .validate("id", &serde_json::json!(u64::MAX))
975            .is_err());
976    }
977
978    #[test]
979    fn test_validate_float_success() {
980        let field_type = FieldType::Float;
981
982        // 正常情况
983        assert!(field_type
984            .validate("price", &serde_json::json!(3.5))
985            .is_ok());
986        assert!(field_type
987            .validate("price", &serde_json::json!(0.0))
988            .is_ok());
989        assert!(field_type
990            .validate("price", &serde_json::json!(-1.5))
991            .is_ok());
992
993        // 整数也可以转换为浮点数
994        assert!(field_type
995            .validate("price", &serde_json::json!(100))
996            .is_ok());
997    }
998
999    #[test]
1000    fn test_validate_float_invalid_type() {
1001        let field_type = FieldType::Float;
1002
1003        // 类型不匹配
1004        assert!(field_type
1005            .validate("price", &serde_json::json!("not a number"))
1006            .is_err());
1007        assert!(field_type
1008            .validate("price", &serde_json::json!(true))
1009            .is_err());
1010    }
1011
1012    #[test]
1013    fn test_validate_double_success() {
1014        let field_type = FieldType::Double;
1015
1016        // 正常情况
1017        assert!(field_type
1018            .validate("amount", &serde_json::json!(123.456))
1019            .is_ok());
1020        assert!(field_type
1021            .validate("amount", &serde_json::json!(0.0))
1022            .is_ok());
1023        assert!(field_type
1024            .validate("amount", &serde_json::json!(100))
1025            .is_ok());
1026    }
1027
1028    #[test]
1029    fn test_validate_double_invalid_type() {
1030        let field_type = FieldType::Double;
1031
1032        // 类型不匹配
1033        assert!(field_type
1034            .validate("amount", &serde_json::json!("not a number"))
1035            .is_err());
1036        assert!(field_type
1037            .validate("amount", &serde_json::json!(true))
1038            .is_err());
1039    }
1040
1041    #[test]
1042    fn test_validate_decimal_preserves_fixed_point_contract() {
1043        let field_type = FieldType::Decimal {
1044            precision: 8,
1045            scale: 2,
1046        };
1047        assert!(field_type
1048            .validate("amount", &serde_json::json!("123456.78"))
1049            .is_ok());
1050        assert!(field_type
1051            .validate("amount", &serde_json::json!("1234567.89"))
1052            .is_err());
1053        assert!(field_type
1054            .validate("amount", &serde_json::json!("1.234"))
1055            .is_err());
1056        assert!(field_type
1057            .validate("amount", &serde_json::json!("not-a-number"))
1058            .is_err());
1059    }
1060
1061    #[test]
1062    fn test_validate_boolean_success() {
1063        let field_type = FieldType::Boolean;
1064
1065        // 正常情况
1066        assert!(field_type
1067            .validate("active", &serde_json::json!(true))
1068            .is_ok());
1069        assert!(field_type
1070            .validate("active", &serde_json::json!(false))
1071            .is_ok());
1072    }
1073
1074    #[test]
1075    fn test_validate_boolean_invalid_type() {
1076        let field_type = FieldType::Boolean;
1077
1078        // 类型不匹配
1079        assert!(field_type
1080            .validate("active", &serde_json::json!("true"))
1081            .is_err());
1082        assert!(field_type
1083            .validate("active", &serde_json::json!(1))
1084            .is_err());
1085        assert!(field_type
1086            .validate("active", &serde_json::json!(0))
1087            .is_err());
1088    }
1089
1090    #[test]
1091    fn test_validate_date_success() {
1092        let field_type = FieldType::Date;
1093
1094        assert!(field_type
1095            .validate("birthday", &serde_json::json!("2026-05-27"))
1096            .is_ok());
1097    }
1098
1099    #[test]
1100    fn test_validate_date_invalid_format() {
1101        let field_type = FieldType::Date;
1102
1103        let result = field_type.validate("birthday", &serde_json::json!("2026/05/27"));
1104        assert!(result.is_err());
1105        assert!(
1106            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "birthday")
1107        );
1108    }
1109
1110    #[test]
1111    fn test_validate_date_invalid_type() {
1112        let field_type = FieldType::Date;
1113
1114        let result = field_type.validate("birthday", &serde_json::json!(20260527));
1115        assert!(result.is_err());
1116        assert!(
1117            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "birthday")
1118        );
1119    }
1120
1121    #[test]
1122    fn test_validate_datetime_success() {
1123        let field_type = FieldType::DateTime;
1124
1125        assert!(field_type
1126            .validate(
1127                "created_at",
1128                &serde_json::json!("2026-05-27T13:45:30+08:00"),
1129            )
1130            .is_ok());
1131        assert!(field_type
1132            .validate("created_at", &serde_json::json!("2026-05-27T05:45:30Z"))
1133            .is_ok());
1134    }
1135
1136    #[test]
1137    fn test_validate_datetime_invalid_format() {
1138        let field_type = FieldType::DateTime;
1139
1140        // 缺少 RFC 3339 时区信息的 naive datetime 必须拒绝。
1141        assert!(field_type
1142            .validate("created_at", &serde_json::json!("2026-05-27T13:45:30"))
1143            .is_err());
1144        assert!(field_type
1145            .validate("created_at", &serde_json::json!("2026-05-27 13:45:30"))
1146            .is_err());
1147
1148        // 真正非法的格式(斜杠分隔)仍然返回错误
1149        let result = field_type.validate("created_at", &serde_json::json!("2026/05/27 13:45:30"));
1150        assert!(result.is_err());
1151        assert!(
1152            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "created_at")
1153        );
1154    }
1155
1156    #[test]
1157    fn test_validate_datetime_matches_json_schema_date_time_format() {
1158        // JSON Schema 的 `date-time` format 使用 RFC 3339。
1159        let field_type = FieldType::DateTime;
1160        let value = serde_json::json!("2026-05-27T13:45:30.123+08:00");
1161        assert!(field_type.validate("created_at", &value).is_ok());
1162    }
1163
1164    #[test]
1165    fn test_validate_timestamp_success() {
1166        let field_type = FieldType::Timestamp;
1167
1168        assert!(field_type
1169            .validate("created_at", &serde_json::json!(1_764_221_130_i64))
1170            .is_ok());
1171    }
1172
1173    #[test]
1174    fn test_validate_timestamp_invalid_type() {
1175        let field_type = FieldType::Timestamp;
1176
1177        let result = field_type.validate("created_at", &serde_json::json!("2026-05-27 13:45:30"));
1178        assert!(result.is_err());
1179        assert!(
1180            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "created_at")
1181        );
1182    }
1183
1184    #[test]
1185    fn test_validate_text_success() {
1186        let field_type = FieldType::Text;
1187
1188        // 任意长度字符串均可(无长度上限)
1189        assert!(field_type
1190            .validate("content", &serde_json::json!("hello"))
1191            .is_ok());
1192        assert!(field_type
1193            .validate("content", &serde_json::json!("a".repeat(100_000)))
1194            .is_ok());
1195        assert!(field_type
1196            .validate("content", &serde_json::json!(""))
1197            .is_ok());
1198    }
1199
1200    #[test]
1201    fn test_validate_text_invalid_type() {
1202        let field_type = FieldType::Text;
1203
1204        // 非字符串返回 InvalidFieldType
1205        let result = field_type.validate("content", &serde_json::json!(123));
1206        assert!(
1207            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "content")
1208        );
1209        assert!(field_type
1210            .validate("content", &serde_json::json!(true))
1211            .is_err());
1212        assert!(field_type
1213            .validate("content", &serde_json::json!(null))
1214            .is_err());
1215    }
1216
1217    #[test]
1218    fn test_validate_enum_success() {
1219        let field_type = FieldType::Enum {
1220            values: vec![
1221                "pending".to_string(),
1222                "approved".to_string(),
1223                "rejected".to_string(),
1224            ],
1225        };
1226
1227        // 正常情况
1228        assert!(field_type
1229            .validate("status", &serde_json::json!("pending"))
1230            .is_ok());
1231        assert!(field_type
1232            .validate("status", &serde_json::json!("approved"))
1233            .is_ok());
1234        assert!(field_type
1235            .validate("status", &serde_json::json!("rejected"))
1236            .is_ok());
1237    }
1238
1239    #[test]
1240    fn test_validate_enum_invalid_value() {
1241        let field_type = FieldType::Enum {
1242            values: vec![
1243                "pending".to_string(),
1244                "approved".to_string(),
1245                "rejected".to_string(),
1246            ],
1247        };
1248
1249        // 枚举值不在列表中
1250        let result = field_type.validate("status", &serde_json::json!("invalid"));
1251        assert!(result.is_err());
1252
1253        assert!(
1254            matches!(result, Err(BaseError::InvalidEnumValue(ref field, ref value)) if field == "status" && value == "invalid"),
1255            "期望 InvalidEnumValue 错误,实际: {:?}",
1256            result
1257        );
1258    }
1259
1260    #[test]
1261    fn test_validate_enum_invalid_type() {
1262        let field_type = FieldType::Enum {
1263            values: vec!["pending".to_string()],
1264        };
1265
1266        // 类型不匹配
1267        assert!(field_type
1268            .validate("status", &serde_json::json!(123))
1269            .is_err());
1270        assert!(field_type
1271            .validate("status", &serde_json::json!(true))
1272            .is_err());
1273    }
1274
1275    #[test]
1276    fn test_validate_json_success() {
1277        let field_type = FieldType::Json;
1278
1279        // JSON 对象
1280        assert!(field_type
1281            .validate("data", &serde_json::json!({"key": "value"}))
1282            .is_ok());
1283
1284        // JSON 数组
1285        assert!(field_type
1286            .validate("data", &serde_json::json!([1, 2, 3]))
1287            .is_ok());
1288    }
1289
1290    #[test]
1291    fn test_validate_json_invalid_format() {
1292        let field_type = FieldType::Json;
1293
1294        // JSON 字段只接受结构化对象/数组;即使字符串内容能解析为 JSON 也拒绝。
1295        let result = field_type.validate("data", &serde_json::json!("not a json"));
1296        assert!(result.is_err());
1297
1298        assert!(field_type
1299            .validate("data", &serde_json::json!("{\"key\": \"value\"}"))
1300            .is_err());
1301        assert!(field_type
1302            .validate("data", &serde_json::json!("[1, 2, 3]"))
1303            .is_err());
1304
1305        assert!(
1306            matches!(result, Err(BaseError::InvalidFieldType(ref field, _)) if field == "data"),
1307            "期望 InvalidFieldType 错误,实际: {:?}",
1308            result
1309        );
1310    }
1311
1312    #[test]
1313    fn test_validate_json_invalid_type() {
1314        let field_type = FieldType::Json;
1315
1316        // 类型不匹配(不是对象、数组或字符串)
1317        assert!(field_type
1318            .validate("data", &serde_json::json!(123))
1319            .is_err());
1320        assert!(field_type
1321            .validate("data", &serde_json::json!(true))
1322            .is_err());
1323        assert!(field_type
1324            .validate("data", &serde_json::json!(null))
1325            .is_err());
1326    }
1327
1328    // ==================== UUID / Bytes / Array 测试 ====================
1329
1330    #[test]
1331    fn test_new_variants_display_name_and_predicates() {
1332        assert_eq!(FieldType::Uuid.display_name(), "UUID");
1333        assert_eq!(FieldType::Bytes.display_name(), "二进制");
1334        assert_eq!(FieldType::array(FieldType::Integer).display_name(), "数组");
1335
1336        assert!(FieldType::Uuid.is_uuid());
1337        assert!(!FieldType::Bytes.is_uuid());
1338        assert!(FieldType::Bytes.is_binary());
1339        assert!(!FieldType::Uuid.is_binary());
1340        let array = FieldType::array(FieldType::Text);
1341        assert!(array.is_array());
1342        assert!(!FieldType::Text.is_array());
1343        assert!(!array.is_text());
1344        assert!(!array.is_numeric());
1345    }
1346
1347    #[test]
1348    fn test_validate_uuid_and_bytes_require_strings() {
1349        assert!(FieldType::Uuid
1350            .validate(
1351                "uid",
1352                &serde_json::json!("11111111-1111-1111-1111-111111111111")
1353            )
1354            .is_ok());
1355        assert!(FieldType::Uuid
1356            .validate("uid", &serde_json::json!(123))
1357            .is_err());
1358
1359        assert!(FieldType::Bytes
1360            .validate("payload", &serde_json::json!("3q2+7w=="))
1361            .is_ok());
1362        assert!(FieldType::Bytes
1363            .validate("payload", &serde_json::json!([1, 2]))
1364            .is_err());
1365    }
1366
1367    #[test]
1368    fn test_validate_array_recurses_scalar_rules_and_allows_null_elements() {
1369        let field_type = FieldType::array(FieldType::Integer);
1370        assert!(field_type
1371            .validate("numbers", &serde_json::json!([1, 2, null]))
1372            .is_ok());
1373        // 元素类型不匹配时递归校验必须报错。
1374        assert!(field_type
1375            .validate("numbers", &serde_json::json!([1, "two"]))
1376            .is_err());
1377        // 非数组值直接拒绝。
1378        assert!(field_type
1379            .validate("numbers", &serde_json::json!(1))
1380            .is_err());
1381
1382        let text_array = FieldType::array(FieldType::Text);
1383        assert!(text_array
1384            .validate("tags", &serde_json::json!(["a", null, "c"]))
1385            .is_ok());
1386        assert!(text_array
1387            .validate("tags", &serde_json::json!([1]))
1388            .is_err());
1389    }
1390}