Skip to main content

yang_base/table/
field_config.rs

1//! 字段配置
2//!
3//! 提供数据表字段的配置功能,包括字段类型、验证规则、权限控制和关联表信息。
4
5use crate::error::BaseError;
6use crate::table::{FieldType, Validator};
7use serde::{Deserialize, Serialize};
8use std::collections::HashSet;
9
10/// 字段配置
11///
12/// 定义单个字段的所有属性,包括:
13/// - 字段名称和显示名称
14/// - 字段类型
15/// - 必填标记和默认值
16/// - 验证器列表
17/// - 字段级权限配置
18/// - 关联表信息
19///
20/// # 示例
21///
22/// ```rust
23/// use yang_base::table::{FieldConfig, FieldType, Validator, FieldPermissions};
24/// use serde_json::json;
25/// use std::collections::HashSet;
26///
27/// // 创建一个必填的用户名字段
28/// let username_field = FieldConfig::new("username", FieldType::String { max_length: 50 })
29///     .display_name("用户名")
30///     .required(true)
31///     .validator(Validator::MinLength(3))
32///     .validator(Validator::MaxLength(50));
33///
34/// // 创建一个带默认值的状态字段
35/// let status_field = FieldConfig::new("status", FieldType::Enum {
36///     values: vec!["active".to_string(), "inactive".to_string()],
37/// })
38///     .display_name("状态")
39///     .default_value(json!("active"));
40///
41/// // 创建一个带权限控制的邮箱字段
42/// let email_field = FieldConfig::new("email", FieldType::String { max_length: 100 })
43///     .display_name("邮箱")
44///     .required(true)
45///     .validator(Validator::Email)
46///     .permissions(FieldPermissions {
47///         readable_roles: HashSet::from(["admin".to_string(), "user".to_string()]),
48///         writable_roles: HashSet::from(["admin".to_string()]),
49///         filterable_roles: HashSet::new(),
50///         sortable_roles: HashSet::new(),
51///     });
52/// ```
53#[derive(Debug, Clone)]
54#[non_exhaustive]
55pub struct FieldConfig {
56    /// 字段名
57    ///
58    /// 数据库中的字段名称,通常使用蛇形命名法(snake_case)
59    pub name: String,
60
61    /// 显示名称
62    ///
63    /// 用于前端展示的字段名称,通常使用中文
64    pub display_name: String,
65
66    /// 字段类型
67    ///
68    /// 定义字段的数据类型,如字符串、整数、枚举等
69    pub field_type: FieldType,
70
71    /// 是否必填
72    ///
73    /// 如果为 true,则字段值不能为 null
74    pub required: bool,
75
76    /// 默认值
77    ///
78    /// 当插入数据时未提供该字段值时使用的默认值
79    pub default_value: Option<serde_json::Value>,
80
81    /// 验证器列表
82    ///
83    /// 用于验证字段值的验证器,按顺序执行
84    pub validators: Vec<Validator>,
85
86    /// 字段权限
87    ///
88    /// 定义不同角色对该字段的访问权限
89    pub permissions: FieldPermissions,
90
91    /// 是否可筛选
92    ///
93    /// 如果为 true,则该字段可以用于 WHERE 条件筛选
94    pub filterable: bool,
95
96    /// 是否可排序
97    ///
98    /// 如果为 true,则该字段可以用于 ORDER BY 排序
99    pub sortable: bool,
100
101    /// 关联表配置
102    ///
103    /// 用于外键字段,定义与其他表的关联关系
104    pub relation: Option<RelationConfig>,
105}
106
107impl FieldConfig {
108    /// 创建新的字段配置
109    ///
110    /// # 参数
111    ///
112    /// - `name`: 字段名称
113    /// - `field_type`: 字段类型
114    ///
115    /// # 返回值
116    ///
117    /// 返回一个新的 FieldConfig 实例,使用默认配置
118    ///
119    /// # 示例
120    ///
121    /// ```rust
122    /// use yang_base::table::{FieldConfig, FieldType};
123    ///
124    /// let field = FieldConfig::new("username", FieldType::String { max_length: 50 });
125    /// assert_eq!(field.name, "username");
126    /// assert!(!field.required);
127    /// ```
128    pub fn new(name: impl Into<String>, field_type: FieldType) -> Self {
129        Self {
130            name: name.into(),
131            display_name: String::new(),
132            field_type,
133            required: false,
134            default_value: None,
135            validators: Vec::new(),
136            permissions: FieldPermissions::default(),
137            filterable: true,
138            sortable: true,
139            relation: None,
140        }
141    }
142
143    /// 设置显示名称
144    ///
145    /// # 参数
146    ///
147    /// - `name`: 显示名称
148    ///
149    /// # 返回值
150    ///
151    /// 返回 self,支持链式调用
152    ///
153    /// # 示例
154    ///
155    /// ```rust
156    /// use yang_base::table::{FieldConfig, FieldType};
157    ///
158    /// let field = FieldConfig::new("username", FieldType::String { max_length: 50 })
159    ///     .display_name("用户名");
160    /// assert_eq!(field.display_name, "用户名");
161    /// ```
162    pub fn display_name(mut self, name: impl Into<String>) -> Self {
163        self.display_name = name.into();
164        self
165    }
166
167    /// 设置必填标记
168    ///
169    /// # 参数
170    ///
171    /// - `required`: 是否必填
172    ///
173    /// # 返回值
174    ///
175    /// 返回 self,支持链式调用
176    ///
177    /// # 示例
178    ///
179    /// ```rust
180    /// use yang_base::table::{FieldConfig, FieldType};
181    ///
182    /// let field = FieldConfig::new("email", FieldType::String { max_length: 100 })
183    ///     .required(true);
184    /// assert!(field.required);
185    /// ```
186    pub fn required(mut self, required: bool) -> Self {
187        self.required = required;
188        self
189    }
190
191    /// 设置默认值
192    ///
193    /// # 参数
194    ///
195    /// - `value`: 默认值
196    ///
197    /// # 返回值
198    ///
199    /// 返回 self,支持链式调用
200    ///
201    /// # 示例
202    ///
203    /// ```rust
204    /// use yang_base::table::{FieldConfig, FieldType};
205    /// use serde_json::json;
206    ///
207    /// let field = FieldConfig::new("status", FieldType::String { max_length: 20 })
208    ///     .default_value(json!("active"));
209    /// assert_eq!(field.default_value, Some(json!("active")));
210    /// ```
211    pub fn default_value(mut self, value: serde_json::Value) -> Self {
212        self.default_value = Some(value);
213        self
214    }
215
216    /// 添加验证器
217    ///
218    /// # 参数
219    ///
220    /// - `validator`: 验证器
221    ///
222    /// # 返回值
223    ///
224    /// 返回 self,支持链式调用
225    ///
226    /// # 示例
227    ///
228    /// ```rust
229    /// use yang_base::table::{FieldConfig, FieldType, Validator};
230    ///
231    /// let field = FieldConfig::new("age", FieldType::Integer)
232    ///     .validator(Validator::Min(0.0))
233    ///     .validator(Validator::Max(150.0));
234    /// assert_eq!(field.validators.len(), 2);
235    /// ```
236    pub fn validator(mut self, validator: Validator) -> Self {
237        self.validators.push(validator);
238        self
239    }
240
241    /// 设置字段权限
242    ///
243    /// # 参数
244    ///
245    /// - `permissions`: 字段权限配置
246    ///
247    /// # 返回值
248    ///
249    /// 返回 self,支持链式调用
250    ///
251    /// # 示例
252    ///
253    /// ```rust
254    /// use yang_base::table::{FieldConfig, FieldType, FieldPermissions};
255    /// use std::collections::HashSet;
256    ///
257    /// let permissions = FieldPermissions {
258    ///     readable_roles: HashSet::from(["admin".to_string()]),
259    ///     writable_roles: HashSet::from(["admin".to_string()]),
260    ///     filterable_roles: HashSet::new(),
261    ///     sortable_roles: HashSet::new(),
262    /// };
263    ///
264    /// let field = FieldConfig::new("salary", FieldType::Double)
265    ///     .permissions(permissions);
266    /// assert_eq!(field.permissions.readable_roles.len(), 1);
267    /// ```
268    pub fn permissions(mut self, permissions: FieldPermissions) -> Self {
269        self.permissions = permissions;
270        self
271    }
272
273    /// 设置关联表配置
274    ///
275    /// # 参数
276    ///
277    /// - `relation`: 关联表配置
278    ///
279    /// # 返回值
280    ///
281    /// 返回 self,支持链式调用
282    ///
283    /// # 示例
284    ///
285    /// ```rust
286    /// use yang_base::table::{FieldConfig, FieldType, RelationConfig, RelationType};
287    ///
288    /// let relation = RelationConfig {
289    ///     table: "users".to_string(),
290    ///     field: "id".to_string(),
291    ///     display_fields: vec!["username".to_string(), "email".to_string()],
292    ///     relation_type: RelationType::OneToOne,
293    /// };
294    ///
295    /// let field = FieldConfig::new("user_id", FieldType::BigInt)
296    ///     .relation(relation);
297    /// assert!(field.relation.is_some());
298    /// ```
299    pub fn relation(mut self, relation: RelationConfig) -> Self {
300        self.relation = Some(relation);
301        self
302    }
303
304    /// 设置是否可筛选
305    ///
306    /// # 参数
307    ///
308    /// - `filterable`: 是否可筛选
309    ///
310    /// # 返回值
311    ///
312    /// 返回 self,支持链式调用
313    ///
314    /// # 示例
315    ///
316    /// ```rust
317    /// use yang_base::table::{FieldConfig, FieldType};
318    ///
319    /// let field = FieldConfig::new("password", FieldType::String { max_length: 255 })
320    ///     .filterable(false);
321    /// assert!(!field.filterable);
322    /// ```
323    pub fn filterable(mut self, filterable: bool) -> Self {
324        self.filterable = filterable;
325        self
326    }
327
328    /// 设置是否可排序
329    ///
330    /// # 参数
331    ///
332    /// - `sortable`: 是否可排序
333    ///
334    /// # 返回值
335    ///
336    /// 返回 self,支持链式调用
337    ///
338    /// # 示例
339    ///
340    /// ```rust
341    /// use yang_base::table::{FieldConfig, FieldType};
342    ///
343    /// let field = FieldConfig::new("description", FieldType::Text)
344    ///     .sortable(false);
345    /// assert!(!field.sortable);
346    /// ```
347    pub fn sortable(mut self, sortable: bool) -> Self {
348        self.sortable = sortable;
349        self
350    }
351
352    /// 验证字段值
353    ///
354    /// 执行完整的字段验证流程:
355    /// 1. 检查必填约束
356    /// 2. 执行字段类型验证
357    /// 3. 依次执行所有配置的验证器
358    ///
359    /// # 参数
360    ///
361    /// - `value`: 要验证的值
362    ///
363    /// # 返回值
364    ///
365    /// 如果验证通过返回 Ok(()),否则返回相应的错误
366    ///
367    /// # 错误
368    ///
369    /// - `BaseError::FieldRequired`: 字段为必填但值为 null
370    /// - `BaseError::InvalidFieldType`: 字段类型验证失败
371    /// - `BaseError::ValidationFailed`: 验证器验证失败
372    ///
373    /// # 示例
374    ///
375    /// ```rust
376    /// use yang_base::table::{FieldConfig, FieldType, Validator};
377    /// use serde_json::json;
378    ///
379    /// let field = FieldConfig::new("username", FieldType::String { max_length: 50 })
380    ///     .required(true)
381    ///     .validator(Validator::MinLength(3));
382    ///
383    /// // 验证通过
384    /// assert!(field.validate(&json!("alice")).is_ok());
385    ///
386    /// // 必填字段为 null
387    /// assert!(field.validate(&json!(null)).is_err());
388    ///
389    /// // 长度不足
390    /// assert!(field.validate(&json!("ab")).is_err());
391    /// ```
392    pub fn validate(&self, value: &serde_json::Value) -> Result<(), BaseError> {
393        // 1. 检查必填约束
394        if self.required && value.is_null() {
395            return Err(BaseError::FieldRequired(self.name.clone()));
396        }
397
398        // 如果值为 null 且字段非必填,跳过后续验证
399        if value.is_null() {
400            return Ok(());
401        }
402
403        // 2. 执行字段类型验证
404        self.field_type.validate(&self.name, value)?;
405
406        // 3. 依次执行所有配置的验证器
407        for validator in &self.validators {
408            validator.validate(&self.name, value)?;
409        }
410
411        Ok(())
412    }
413}
414
415/// 字段权限配置
416///
417/// 定义不同角色对字段的访问权限,包括读取、写入、筛选和排序权限。
418/// 如果角色列表为空,表示允许所有用户访问。
419///
420/// # 示例
421///
422/// ```rust
423/// use yang_base::table::FieldPermissions;
424/// use std::collections::HashSet;
425///
426/// // 创建一个只有管理员可以读写的字段权限
427/// let admin_only = FieldPermissions {
428///     readable_roles: HashSet::from(["admin".to_string()]),
429///     writable_roles: HashSet::from(["admin".to_string()]),
430///     filterable_roles: HashSet::from(["admin".to_string()]),
431///     sortable_roles: HashSet::from(["admin".to_string()]),
432/// };
433///
434/// // 检查权限
435/// let admin_roles = HashSet::from(["admin".to_string()]);
436/// let user_roles = HashSet::from(["user".to_string()]);
437///
438/// assert!(admin_only.can_read(&admin_roles));
439/// assert!(!admin_only.can_read(&user_roles));
440///
441/// // 创建一个所有人都可以访问的字段权限
442/// let public = FieldPermissions::default();
443/// assert!(public.can_read(&user_roles));
444/// assert!(public.can_write(&user_roles));
445/// ```
446#[derive(Debug, Clone, Default, Serialize, Deserialize)]
447pub struct FieldPermissions {
448    /// 可读角色集合
449    ///
450    /// 如果集合为空,表示所有用户都可以读取该字段
451    pub readable_roles: HashSet<String>,
452
453    /// 可写角色集合
454    ///
455    /// 如果集合为空,表示所有用户都可以写入该字段
456    pub writable_roles: HashSet<String>,
457
458    /// 可筛选角色集合
459    ///
460    /// 如果集合为空,表示所有用户都可以使用该字段进行筛选
461    pub filterable_roles: HashSet<String>,
462
463    /// 可排序角色集合
464    ///
465    /// 如果集合为空,表示所有用户都可以使用该字段进行排序
466    pub sortable_roles: HashSet<String>,
467}
468
469impl FieldPermissions {
470    /// 检查用户是否有读取权限
471    ///
472    /// # 参数
473    ///
474    /// - `user_roles`: 用户的角色集合(HashSet,支持 O(1) 查找)
475    ///
476    /// # 返回值
477    ///
478    /// 如果用户有读取权限返回 true,否则返回 false
479    ///
480    /// # 示例
481    ///
482    /// ```rust
483    /// use yang_base::table::FieldPermissions;
484    /// use std::collections::HashSet;
485    ///
486    /// let permissions = FieldPermissions {
487    ///     readable_roles: HashSet::from(["admin".to_string(), "user".to_string()]),
488    ///     ..Default::default()
489    /// };
490    ///
491    /// let admin_roles = HashSet::from(["admin".to_string()]);
492    /// let user_roles = HashSet::from(["user".to_string()]);
493    ///
494    /// assert!(permissions.can_read(&admin_roles));
495    /// assert!(permissions.can_read(&user_roles));
496    /// assert!(!permissions.can_read(&HashSet::from(["guest".to_string()])));
497    /// ```
498    pub fn can_read(&self, user_roles: &HashSet<String>) -> bool {
499        self.readable_roles.is_empty() || user_roles.iter().any(|r| self.readable_roles.contains(r))
500    }
501
502    /// 检查用户是否有写入权限
503    ///
504    /// # 参数
505    ///
506    /// - `user_roles`: 用户的角色集合(HashSet,支持 O(1) 查找)
507    ///
508    /// # 返回值
509    ///
510    /// 如果用户有写入权限返回 true,否则返回 false
511    ///
512    /// # 示例
513    ///
514    /// ```rust
515    /// use yang_base::table::FieldPermissions;
516    /// use std::collections::HashSet;
517    ///
518    /// let permissions = FieldPermissions {
519    ///     writable_roles: HashSet::from(["admin".to_string()]),
520    ///     ..Default::default()
521    /// };
522    ///
523    /// let admin_roles = HashSet::from(["admin".to_string()]);
524    ///
525    /// assert!(permissions.can_write(&admin_roles));
526    /// ```
527    pub fn can_write(&self, user_roles: &HashSet<String>) -> bool {
528        self.writable_roles.is_empty() || user_roles.iter().any(|r| self.writable_roles.contains(r))
529    }
530
531    /// 检查用户是否有筛选权限
532    ///
533    /// # 参数
534    ///
535    /// - `user_roles`: 用户的角色列表
536    ///
537    /// # 返回值
538    ///
539    /// 如果用户有筛选权限返回 true,否则返回 false
540    ///
541    /// # 示例
542    ///
543    /// ```rust
544    /// use yang_base::table::FieldPermissions;
545    /// use std::collections::HashSet;
546    ///
547    /// let permissions = FieldPermissions {
548    ///     filterable_roles: HashSet::from(["admin".to_string()]),
549    ///     ..Default::default()
550    /// };
551    ///
552    /// let admin_roles = HashSet::from(["admin".to_string()]);
553    /// assert!(permissions.can_filter(&admin_roles));
554    /// ```
555    pub fn can_filter(&self, user_roles: &HashSet<String>) -> bool {
556        self.filterable_roles.is_empty()
557            || user_roles.iter().any(|r| self.filterable_roles.contains(r))
558    }
559
560    /// 检查用户是否有排序权限
561    ///
562    /// # 参数
563    ///
564    /// - `user_roles`: 用户的角色集合(HashSet,支持 O(1) 查找)
565    ///
566    /// # 返回值
567    ///
568    /// 如果用户有排序权限返回 true,否则返回 false
569    ///
570    /// # 示例
571    ///
572    /// ```rust
573    /// use yang_base::table::FieldPermissions;
574    /// use std::collections::HashSet;
575    ///
576    /// let permissions = FieldPermissions {
577    ///     sortable_roles: HashSet::from(["admin".to_string()]),
578    ///     ..Default::default()
579    /// };
580    ///
581    /// let admin_roles = HashSet::from(["admin".to_string()]);
582    /// assert!(permissions.can_sort(&admin_roles));
583    /// ```
584    pub fn can_sort(&self, user_roles: &HashSet<String>) -> bool {
585        self.sortable_roles.is_empty() || user_roles.iter().any(|r| self.sortable_roles.contains(r))
586    }
587}
588
589/// 关联表配置
590///
591/// 定义字段与其他表的关联关系,用于外键字段。
592///
593/// # 示例
594///
595/// ```rust
596/// use yang_base::table::{RelationConfig, RelationType};
597///
598/// // 定义一个一对一关联
599/// let relation = RelationConfig {
600///     table: "users".to_string(),
601///     field: "id".to_string(),
602///     display_fields: vec!["username".to_string(), "email".to_string()],
603///     relation_type: RelationType::OneToOne,
604/// };
605/// ```
606#[derive(Debug, Clone, Serialize, Deserialize)]
607pub struct RelationConfig {
608    /// 关联的目标表名
609    pub table: String,
610
611    /// 关联的目标字段名
612    pub field: String,
613
614    /// 显示字段列表
615    ///
616    /// 当查询关联数据时,需要返回的字段列表
617    pub display_fields: Vec<String>,
618
619    /// 关联类型
620    pub relation_type: RelationType,
621}
622
623/// 关联类型
624///
625/// 定义表之间的关联关系类型
626#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
627pub enum RelationType {
628    /// 一对一关联
629    ///
630    /// 一条记录对应另一个表的一条记录
631    OneToOne,
632
633    /// 一对多关联
634    ///
635    /// 一条记录对应另一个表的多条记录
636    OneToMany,
637
638    /// 多对多关联
639    ///
640    /// 多条记录对应另一个表的多条记录,通常需要中间表
641    ManyToMany,
642}