pub struct TableQuery { /* private fields */ }Expand description
表查询构建器
基于不可变表定义创建受保护的查询构建器,支持:
- 字段选择和权限验证
- WHERE 条件构建
- 排序规则
- 分页查询
§字段
- 内部表契约:由
super::TableDefinition提供字段定义和权限配置 user_roles:用户角色列表,用于权限检查query_params:查询参数,包含字段选择、WHERE 条件、排序规则和分页参数pool:数据库连接池引用(预留,暂未使用)
§示例
use yang_base::table::{Field, SortOrder, Table};
use std::sync::Arc;
use serde_json::json;
let table = Table::new("users")
.fields(vec![Field::id("id"), Field::string("name", 50)])
.build()?;
let query = table.bind(Arc::new(pool)).query(["admin"]);
// 选择字段
let query = query.select_fields(&["id", "name"])?;
// 添加 WHERE 条件
let query = query.where_eq("status", json!(1))?;
// 添加排序
let query = query.order_by("created_at", SortOrder::Desc)?;
// 设置分页
let query = query.page(1, 20)?;Implementations§
Source§impl TableQuery
impl TableQuery
Sourcepub fn with_slow_threshold(self, threshold: Option<Duration>) -> Self
pub fn with_slow_threshold(self, threshold: Option<Duration>) -> Self
设置慢查询阈值(链式)。超过该耗时的单次执行会 tracing::warn!。
通常由 ActionContext::table_query() 从全局 ObservabilityConfig 注入;
也可手动覆盖。None/不调用时不启用慢查询日志。
Sourcepub fn with_request_id(self, request_id: RequestId) -> Self
pub fn with_request_id(self, request_id: RequestId) -> Self
设置本次查询关联的 request_id(链式),用于慢查询日志串联。
Sourcepub fn select_fields(self, fields: &[&str]) -> Result<Self, BaseError>
pub fn select_fields(self, fields: &[&str]) -> Result<Self, BaseError>
选择要查询的字段。
会校验字段存在,并校验当前用户角色具备这些字段的读取权限。
Sourcepub fn where_eq(self, field: &str, value: Value) -> Result<Self, BaseError>
pub fn where_eq(self, field: &str, value: Value) -> Result<Self, BaseError>
添加等于条件 (WHERE field = value)
添加 WHERE 等于条件,并验证:
- 字段是否存在于表配置中
- 用户是否有字段的筛选权限
§参数
field:字段名value:比较值
§返回值
Ok(Self):验证通过,返回 self 支持链式调用Err(BaseError):验证失败,返回错误
§错误
BaseError::FieldNotFound:字段不存在BaseError::FieldPermissionDenied:用户无筛选权限
§示例
use serde_json::json;
let query = query.where_eq("status", json!("active"))?;Sourcepub fn where_in(
self,
field: &str,
values: Vec<Value>,
) -> Result<Self, BaseError>
pub fn where_in( self, field: &str, values: Vec<Value>, ) -> Result<Self, BaseError>
添加包含条件 (WHERE field IN (values))
添加 WHERE IN 条件,并验证:
- 字段是否存在于表配置中
- 用户是否有字段的筛选权限
§参数
field:字段名values:值列表
§返回值
Ok(Self):验证通过,返回 self 支持链式调用Err(BaseError):验证失败,返回错误
§错误
BaseError::FieldNotFound:字段不存在BaseError::FieldPermissionDenied:用户无筛选权限
§示例
use serde_json::json;
let query = query.where_in("status", vec![json!(1), json!(2), json!(3)])?;Sourcepub fn where_like(self, field: &str, pattern: String) -> Result<Self, BaseError>
pub fn where_like(self, field: &str, pattern: String) -> Result<Self, BaseError>
添加模糊匹配条件 (WHERE field LIKE pattern)
添加 WHERE LIKE 条件,并验证:
- 字段是否存在于表配置中
- 用户是否有字段的筛选权限
§参数
field:字段名pattern:匹配模式,支持 % 和 _ 通配符
§返回值
Ok(Self):验证通过,返回 self 支持链式调用Err(BaseError):验证失败,返回错误
§错误
BaseError::FieldNotFound:字段不存在BaseError::FieldPermissionDenied:用户无筛选权限
§示例
let query = query.where_like("name", "%alice%")?;Sourcepub fn where_contains(
self,
field: &str,
keyword: &str,
) -> Result<Self, BaseError>
pub fn where_contains( self, field: &str, keyword: &str, ) -> Result<Self, BaseError>
添加模糊匹配条件 (WHERE field LIKE ‘%keyword%’)
便捷方法:自动将 keyword 用 % 包裹,并转义其中的 % 和 _ 通配符,
避免用户输入中的通配符被解释为 SQL LIKE 语法。
§参数
field:字段名keyword:搜索关键词(无需手动加%)
§返回值
Ok(Self):验证通过,返回 self 支持链式调用Err(BaseError):验证失败(字段不存在 / 无权限 / 转义后超长)
§示例
// WHERE name LIKE '%alice%',且 "%" / "_" 被转义
let query = query.where_contains("name", "alice")?;Sourcepub fn where_between(
self,
field: &str,
lo: Value,
hi: Value,
) -> Result<Self, BaseError>
pub fn where_between( self, field: &str, lo: Value, hi: Value, ) -> Result<Self, BaseError>
添加区间条件 (WHERE field BETWEEN lo AND hi)
添加 WHERE BETWEEN 条件,并验证:
- 字段是否存在于表配置中
- 用户是否有字段的筛选权限
当 lo > hi 时 BETWEEN 返回空集(MySQL 标准行为,框架不做特殊处理)。
§参数
field:字段名lo:区间下界(包含)hi:区间上界(包含)
§返回值
Ok(Self):验证通过,返回 self 支持链式调用Err(BaseError):验证失败,返回错误
§错误
BaseError::FieldNotFound:字段不存在BaseError::FieldPermissionDenied:用户无筛选权限
Sourcepub fn where_null(self, field: &str) -> Result<Self, BaseError>
pub fn where_null(self, field: &str) -> Result<Self, BaseError>
Sourcepub fn where_not_null(self, field: &str) -> Result<Self, BaseError>
pub fn where_not_null(self, field: &str) -> Result<Self, BaseError>
Sourcepub fn order_by(self, field: &str, order: SortOrder) -> Result<Self, BaseError>
pub fn order_by(self, field: &str, order: SortOrder) -> Result<Self, BaseError>
添加排序规则。
会校验字段存在、字段允许排序,以及当前用户角色具备排序权限。
Sourcepub fn search(self, keyword: Option<&str>) -> Result<Self, BaseError>
pub fn search(self, keyword: Option<&str>) -> Result<Self, BaseError>
对声明了 searchable 且当前角色可读的文本字段应用一次 OR LIKE 搜索。
关键词搜索只认独立的 searchable 位(crate::table::Field::searchable),与
结构化 where 的 filterable 校验(validate_filter_field)互不开放。搜索字段
来自表定义迭代(必然存在)且已逐一验证 is_text / searchable / 可读 /
非 hidden,因此这里自行构造 OR 组、不经过 where_or 的 filterable 门槛;
但 LIKE pattern 长度上限(QRY-1)仍在本地强制执行。
Sourcepub fn with_trashed(self) -> Self
pub fn with_trashed(self) -> Self
在读取路径包含软删除记录
默认情况下,配置了 soft_delete_field 的表会在 select/count/paginate
时自动追加 软删字段 IS NULL 过滤,隐藏已软删行。调用本方法后,本次查询
读取全量数据(含已软删行)。
§返回值
返回 self 支持链式调用
Sourcepub fn where_or(
self,
conditions: Vec<WhereCondition>,
) -> Result<Self, BaseError>
pub fn where_or( self, conditions: Vec<WhereCondition>, ) -> Result<Self, BaseError>
添加一个 OR 逻辑组 (WHERE … AND (c1 OR c2 OR …))
组内每个子条件递归校验字段存在性与筛选权限;通过后整组以 Or 节点追加到
顶层条件列表,与既有条件以隐式 AND 连接。空组等价于恒假(1=0)。
子条件可由 WhereCondition 直接构造,亦可嵌套 And/Or 组(深度上限
MAX_WHERE_DEPTH)。
§参数
conditions:OR 组的子条件列表
§返回值
Ok(Self):校验通过,返回 self 支持链式调用Err(BaseError):字段不存在 / 无筛选权限 / 嵌套超限
§示例
use yang_base::table::WhereCondition;
use serde_json::json;
// WHERE status = 'active' AND (age >= 18 OR vip = true)
let query = query
.where_eq("status", json!("active"))?
.where_or(vec![
WhereCondition::Gte { field: "age".into(), value: json!(18) },
WhereCondition::Eq { field: "vip".into(), value: json!(true) },
])?;Sourcepub fn where_and(
self,
conditions: Vec<WhereCondition>,
) -> Result<Self, BaseError>
pub fn where_and( self, conditions: Vec<WhereCondition>, ) -> Result<Self, BaseError>
添加一个 AND 逻辑组 (WHERE … AND (c1 AND c2 AND …))
语义同 TableQuery::where_or,但组内子条件以 AND 连接。主要用于在 OR 组
内部嵌套 AND 子组;顶层多个条件本就隐式 AND,单独使用通常无必要。空组等价
于恒真(1=1)。
§参数
conditions:AND 组的子条件列表
§返回值
Ok(Self):校验通过,返回 self 支持链式调用Err(BaseError):字段不存在 / 无筛选权限 / 嵌套超限
Sourcepub fn where_tree(self, condition: WhereCondition) -> Result<Self, BaseError>
pub fn where_tree(self, condition: WhereCondition) -> Result<Self, BaseError>
追加一棵任意 WHERE 条件(叶子或 And/Or 组),递归校验后并入顶层条件。
这是以 WhereCondition 表示的类型化布尔树桥接到受保护层的统一入口:
整棵树先经 validate_condition_tree 递归校验字段存在性、筛选权限与
嵌套深度,通过后作为单个条件追加(与既有条件隐式 AND 连接)。
§参数
condition:任意WhereCondition(叶子或逻辑组)
§返回值
Ok(Self):校验通过,返回 self 支持链式调用Err(BaseError):字段不存在 / 无筛选权限 / 嵌套超限
Sourcepub fn get_query_params(&self) -> &QueryParams
pub fn get_query_params(&self) -> &QueryParams
Sourcepub fn apply_params(self, params: QueryParams) -> Result<Self, BaseError>
pub fn apply_params(self, params: QueryParams) -> Result<Self, BaseError>
应用通用列表参数,并复用本类型现有的字段/筛选/排序/分页权限校验。
Sourcepub fn get_user_roles(&self) -> &[String]
pub fn get_user_roles(&self) -> &[String]
Source§impl TableQuery
数据库执行方法(需要启用 mysql feature)
impl TableQuery
数据库执行方法(需要启用 mysql feature)
Sourcepub async fn paginate_records(
self,
) -> Result<PaginatedResult<Record>, BaseError>
pub async fn paginate_records( self, ) -> Result<PaginatedResult<Record>, BaseError>
执行分页查询并返回 schema-first Record。
Sourcepub async fn count(self) -> Result<u64, BaseError>
pub async fn count(self) -> Result<u64, BaseError>
执行 COUNT 查询获取总记录数
构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
§返回值
Ok(u64):查询成功,返回总记录数Err(BaseError):查询失败,返回错误
§错误
BaseError::DatabaseNotInitialized:数据库未初始化BaseError::DatabaseQueryFailed:查询执行失败
§示例
let total = query
.where_eq("status", serde_json::json!("active"))?
.count()
.await?;
println!("总记录数: {}", total);Sourcepub async fn all_in_tx(
self,
tx: &mut Transaction,
) -> Result<Vec<Record>, BaseError>
pub async fn all_in_tx( self, tx: &mut Transaction, ) -> Result<Vec<Record>, BaseError>
在事务中查询全部匹配记录。
Sourcepub async fn one(self) -> Result<Record, BaseError>
pub async fn one(self) -> Result<Record, BaseError>
查询单条记录;没有匹配记录时返回 BaseError::RecordNotFound。
Sourcepub async fn insert(self, data: Record) -> Result<u64, BaseError>
pub async fn insert(self, data: Record) -> Result<u64, BaseError>
执行 INSERT 操作
插入数据到表中,包括以下步骤:
- 按表定义验证所有字段值
- 检查用户是否有字段的写入权限
- 构建 INSERT SQL 语句
- 执行插入操作
- 返回影响行数
§参数
data:要插入的crate::table::Record
§返回值
Ok(u64):插入成功,返回影响行数(通常为 1)Err(BaseError):插入失败,返回错误
§错误
BaseError::DatabaseNotInitialized:数据库未初始化BaseError::FieldRequired:必填字段缺失BaseError::FieldPermissionDenied:用户无字段写入权限BaseError::ValidationFailed:字段值验证失败BaseError::DatabaseExecuteFailed:数据库执行失败
§示例
use yang_base::table::Record;
let data = Record::new()
.set("name", "张三")
.set("email", "zhangsan@example.com");
// 执行插入
let affected = query.insert(data).await?;
println!("插入成功,影响行数: {}", affected);Sourcepub async fn insert_in_tx(
self,
tx: &mut Transaction,
data: Record,
) -> Result<u64, BaseError>
pub async fn insert_in_tx( self, tx: &mut Transaction, data: Record, ) -> Result<u64, BaseError>
在事务中执行 INSERT 操作
与 TableQuery::insert 完全一致的写权限校验/默认值填充/时间戳/必填校验
流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
§错误
BaseError::DatabaseTransactionFailed:事务已提交/回滚- 其余同
TableQuery::insert
Sourcepub async fn insert_returning_id(
self,
data: Record,
) -> Result<(u64, u64), BaseError>
pub async fn insert_returning_id( self, data: Record, ) -> Result<(u64, u64), BaseError>
执行 INSERT 操作并返回自增主键
与 TableQuery::insert 完全一致的校验与拼 SQL 流程,但额外返回本次
INSERT 产生的自增主键值(last_insert_id),便于调用方拿到新建记录 ID。
§参数
data:要插入的数据
§返回值
Ok((affected, id)):插入成功,返回 (影响行数, 自增主键值)。 表无自增列时id为 0。Err(BaseError):插入失败
§错误
BaseError::DatabaseNotInitialized:数据库未初始化BaseError::FieldRequired:必填字段缺失BaseError::FieldPermissionDenied:用户无字段写入权限BaseError::DatabaseExecuteFailed:数据库执行失败
Sourcepub async fn insert_returning_id_in_tx(
self,
tx: &mut Transaction,
data: Record,
) -> Result<(u64, u64), BaseError>
pub async fn insert_returning_id_in_tx( self, tx: &mut Transaction, data: Record, ) -> Result<(u64, u64), BaseError>
在事务中执行 INSERT 并返回自增主键
与 TableQuery::insert_returning_id 一致,但在事务内执行。批量写入或
「插入父行→用其主键插入子行」等需要拿到新 ID 再继续的原子场景使用。
Sourcepub async fn update(self, data: Record) -> Result<u64, BaseError>
pub async fn update(self, data: Record) -> Result<u64, BaseError>
执行 UPDATE 操作
更新表中的数据,包括以下步骤:
- 按表定义验证所有字段值
- 检查用户是否有字段的写入权限
- 构建 UPDATE SQL 语句
- 应用已配置的 WHERE 条件
- 执行更新操作
- 返回影响行数
§参数
data:要更新的crate::table::Record
§返回值
Ok(u64):更新成功,返回影响行数Err(BaseError):更新失败,返回错误
§错误
BaseError::DatabaseNotInitialized:数据库未初始化BaseError::FieldNotFound:字段不存在BaseError::FieldPermissionDenied:用户无字段写入权限BaseError::ValidationFailed:字段值验证失败BaseError::DatabaseExecuteFailed:数据库执行失败
§示例
use yang_base::table::Record;
use serde_json::json;
let data = Record::new()
.set("name", "李四")
.set("email", "lisi@example.com");
// 执行更新(需要先设置 WHERE 条件)
let affected = query
.where_eq("id", json!(1))?
.update(data)
.await?;
println!("更新成功,影响行数: {}", affected);Sourcepub async fn update_in_tx(
self,
tx: &mut Transaction,
data: Record,
) -> Result<u64, BaseError>
pub async fn update_in_tx( self, tx: &mut Transaction, data: Record, ) -> Result<u64, BaseError>
在事务中执行 UPDATE 操作
与 TableQuery::update 一致的字段校验/权限/WHERE 守卫/自动 updated_at
逻辑,但在事务内执行。
§错误
BaseError::DatabaseTransactionFailed:事务已提交/回滚- 其余同
TableQuery::update
Sourcepub async fn delete(self) -> Result<u64, BaseError>
pub async fn delete(self) -> Result<u64, BaseError>
执行 DELETE 操作
删除表中的数据,支持软删除和物理删除两种模式:
- 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
- 如果未配置软删除字段,执行物理删除
- 应用已配置的 WHERE 条件
- 返回影响行数
§返回值
Ok(u64):删除成功,返回影响行数Err(BaseError):删除失败,返回错误
§错误
BaseError::DatabaseNotInitialized:数据库未初始化BaseError::DatabaseExecuteFailed:数据库执行失败
§示例
use serde_json::json;
use yang_base::table::{Field, Table};
let users = Table::new("users")
.fields(vec![
Field::id("id"),
Field::string("name", 50).required(),
Field::soft_delete("deleted_at"),
])
.build()?;
// 执行软删除(实际上是 UPDATE deleted_at = <timestamp>)
let affected = users
.bind(pool)
.query(["admin"])
.where_eq("id", json!(1))?
.delete()
.await?;
println!("删除成功,影响行数: {}", affected);Sourcepub async fn delete_in_tx(self, tx: &mut Transaction) -> Result<u64, BaseError>
pub async fn delete_in_tx(self, tx: &mut Transaction) -> Result<u64, BaseError>
在事务中执行 DELETE 操作
与 TableQuery::delete 一致:配置了软删除字段时走 UPDATE 标记(同样在
事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
§错误
BaseError::DatabaseTransactionFailed:事务已提交/回滚- 其余同
TableQuery::delete
Trait Implementations§
Source§impl Clone for TableQuery
impl Clone for TableQuery
Source§fn clone(&self) -> TableQuery
fn clone(&self) -> TableQuery
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for TableQuery
impl !UnwindSafe for TableQuery
impl Freeze for TableQuery
impl Send for TableQuery
impl Sync for TableQuery
impl Unpin for TableQuery
impl UnsafeUnpin for TableQuery
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more