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}