Skip to main content

yang_base/table/
query_params.rs

1//! 查询参数结构
2//!
3//! 提供统一的查询参数定义,包括 WHERE 条件、排序规则和分页参数。
4//!
5//! # 主要组件
6//!
7//! - `WhereCondition`:WHERE 条件枚举
8//! - `QueryParams`:查询参数结构体
9//! - `PaginatedResult`:分页结果结构体
10//!
11//! # 示例
12//!
13//! ```rust
14//! use yang_base::table::{WhereCondition, QueryParams, SortOrder};
15//! use serde_json::json;
16//!
17//! // 创建查询参数
18//! let mut params = QueryParams::new();
19//!
20//! // 添加字段选择
21//! params.fields = Some(vec!["id".to_string(), "name".to_string()]);
22//!
23//! // 添加 WHERE 条件
24//! params.where_conditions.push(WhereCondition::Eq {
25//!     field: "status".to_string(),
26//!     value: json!("active"),
27//! });
28//!
29//! params.where_conditions.push(WhereCondition::In {
30//!     field: "role".to_string(),
31//!     values: vec![json!("admin"), json!("user")],
32//! });
33//!
34//! // 添加排序规则
35//! params.order_by.push(("created_at".to_string(), SortOrder::Desc));
36//!
37//! // 设置分页参数
38//! params.page = Some(1);
39//! params.page_size = Some(20);
40//! ```
41
42use serde::{Deserialize, Serialize};
43use serde_json::Value;
44
45/// 默认每页条数。
46pub const DEFAULT_QUERY_PAGE_SIZE: usize = 10;
47
48/// 查询请求模型允许的最大每页条数。
49pub const MAX_QUERY_PAGE_SIZE: usize = 100;
50
51/// WHERE 条件枚举
52///
53/// 定义各种查询条件类型,支持常见的 SQL WHERE 子句操作。
54///
55/// # 变体
56///
57/// - `Eq`:等于条件 (field = value)
58/// - `In`:包含于列表条件 (field IN (values))
59/// - `Like`:模糊匹配条件 (field LIKE pattern)
60/// - `Gt`:大于条件 (field > value)
61/// - `Gte`:大于等于条件 (field >= value)
62/// - `Lt`:小于条件 (field < value)
63/// - `Lte`:小于等于条件 (field <= value)
64/// - `IsNull`:空值判断 (field IS NULL)
65/// - `IsNotNull`:非空值判断 (field IS NOT NULL)
66///
67/// # 示例
68///
69/// ```rust
70/// use yang_base::table::WhereCondition;
71/// use serde_json::json;
72///
73/// // 等于条件
74/// let eq_condition = WhereCondition::Eq {
75///     field: "status".to_string(),
76///     value: json!("active"),
77/// };
78///
79/// // 包含条件
80/// let in_condition = WhereCondition::In {
81///     field: "role".to_string(),
82///     values: vec![json!("admin"), json!("user")],
83/// };
84///
85/// // 模糊匹配
86/// let like_condition = WhereCondition::Like {
87///     field: "name".to_string(),
88///     pattern: "%alice%".to_string(),
89/// };
90///
91/// // 大于条件
92/// let gt_condition = WhereCondition::Gt {
93///     field: "age".to_string(),
94///     value: json!(18),
95/// };
96///
97/// // 空值判断
98/// let is_null_condition = WhereCondition::IsNull {
99///     field: "deleted_at".to_string(),
100/// };
101/// ```
102#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, schemars::JsonSchema)]
103#[serde(tag = "type", rename_all = "snake_case")]
104#[non_exhaustive]
105pub enum WhereCondition {
106    /// 等于条件 (field = value)
107    ///
108    /// # 字段
109    ///
110    /// - `field`:字段名
111    /// - `value`:比较值
112    Eq {
113        /// 字段名
114        field: String,
115        /// 比较值
116        value: Value,
117    },
118
119    /// 包含于列表条件 (field IN (values))
120    ///
121    /// # 字段
122    ///
123    /// - `field`:字段名
124    /// - `values`:值列表
125    In {
126        /// 字段名
127        field: String,
128        /// 值列表
129        values: Vec<Value>,
130    },
131
132    /// 模糊匹配条件 (field LIKE pattern)
133    ///
134    /// # 字段
135    ///
136    /// - `field`:字段名
137    /// - `pattern`:匹配模式,支持 % 和 _ 通配符
138    Like {
139        /// 字段名
140        field: String,
141        /// 匹配模式
142        pattern: String,
143    },
144
145    /// 大于条件 (field > value)
146    ///
147    /// # 字段
148    ///
149    /// - `field`:字段名
150    /// - `value`:比较值
151    Gt {
152        /// 字段名
153        field: String,
154        /// 比较值
155        value: Value,
156    },
157
158    /// 大于等于条件 (field >= value)
159    ///
160    /// # 字段
161    ///
162    /// - `field`:字段名
163    /// - `value`:比较值
164    Gte {
165        /// 字段名
166        field: String,
167        /// 比较值
168        value: Value,
169    },
170
171    /// 小于条件 (field < value)
172    ///
173    /// # 字段
174    ///
175    /// - `field`:字段名
176    /// - `value`:比较值
177    Lt {
178        /// 字段名
179        field: String,
180        /// 比较值
181        value: Value,
182    },
183
184    /// 小于等于条件 (field <= value)
185    ///
186    /// # 字段
187    ///
188    /// - `field`:字段名
189    /// - `value`:比较值
190    Lte {
191        /// 字段名
192        field: String,
193        /// 比较值
194        value: Value,
195    },
196
197    /// 空值判断 (field IS NULL)
198    ///
199    /// # 字段
200    ///
201    /// - `field`:字段名
202    IsNull {
203        /// 字段名
204        field: String,
205    },
206
207    /// 非空值判断 (field IS NOT NULL)
208    ///
209    /// # 字段
210    ///
211    /// - `field`:字段名
212    IsNotNull {
213        /// 字段名
214        field: String,
215    },
216
217    /// 不等于条件 (field <> value)
218    ///
219    /// # 字段
220    ///
221    /// - `field`:字段名
222    /// - `value`:比较值
223    Ne {
224        /// 字段名
225        field: String,
226        /// 比较值
227        value: Value,
228    },
229
230    /// 区间条件 (field BETWEEN lo AND hi)
231    ///
232    /// # 字段
233    ///
234    /// - `field`:字段名
235    /// - `lo`:区间下界
236    /// - `hi`:区间上界
237    Between {
238        /// 字段名
239        field: String,
240        /// 区间下界
241        lo: Value,
242        /// 区间上界
243        hi: Value,
244    },
245
246    /// 不在列表条件 (field NOT IN (values))
247    ///
248    /// # 字段
249    ///
250    /// - `field`:字段名
251    /// - `values`:值列表
252    NotIn {
253        /// 字段名
254        field: String,
255        /// 值列表
256        values: Vec<Value>,
257    },
258
259    /// 逻辑与组(嵌套子条件全部成立),SQL 渲染为 `(c1 AND c2 AND ...)`
260    ///
261    /// 空组等价于恒真(`1=1`),与顶层「无条件」语义一致。
262    ///
263    /// # 字段
264    ///
265    /// - `conditions`:子条件列表,递归可含 `And`/`Or` 组
266    And {
267        /// 子条件列表
268        conditions: Vec<WhereCondition>,
269    },
270
271    /// 逻辑或组(嵌套子条件任一成立),SQL 渲染为 `(c1 OR c2 OR ...)`
272    ///
273    /// 空组等价于恒假(`1=0`),避免拼出非法的空括号。
274    ///
275    /// # 字段
276    ///
277    /// - `conditions`:子条件列表,递归可含 `And`/`Or` 组
278    Or {
279        /// 子条件列表
280        conditions: Vec<WhereCondition>,
281    },
282}
283
284impl WhereCondition {
285    /// 获取条件涉及的字段名
286    ///
287    /// 叶子条件返回 `Some(字段名)`;逻辑组(`And`/`Or`)无单一字段,返回 `None`。
288    ///
289    /// # 返回值
290    ///
291    /// 叶子返回 `Some(&str)`,组节点返回 `None`
292    ///
293    /// # 示例
294    ///
295    /// ```rust
296    /// use yang_base::table::WhereCondition;
297    /// use serde_json::json;
298    ///
299    /// let condition = WhereCondition::Eq {
300    ///     field: "status".to_string(),
301    ///     value: json!("active"),
302    /// };
303    ///
304    /// assert_eq!(condition.field(), Some("status"));
305    /// ```
306    pub fn field(&self) -> Option<&str> {
307        match self {
308            WhereCondition::Eq { field, .. }
309            | WhereCondition::In { field, .. }
310            | WhereCondition::Like { field, .. }
311            | WhereCondition::Gt { field, .. }
312            | WhereCondition::Gte { field, .. }
313            | WhereCondition::Lt { field, .. }
314            | WhereCondition::Lte { field, .. }
315            | WhereCondition::IsNull { field }
316            | WhereCondition::IsNotNull { field }
317            | WhereCondition::Ne { field, .. }
318            | WhereCondition::Between { field, .. }
319            | WhereCondition::NotIn { field, .. } => Some(field),
320            // 逻辑组无单一字段
321            WhereCondition::And { .. } | WhereCondition::Or { .. } => None,
322        }
323    }
324}
325
326/// 查询参数结构体
327///
328/// 包含完整的查询参数,包括字段选择、WHERE 条件、排序规则和分页参数。
329///
330/// # 字段
331///
332/// - `fields`:字段选择列表,None 表示选择所有字段
333/// - `where_conditions`:WHERE 条件列表
334/// - `order_by`:排序规则列表,元组格式为 (字段名, 排序方向)
335/// - `page`:当前页码,从 1 开始
336/// - `page_size`:每页大小
337///
338/// # 示例
339///
340/// ```rust
341/// use yang_base::table::{QueryParams, WhereCondition, SortOrder};
342/// use serde_json::json;
343///
344/// let mut params = QueryParams::new();
345///
346/// // 选择特定字段
347/// params.fields = Some(vec!["id".to_string(), "name".to_string(), "email".to_string()]);
348///
349/// // 添加 WHERE 条件
350/// params.where_conditions.push(WhereCondition::Eq {
351///     field: "status".to_string(),
352///     value: json!("active"),
353/// });
354///
355/// params.where_conditions.push(WhereCondition::Gt {
356///     field: "age".to_string(),
357///     value: json!(18),
358/// });
359///
360/// // 添加排序规则
361/// params.order_by.push(("created_at".to_string(), SortOrder::Desc));
362/// params.order_by.push(("name".to_string(), SortOrder::Asc));
363///
364/// // 设置分页参数
365/// params.page = Some(1);
366/// params.page_size = Some(20);
367/// ```
368#[derive(Debug, Clone, Serialize, Deserialize, Default)]
369pub struct QueryParams {
370    /// 字段选择列表
371    ///
372    /// - `None`:选择所有字段
373    /// - `Some(vec)`:选择指定字段
374    #[serde(skip_serializing_if = "Option::is_none")]
375    pub fields: Option<Vec<String>>,
376
377    /// WHERE 条件列表
378    ///
379    /// 多个条件之间使用 AND 连接
380    #[serde(default)]
381    pub where_conditions: Vec<WhereCondition>,
382
383    /// 排序规则列表
384    ///
385    /// 元组格式为 (字段名, 排序方向)
386    #[serde(default)]
387    pub order_by: Vec<(String, crate::table::SortOrder)>,
388
389    /// 当前页码
390    ///
391    /// 从 1 开始,None 表示不分页
392    #[serde(skip_serializing_if = "Option::is_none")]
393    pub page: Option<usize>,
394
395    /// 每页大小
396    ///
397    /// None 表示使用默认值或不分页
398    #[serde(skip_serializing_if = "Option::is_none")]
399    pub page_size: Option<usize>,
400}
401
402impl QueryParams {
403    /// 创建新的查询参数
404    ///
405    /// # 返回值
406    ///
407    /// 返回空的查询参数实例
408    ///
409    /// # 示例
410    ///
411    /// ```rust
412    /// use yang_base::table::QueryParams;
413    ///
414    /// let params = QueryParams::new();
415    /// assert!(params.fields.is_none());
416    /// assert!(params.where_conditions.is_empty());
417    /// assert!(params.order_by.is_empty());
418    /// assert!(params.page.is_none());
419    /// assert!(params.page_size.is_none());
420    /// ```
421    pub fn new() -> Self {
422        Self::default()
423    }
424
425    /// 设置字段选择列表
426    ///
427    /// # 参数
428    ///
429    /// - `fields`:字段名列表
430    ///
431    /// # 返回值
432    ///
433    /// 返回 self 以支持链式调用
434    ///
435    /// # 示例
436    ///
437    /// ```rust
438    /// use yang_base::table::QueryParams;
439    ///
440    /// let params = QueryParams::new()
441    ///     .with_fields(vec!["id".to_string(), "name".to_string()]);
442    ///
443    /// assert_eq!(params.fields, Some(vec!["id".to_string(), "name".to_string()]));
444    /// ```
445    pub fn with_fields(mut self, fields: Vec<String>) -> Self {
446        self.fields = Some(fields);
447        self
448    }
449
450    /// 添加 WHERE 条件
451    ///
452    /// # 参数
453    ///
454    /// - `condition`:WHERE 条件
455    ///
456    /// # 返回值
457    ///
458    /// 返回 self 以支持链式调用
459    ///
460    /// # 示例
461    ///
462    /// ```rust
463    /// use yang_base::table::{QueryParams, WhereCondition};
464    /// use serde_json::json;
465    ///
466    /// let params = QueryParams::new()
467    ///     .with_condition(WhereCondition::Eq {
468    ///         field: "status".to_string(),
469    ///         value: json!("active"),
470    ///     });
471    ///
472    /// assert_eq!(params.where_conditions.len(), 1);
473    /// ```
474    pub fn with_condition(mut self, condition: WhereCondition) -> Self {
475        self.where_conditions.push(condition);
476        self
477    }
478
479    /// 添加排序规则
480    ///
481    /// # 参数
482    ///
483    /// - `field`:字段名
484    /// - `order`:排序方向
485    ///
486    /// # 返回值
487    ///
488    /// 返回 self 以支持链式调用
489    ///
490    /// # 示例
491    ///
492    /// ```rust
493    /// use yang_base::table::{QueryParams, SortOrder};
494    ///
495    /// let params = QueryParams::new()
496    ///     .with_order_by("created_at".to_string(), SortOrder::Desc);
497    ///
498    /// assert_eq!(params.order_by.len(), 1);
499    /// ```
500    pub fn with_order_by(mut self, field: String, order: crate::table::SortOrder) -> Self {
501        self.order_by.push((field, order));
502        self
503    }
504
505    /// 设置分页参数
506    ///
507    /// # 参数
508    ///
509    /// - `page`:当前页码,从 1 开始
510    /// - `page_size`:每页大小
511    ///
512    /// # 返回值
513    ///
514    /// 返回 self 以支持链式调用
515    ///
516    /// # 示例
517    ///
518    /// ```rust
519    /// use yang_base::table::QueryParams;
520    ///
521    /// let params = QueryParams::new()
522    ///     .with_pagination(1, 20);
523    ///
524    /// assert_eq!(params.page, Some(1));
525    /// assert_eq!(params.page_size, Some(20));
526    /// ```
527    pub fn with_pagination(mut self, page: usize, page_size: usize) -> Self {
528        self.page = Some(page);
529        self.page_size = Some(page_size);
530        self
531    }
532
533    /// 归一化分页参数
534    ///
535    /// 将 `page` 中小于 1 的值(含 0)归一为 1,避免直接构造 `QueryParams`
536    /// 时 `page == 0` 导致 LIMIT/OFFSET 计算下溢。`page_size` 保持原值。
537    ///
538    /// # 示例
539    ///
540    /// ```rust
541    /// use yang_base::table::QueryParams;
542    ///
543    /// let mut params = QueryParams::new().with_pagination(0, 20);
544    /// params.normalize();
545    /// assert_eq!(params.page, Some(1));
546    /// ```
547    pub fn normalize(&mut self) {
548        if let Some(page) = self.page {
549            if page == 0 {
550                self.page = Some(1);
551            }
552        }
553        if let Some(page_size) = self.page_size {
554            if page_size == 0 {
555                self.page_size = Some(DEFAULT_QUERY_PAGE_SIZE);
556            } else if page_size > MAX_QUERY_PAGE_SIZE {
557                self.page_size = Some(MAX_QUERY_PAGE_SIZE);
558            }
559        }
560    }
561}
562
563/// 表查询的唯一执行计划模型。
564///
565/// 保留 `QueryParams` 名称作为传输语义;业务层与 [`crate::table::Tables`]
566/// 使用本别名表达筛选、排序和分页已经汇入同一条查询执行链。
567pub type TableQueryPlan = QueryParams;
568
569/// 分页结果结构体
570///
571/// 包含分页查询的完整结果,包括数据列表和分页元信息。
572///
573/// # 类型参数
574///
575/// - `T`:数据项类型,必须实现 Serialize 和 Deserialize
576///
577/// # 字段
578///
579/// - `data`:数据列表
580/// - `total`:总记录数
581/// - `page`:当前页码,从 1 开始
582/// - `page_size`:每页大小
583/// - `total_pages`:总页数
584///
585/// # 示例
586///
587/// ```rust
588/// use yang_base::table::PaginatedResult;
589/// use serde::{Deserialize, Serialize};
590///
591/// #[derive(Debug, Serialize, Deserialize)]
592/// struct User {
593///     id: i64,
594///     name: String,
595/// }
596///
597/// let users = vec![
598///     User { id: 1, name: "Alice".to_string() },
599///     User { id: 2, name: "Bob".to_string() },
600/// ];
601///
602/// let result = PaginatedResult::new(users, 100, 1, 20);
603///
604/// assert_eq!(result.data.len(), 2);
605/// assert_eq!(result.total, 100);
606/// assert_eq!(result.page, 1);
607/// assert_eq!(result.page_size, 20);
608/// assert_eq!(result.total_pages, 5);
609/// ```
610#[derive(Debug, Clone, Serialize, Deserialize)]
611pub struct PaginatedResult<T>
612where
613    T: Serialize,
614{
615    /// 数据列表
616    pub data: Vec<T>,
617
618    /// 总记录数
619    pub total: usize,
620
621    /// 当前页码
622    ///
623    /// 从 1 开始
624    pub page: usize,
625
626    /// 每页大小
627    pub page_size: usize,
628
629    /// 总页数
630    pub total_pages: usize,
631}
632
633impl<T> PaginatedResult<T>
634where
635    T: Serialize,
636{
637    /// 创建新的分页结果
638    ///
639    /// # 参数
640    ///
641    /// - `data`:数据列表
642    /// - `total`:总记录数
643    /// - `page`:当前页码,从 1 开始
644    /// - `page_size`:每页大小
645    ///
646    /// # 返回值
647    ///
648    /// 返回分页结果实例,自动计算总页数
649    ///
650    /// # 示例
651    ///
652    /// ```rust
653    /// use yang_base::table::PaginatedResult;
654    /// use serde::{Deserialize, Serialize};
655    ///
656    /// #[derive(Debug, Serialize, Deserialize)]
657    /// struct User {
658    ///     id: i64,
659    ///     name: String,
660    /// }
661    ///
662    /// let users = vec![
663    ///     User { id: 1, name: "Alice".to_string() },
664    ///     User { id: 2, name: "Bob".to_string() },
665    /// ];
666    ///
667    /// let result = PaginatedResult::new(users, 100, 1, 20);
668    ///
669    /// assert_eq!(result.total_pages, 5);
670    /// ```
671    pub fn new(data: Vec<T>, total: usize, page: usize, page_size: usize) -> Self {
672        let total_pages = if page_size > 0 {
673            total.div_ceil(page_size)
674        } else {
675            0
676        };
677
678        Self {
679            data,
680            total,
681            page,
682            page_size,
683            total_pages,
684        }
685    }
686
687    /// 创建空的分页结果
688    ///
689    /// # 参数
690    ///
691    /// - `page`:当前页码
692    /// - `page_size`:每页大小
693    ///
694    /// # 返回值
695    ///
696    /// 返回空的分页结果实例
697    ///
698    /// # 示例
699    ///
700    /// ```rust
701    /// use yang_base::table::PaginatedResult;
702    /// use serde::{Deserialize, Serialize};
703    ///
704    /// #[derive(Debug, Serialize, Deserialize)]
705    /// struct User {
706    ///     id: i64,
707    ///     name: String,
708    /// }
709    ///
710    /// let result: PaginatedResult<User> = PaginatedResult::empty(1, 20);
711    ///
712    /// assert_eq!(result.data.len(), 0);
713    /// assert_eq!(result.total, 0);
714    /// assert_eq!(result.total_pages, 0);
715    /// ```
716    pub fn empty(page: usize, page_size: usize) -> Self {
717        Self {
718            data: Vec::new(),
719            total: 0,
720            page,
721            page_size,
722            total_pages: 0,
723        }
724    }
725
726    /// 判断是否有下一页
727    ///
728    /// # 返回值
729    ///
730    /// 如果有下一页返回 true,否则返回 false
731    ///
732    /// # 示例
733    ///
734    /// ```rust
735    /// use yang_base::table::PaginatedResult;
736    /// use serde::{Deserialize, Serialize};
737    ///
738    /// #[derive(Debug, Serialize, Deserialize)]
739    /// struct User {
740    ///     id: i64,
741    ///     name: String,
742    /// }
743    ///
744    /// let result: PaginatedResult<User> = PaginatedResult::new(vec![], 100, 1, 20);
745    /// assert!(result.has_next());
746    ///
747    /// let result: PaginatedResult<User> = PaginatedResult::new(vec![], 100, 5, 20);
748    /// assert!(!result.has_next());
749    /// ```
750    pub fn has_next(&self) -> bool {
751        self.page < self.total_pages
752    }
753
754    /// 判断是否有上一页
755    ///
756    /// # 返回值
757    ///
758    /// 如果有上一页返回 true,否则返回 false
759    ///
760    /// # 示例
761    ///
762    /// ```rust
763    /// use yang_base::table::PaginatedResult;
764    /// use serde::{Deserialize, Serialize};
765    ///
766    /// #[derive(Debug, Serialize, Deserialize)]
767    /// struct User {
768    ///     id: i64,
769    ///     name: String,
770    /// }
771    ///
772    /// let result: PaginatedResult<User> = PaginatedResult::new(vec![], 100, 1, 20);
773    /// assert!(!result.has_prev());
774    ///
775    /// let result: PaginatedResult<User> = PaginatedResult::new(vec![], 100, 2, 20);
776    /// assert!(result.has_prev());
777    /// ```
778    pub fn has_prev(&self) -> bool {
779        self.page > 1
780    }
781}