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}