Skip to main content

yang_base/table/table_query/
mod.rs

1//! 表查询构建器
2//!
3//! 提供由 [`super::TableDefinition`] 约束的查询构建器,支持字段权限验证和 CRUD。
4//!
5//! # 主要组件
6//!
7//! - `TableQuery`:查询构建器,支持链式调用
8//!
9//! # 示例
10//!
11//! ```rust,ignore
12//! use yang_base::table::{Field, SortOrder, Table};
13//! use serde_json::json;
14//! use std::sync::Arc;
15//!
16//! let table = Table::new("users")
17//!     .fields(vec![
18//!         Field::id("id"),
19//!         Field::string("name", 50),
20//!         Field::string("email", 100),
21//!     ])
22//!     .build()?;
23//!
24//! let query = table.bind(Arc::new(pool)).query(["user"]);
25//!
26//! // 链式调用构建查询
27//! let result = query
28//!     .select_fields(&["id", "name", "email"])?
29//!     .where_eq("status", json!("active"))?
30//!     .order_by("created_at", SortOrder::Desc)?
31//!     .page(1, 20)?
32//!     .all()
33//!     .await?;
34//! ```
35
36mod build;
37mod filters;
38#[cfg(any(feature = "mysql", feature = "postgres"))]
39mod plan;
40#[cfg(feature = "postgres")]
41mod plan_pg;
42#[cfg(any(feature = "mysql", feature = "postgres"))]
43mod read;
44#[cfg(all(test, feature = "mysql"))]
45mod sql_param;
46#[cfg(all(test, feature = "mysql"))]
47mod sql_render;
48mod validation;
49#[cfg(any(feature = "mysql", feature = "postgres"))]
50mod write;
51
52// 保持 crate 内既有路径 `crate::table::table_query::SqlParam` 可用于测试
53#[cfg(all(test, feature = "mysql"))]
54pub(crate) use sql_param::SqlParam;
55
56use crate::table::{QueryParams, TableConfig};
57use serde_json::Value;
58use std::collections::HashSet;
59use std::sync::Arc;
60
61/// 受保护表查询允许的最大单页大小。
62///
63/// 该上限必须在 `TableQuery` 底层执行,而不能只放在上层 action。自定义 action 或库调用方
64/// 可直接调用 `ctx.table_query()?.page(...)`,底层没有上限会绕过内置 `SelectAction` 的保护,
65/// 导致超大查询拖垮数据库或应用内存。
66pub const MAX_TABLE_QUERY_PAGE_SIZE: usize = super::query_params::MAX_QUERY_PAGE_SIZE;
67
68/// 表查询构建器
69///
70/// 基于不可变表定义创建受保护的查询构建器,支持:
71/// - 字段选择和权限验证
72/// - WHERE 条件构建
73/// - 排序规则
74/// - 分页查询
75///
76/// # 字段
77///
78/// - 内部表契约:由 [`super::TableDefinition`] 提供字段定义和权限配置
79/// - `user_roles`:用户角色列表,用于权限检查
80/// - `query_params`:查询参数,包含字段选择、WHERE 条件、排序规则和分页参数
81/// - `pool`:运行时数据库连接池句柄(MySQL / PostgreSQL 按后端分派)
82///
83/// # 示例
84///
85/// ```rust,ignore
86/// use yang_base::table::{Field, SortOrder, Table};
87/// use std::sync::Arc;
88/// use serde_json::json;
89///
90/// let table = Table::new("users")
91///     .fields(vec![Field::id("id"), Field::string("name", 50)])
92///     .build()?;
93/// let query = table.bind(Arc::new(pool)).query(["admin"]);
94///
95/// // 选择字段
96/// let query = query.select_fields(&["id", "name"])?;
97///
98/// // 添加 WHERE 条件
99/// let query = query.where_eq("status", json!(1))?;
100///
101/// // 添加排序
102/// let query = query.order_by("created_at", SortOrder::Desc)?;
103///
104/// // 设置分页
105/// let query = query.page(1, 20)?;
106/// ```
107#[derive(Debug, Clone)]
108pub struct TableQuery {
109    /// 表配置引用
110    ///
111    /// 包含表结构、字段定义和权限配置
112    table_config: Arc<TableConfig>,
113
114    /// 用户角色列表
115    ///
116    /// 使用 Arc<[String]> 共享所有权,避免不必要的克隆
117    user_roles: Arc<[String]>,
118    /// 用户角色 HashSet 缓存(O(1) 查找,避免每次 can_read/can_write 时转换)
119    user_roles_set: HashSet<String>,
120
121    /// 查询参数
122    ///
123    /// 包含字段选择、WHERE 条件、排序规则和分页参数
124    query_params: QueryParams,
125
126    /// 每个排序字段的 NULL 位置:`true` = NULLS FIRST,`false` = NULLS LAST。
127    ///
128    /// 与 `query_params.order_by` 按字段名关联;PostgreSQL 渲染原生
129    /// `NULLS FIRST/LAST`,MySQL 用 `field IS NULL` 表达式模拟(见
130    /// [`TableQuery::order_nulls`])。
131    #[cfg_attr(not(any(feature = "mysql", feature = "postgres")), allow(dead_code))]
132    nulls_orders: std::collections::HashMap<String, bool>,
133
134    /// `where_any` 登记的数组参数条件(仅 PostgreSQL 使用 `= ANY($n)`)。
135    #[cfg_attr(not(feature = "postgres"), allow(dead_code))]
136    any_conditions: Vec<(String, Vec<Value>)>,
137
138    /// 是否在读取路径包含软删除记录
139    ///
140    /// 默认 `false`:配置了 `soft_delete_field` 的表,软删行不出现在
141    /// select/count/paginate 结果中。置为 `true`(经 [`TableQuery::with_trashed`])
142    /// 时读取全量(含已软删行)。
143    include_trashed: bool,
144
145    /// 启动期定义并在请求期注入的租户范围;存在时所有读写均必须带该条件。
146    tenant_scope: Option<(String, Value)>,
147
148    /// 数据库连接池句柄(按运行时后端分派)
149    ///
150    /// 由 [`TableHandle`](crate::table::TableHandle) 或
151    /// [`ActionContext`](crate::action::ActionContext) 注入;未注入时执行方法返回
152    /// [`BaseError::DatabaseNotInitialized`]。
153    #[cfg(any(feature = "mysql", feature = "postgres"))]
154    pool: Option<crate::database::AnyPool>,
155
156    /// 连接池所属逻辑数据源;事务同源校验使用。
157    #[cfg_attr(not(any(feature = "mysql", feature = "postgres")), allow(dead_code))]
158    pool_source: crate::datasource::DatasourceId,
159
160    /// 是否要求事务必须显式携带数据源身份(多源应用启用)。
161    #[cfg_attr(not(any(feature = "mysql", feature = "postgres")), allow(dead_code))]
162    require_sourced_tx: bool,
163
164    /// 慢查询阈值(可观测性 C4)
165    ///
166    /// `Some(d)` 时,单次执行耗时超过 `d` 会 `tracing::warn!`;`None`(默认)
167    /// 整个计时分支短路,热路径仅一次 `Instant::now()`,无分配。
168    /// 由 [`ActionContext::table_query`](crate::action::ActionContext) 从
169    /// [`ObservabilityConfig`](crate::observability::ObservabilityConfig) 注入。
170    slow_threshold: Option<std::time::Duration>,
171
172    /// 本次派发的运行期标识(用于慢查询日志串联),由 ActionContext 注入。
173    request_id: Option<crate::action::RequestId>,
174
175    /// 共享的有界正则缓存(Email/Phone/Regex 验证器复用),由 ActionContext 从
176    /// [`crate::tools::Tools`] 注入;未注入时退化为默认容量缓存。
177    regex_cache: crate::table::RegexCache,
178}