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(feature = "mysql")]
39mod plan;
40#[cfg(feature = "mysql")]
41mod read;
42#[cfg(all(test, feature = "mysql"))]
43mod sql_param;
44#[cfg(all(test, feature = "mysql"))]
45mod sql_render;
46mod validation;
47#[cfg(feature = "mysql")]
48mod write;
49
50// 保持 crate 内既有路径 `crate::table::table_query::SqlParam` 可用于测试
51#[cfg(all(test, feature = "mysql"))]
52pub(crate) use sql_param::SqlParam;
53
54use crate::table::{QueryParams, TableConfig};
55use serde_json::Value;
56use std::collections::HashSet;
57use std::sync::Arc;
58
59/// 受保护表查询允许的最大单页大小。
60///
61/// 该上限必须在 `TableQuery` 底层执行,而不能只放在上层 action。自定义 action 或库调用方
62/// 可直接调用 `ctx.table_query()?.page(...)`,底层没有上限会绕过内置 `SelectAction` 的保护,
63/// 导致超大查询拖垮数据库或应用内存。
64pub const MAX_TABLE_QUERY_PAGE_SIZE: usize = super::query_params::MAX_QUERY_PAGE_SIZE;
65
66/// 表查询构建器
67///
68/// 基于不可变表定义创建受保护的查询构建器,支持:
69/// - 字段选择和权限验证
70/// - WHERE 条件构建
71/// - 排序规则
72/// - 分页查询
73///
74/// # 字段
75///
76/// - 内部表契约:由 [`super::TableDefinition`] 提供字段定义和权限配置
77/// - `user_roles`:用户角色列表,用于权限检查
78/// - `query_params`:查询参数,包含字段选择、WHERE 条件、排序规则和分页参数
79/// - `pool`:数据库连接池引用(预留,暂未使用)
80///
81/// # 示例
82///
83/// ```rust,ignore
84/// use yang_base::table::{Field, SortOrder, Table};
85/// use std::sync::Arc;
86/// use serde_json::json;
87///
88/// let table = Table::new("users")
89///     .fields(vec![Field::id("id"), Field::string("name", 50)])
90///     .build()?;
91/// let query = table.bind(Arc::new(pool)).query(["admin"]);
92///
93/// // 选择字段
94/// let query = query.select_fields(&["id", "name"])?;
95///
96/// // 添加 WHERE 条件
97/// let query = query.where_eq("status", json!(1))?;
98///
99/// // 添加排序
100/// let query = query.order_by("created_at", SortOrder::Desc)?;
101///
102/// // 设置分页
103/// let query = query.page(1, 20)?;
104/// ```
105#[derive(Debug, Clone)]
106pub struct TableQuery {
107    /// 表配置引用
108    ///
109    /// 包含表结构、字段定义和权限配置
110    table_config: Arc<TableConfig>,
111
112    /// 用户角色列表
113    ///
114    /// 使用 Arc<[String]> 共享所有权,避免不必要的克隆
115    user_roles: Arc<[String]>,
116    /// 用户角色 HashSet 缓存(O(1) 查找,避免每次 can_read/can_write 时转换)
117    user_roles_set: HashSet<String>,
118
119    /// 查询参数
120    ///
121    /// 包含字段选择、WHERE 条件、排序规则和分页参数
122    query_params: QueryParams,
123
124    /// 是否在读取路径包含软删除记录
125    ///
126    /// 默认 `false`:配置了 `soft_delete_field` 的表,软删行不出现在
127    /// select/count/paginate 结果中。置为 `true`(经 [`TableQuery::with_trashed`])
128    /// 时读取全量(含已软删行)。
129    include_trashed: bool,
130
131    /// 启动期定义并在请求期注入的租户范围;存在时所有读写均必须带该条件。
132    tenant_scope: Option<(String, Value)>,
133
134    /// 数据库连接池引用(预留)
135    ///
136    /// 暂未使用,预留用于后续实现 CRUD 操作
137    #[cfg(feature = "mysql")]
138    #[allow(dead_code)]
139    pool: Option<Arc<sqlx::MySqlPool>>,
140
141    /// 慢查询阈值(可观测性 C4)
142    ///
143    /// `Some(d)` 时,单次执行耗时超过 `d` 会 `tracing::warn!`;`None`(默认)
144    /// 整个计时分支短路,热路径仅一次 `Instant::now()`,无分配。
145    /// 由 [`ActionContext::table_query`](crate::action::ActionContext) 从
146    /// [`ObservabilityConfig`](crate::observability::ObservabilityConfig) 注入。
147    slow_threshold: Option<std::time::Duration>,
148
149    /// 本次派发的运行期标识(用于慢查询日志串联),由 ActionContext 注入。
150    request_id: Option<crate::action::RequestId>,
151}