yang_base/table/table_query.rs
1//! 表查询构建器
2//!
3//! 提供基于 TableConfig 的类型安全查询构建器,支持字段权限验证和 CRUD 操作。
4//!
5//! # 主要组件
6//!
7//! - `TableQuery`:查询构建器,支持链式调用
8//!
9//! # 示例
10//!
11//! ```rust,ignore
12//! use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
13//! use std::sync::Arc;
14//!
15//! // 创建表配置
16//! let table_config = Arc::new(
17//! TableConfig::new("users")
18//! .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
19//! .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
20//! .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
21//! );
22//!
23//! // 创建查询构建器
24//! let query = TableQuery::new(
25//! table_config,
26//! vec!["user".to_string()],
27//! pool,
28//! );
29//!
30//! // 链式调用构建查询
31//! let result = query
32//! .select_fields(&["id", "name", "email"])?
33//! .where_eq("status", json!("active"))?
34//! .order_by("created_at", SortOrder::Desc)?
35//! .page(1, 20)?
36//! .execute()
37//! .await?;
38//! ```
39
40use crate::error::BaseError;
41use crate::table::{QueryParams, SortOrder, TableConfig, WhereCondition};
42#[cfg(feature = "mysql")]
43use serde::Serialize;
44use serde_json::Value;
45use std::collections::HashSet;
46use std::sync::Arc;
47
48/// 受保护表查询允许的最大单页大小。
49///
50/// 该上限必须在 `TableQuery` 底层执行,而不能只放在上层 action。自定义 action 或库调用方
51/// 可直接调用 `ctx.table_query()?.page(...)`,底层没有上限会绕过内置 `SelectAction` 的保护,
52/// 导致超大查询拖垮数据库或应用内存。
53pub const MAX_TABLE_QUERY_PAGE_SIZE: usize = super::query_params::MAX_QUERY_PAGE_SIZE;
54
55/// 表查询构建器
56///
57/// 基于 TableConfig 创建类型安全的查询构建器,支持:
58/// - 字段选择和权限验证
59/// - WHERE 条件构建
60/// - 排序规则
61/// - 分页查询
62///
63/// # 字段
64///
65/// - `table_config`:表配置引用,包含字段定义和权限配置
66/// - `user_roles`:用户角色列表,用于权限检查
67/// - `query_params`:查询参数,包含字段选择、WHERE 条件、排序规则和分页参数
68/// - `pool`:数据库连接池引用(预留,暂未使用)
69///
70/// # 示例
71///
72/// ```rust,ignore
73/// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
74/// use std::sync::Arc;
75/// use serde_json::json;
76///
77/// let table_config = Arc::new(
78/// TableConfig::new("users")
79/// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
80/// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
81/// );
82///
83/// let query = TableQuery::new(
84/// table_config,
85/// vec!["admin".to_string()],
86/// pool,
87/// );
88///
89/// // 选择字段
90/// let query = query.select_fields(&["id", "name"])?;
91///
92/// // 添加 WHERE 条件
93/// let query = query.where_eq("status", json!(1))?;
94///
95/// // 添加排序
96/// let query = query.order_by("created_at", SortOrder::Desc)?;
97///
98/// // 设置分页
99/// let query = query.page(1, 20)?;
100/// ```
101#[derive(Debug, Clone)]
102pub struct TableQuery {
103 /// 表配置引用
104 ///
105 /// 包含表结构、字段定义和权限配置
106 table_config: Arc<TableConfig>,
107
108 /// 用户角色列表
109 ///
110 /// 使用 Arc<[String]> 共享所有权,避免不必要的克隆
111 user_roles: Arc<[String]>,
112 /// 用户角色 HashSet 缓存(O(1) 查找,避免每次 can_read/can_write 时转换)
113 user_roles_set: HashSet<String>,
114
115 /// 查询参数
116 ///
117 /// 包含字段选择、WHERE 条件、排序规则和分页参数
118 query_params: QueryParams,
119
120 /// 是否在读取路径包含软删除记录
121 ///
122 /// 默认 `false`:配置了 `soft_delete_field` 的表,软删行不出现在
123 /// select/count/paginate 结果中。置为 `true`(经 [`TableQuery::with_trashed`])
124 /// 时读取全量(含已软删行)。
125 include_trashed: bool,
126
127 /// 是否允许无 WHERE 的全表 UPDATE/DELETE
128 ///
129 /// 默认 `false`:无 WHERE 的更新/删除会返回 [`BaseError::MissingWhereClause`],
130 /// 与 yang-db 的安全网对齐。置为 `true`(经 [`TableQuery::allow_full_table`])
131 /// 时显式放行全表操作。
132 allow_full_table: bool,
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}
152
153/// 检查字符串是否为合法的 SQL 标识符
154///
155/// 合法标识符规则:
156/// - 首字符必须是 ASCII 字母或下划线
157/// - 后续字符必须是 ASCII 字母、数字或下划线
158/// - 不能为空
159/// - 不能包含分号、`--`、空白字符
160#[cfg(feature = "mysql")]
161fn is_valid_identifier(s: &str) -> bool {
162 if s.is_empty() {
163 return false;
164 }
165 let mut chars = s.chars();
166 match chars.next() {
167 Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
168 _ => return false,
169 }
170 chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
171}
172
173impl TableQuery {
174 /// 对字段名进行反引号转义
175 ///
176 /// 对合法标识符添加反引号,内部反引号转义为双反引号。
177 /// 非法字段名返回 `BaseError::FieldNotFound`。
178 ///
179 /// # 参数
180 ///
181 /// - `field`: 字段名
182 ///
183 /// # 返回
184 ///
185 /// - `Ok(String)`: 转义后的字段名,如 `` `field_name` ``
186 /// - `Err(BaseError)`: 字段名非法
187 #[cfg(feature = "mysql")]
188 fn quote_identifier(&self, field: &str) -> Result<String, BaseError> {
189 if !is_valid_identifier(field) {
190 return Err(BaseError::FieldNotFound(
191 self.table_config.table_name.clone(),
192 field.to_string(),
193 ));
194 }
195 // 反引号转义:内部反引号变双反引号
196 Ok(format!("`{}`", field.replace('`', "``")))
197 }
198
199 /// 对表名进行反引号转义(与字段名走同一条校验/转义路径)
200 ///
201 /// 防止非法表名破坏引号边界。表名虽来自开发者配置而非终端用户输入,
202 /// 但统一转义可消除字段名与表名处理的不一致(防御纵深)。
203 ///
204 /// # 返回
205 ///
206 /// - `Ok(String)`: 转义后的表名,如 `` `users` ``
207 /// - `Err(BaseError)`: 表名非法
208 #[cfg(feature = "mysql")]
209 fn quoted_table_name(&self) -> Result<String, BaseError> {
210 let name = &self.table_config.table_name;
211 if !is_valid_identifier(name) {
212 return Err(BaseError::FieldNotFound(
213 name.clone(),
214 "非法表名".to_string(),
215 ));
216 }
217 Ok(format!("`{}`", name.replace('`', "``")))
218 }
219
220 /// 创建新的查询构建器
221 ///
222 /// # 参数
223 ///
224 /// - `table_config`:表配置引用
225 /// - `user_roles`:用户角色列表(`Arc<[String]>` 共享所有权)
226 /// - `pool`:数据库连接池引用(可选)
227 ///
228 /// # 返回值
229 ///
230 /// 返回新的 TableQuery 实例
231 #[cfg(feature = "mysql")]
232 pub fn new(
233 table_config: Arc<TableConfig>,
234 user_roles: Arc<[String]>,
235 pool: Option<Arc<sqlx::MySqlPool>>,
236 ) -> Self {
237 let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
238 Self {
239 table_config,
240 user_roles,
241 user_roles_set,
242 query_params: QueryParams::new(),
243 include_trashed: false,
244 allow_full_table: false,
245 pool,
246 slow_threshold: None,
247 request_id: None,
248 }
249 }
250
251 /// 创建新的查询构建器(无数据库连接池)
252 ///
253 /// 当未启用 `mysql` feature 时使用此方法。
254 #[cfg(not(feature = "mysql"))]
255 pub fn new(
256 table_config: Arc<TableConfig>,
257 user_roles: Arc<[String]>,
258 _pool: Option<()>,
259 ) -> Self {
260 let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
261 Self {
262 table_config,
263 user_roles,
264 user_roles_set,
265 query_params: QueryParams::new(),
266 include_trashed: false,
267 allow_full_table: false,
268 slow_threshold: None,
269 request_id: None,
270 }
271 }
272
273 /// 设置慢查询阈值(链式)。超过该耗时的单次执行会 `tracing::warn!`。
274 ///
275 /// 通常由 `ActionContext::table_query()` 从全局 `ObservabilityConfig` 注入;
276 /// 也可手动覆盖。`None`/不调用时不启用慢查询日志。
277 pub fn with_slow_threshold(mut self, threshold: Option<std::time::Duration>) -> Self {
278 self.slow_threshold = threshold;
279 self
280 }
281
282 /// 设置本次查询关联的 request_id(链式),用于慢查询日志串联。
283 pub fn with_request_id(mut self, request_id: crate::action::RequestId) -> Self {
284 self.request_id = Some(request_id);
285 self
286 }
287
288 /// 选择查询字段
289 ///
290 /// 设置要查询的字段列表,并验证:
291 /// 1. 字段是否存在于表配置中
292 /// 2. 用户是否有字段的读取权限
293 ///
294 /// # 参数
295 ///
296 /// - `fields`:字段名列表
297 ///
298 /// # 返回值
299 ///
300 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
301 /// - `Err(BaseError)`:验证失败,返回错误
302 ///
303 /// # 错误
304 ///
305 /// - `BaseError::FieldNotFound`:字段不存在
306 /// - `BaseError::FieldPermissionDenied`:用户无读取权限
307 ///
308 /// # 示例
309 ///
310 /// ```rust
311 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
312 /// use std::sync::Arc;
313 ///
314 /// // 创建表配置
315 /// let table_config = Arc::new(
316 /// TableConfig::new("users")
317 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
318 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
319 /// .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
320 /// );
321 ///
322 /// // 创建查询构建器(不需要数据库连接)
323 /// let query = TableQuery::new(
324 /// table_config,
325 /// Arc::from(vec!["admin".to_string()]),
326 /// None,
327 /// );
328 ///
329 /// // 选择存在的字段,应成功
330 /// let result = query.select_fields(&["id", "name", "email"]);
331 /// assert!(result.is_ok());
332 ///
333 /// // 选择不存在的字段,应返回错误
334 /// let table_config2 = Arc::new(
335 /// TableConfig::new("users")
336 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
337 /// );
338 /// let query2 = TableQuery::new(
339 /// table_config2,
340 /// Arc::from(vec!["admin".to_string()]),
341 /// None,
342 /// );
343 /// let result2 = query2.select_fields(&["nonexistent_field"]);
344 /// assert!(result2.is_err());
345 /// ```
346 fn validate_read_field(&self, field_name: &str) -> Result<(), BaseError> {
347 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
348 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.to_string())
349 })?;
350
351 if !field_config.permissions.can_read(&self.user_roles_set) {
352 return Err(BaseError::FieldPermissionDenied(
353 self.table_config.table_name.clone(),
354 field_name.to_string(),
355 "用户无读取权限".to_string(),
356 ));
357 }
358
359 Ok(())
360 }
361
362 fn validate_all_fields_readable_for_roles(
363 &self,
364 roles: &HashSet<String>,
365 ) -> Result<(), BaseError> {
366 if let Some(field_name) = self
367 .table_config
368 .fields
369 .iter()
370 .filter_map(|(field_name, field_config)| {
371 (!field_config.permissions.can_read(roles)).then_some(field_name)
372 })
373 .min()
374 {
375 return Err(BaseError::FieldPermissionDenied(
376 self.table_config.table_name.clone(),
377 field_name.clone(),
378 "用户无读取权限".to_string(),
379 ));
380 }
381 Ok(())
382 }
383
384 #[cfg(feature = "mysql")]
385 fn validate_all_fields_readable(&self) -> Result<(), BaseError> {
386 self.validate_all_fields_readable_for_roles(&self.user_roles_set)
387 }
388
389 /// 选择要查询的字段。
390 ///
391 /// 会校验字段存在,并校验当前用户角色具备这些字段的读取权限。
392 pub fn select_fields(mut self, fields: &[&str]) -> Result<Self, BaseError> {
393 if fields.is_empty() {
394 return Err(BaseError::ParamInvalid(
395 "fields".to_string(),
396 "查询字段列表不能为空".to_string(),
397 ));
398 }
399
400 // 验证每个字段
401 for field_name in fields {
402 self.validate_read_field(field_name)?;
403 }
404
405 // 设置字段列表
406 self.query_params.fields = Some(fields.iter().map(|s| s.to_string()).collect());
407
408 Ok(self)
409 }
410
411 /// 强制校验当前用户对表内所有字段的读权限
412 ///
413 /// 内置 Get/Select Action 读取整实体(`SELECT *`)时,在执行查询前调用本方法,
414 /// 确保不会把用户无权读取的字段一并返回。遍历表配置中的每个字段,对
415 /// `readable_roles` 非空且用户不具备任一可读角色的字段返回
416 /// [`BaseError::FieldPermissionDenied`]。与 [`TableQuery::select_fields`] 的
417 /// `can_read` 判定机制保持一致。
418 ///
419 /// # 参数
420 ///
421 /// - `user`:当前用户(其 `roles` 用于权限判定)
422 ///
423 /// # 返回值
424 ///
425 /// - `Ok(())`:用户对全部字段可读
426 /// - `Err(BaseError::FieldPermissionDenied)`:存在不可读字段
427 pub fn ensure_fields_readable(&self, user: &crate::action::User) -> Result<(), BaseError> {
428 self.validate_all_fields_readable_for_roles(&user.roles)
429 }
430
431 /// 添加等于条件 (WHERE field = value)
432 ///
433 /// 添加 WHERE 等于条件,并验证:
434 /// 1. 字段是否存在于表配置中
435 /// 2. 用户是否有字段的筛选权限
436 ///
437 /// # 参数
438 ///
439 /// - `field`:字段名
440 /// - `value`:比较值
441 ///
442 /// # 返回值
443 ///
444 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
445 /// - `Err(BaseError)`:验证失败,返回错误
446 ///
447 /// # 错误
448 ///
449 /// - `BaseError::FieldNotFound`:字段不存在
450 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
451 ///
452 /// # 示例
453 ///
454 /// ```rust,ignore
455 /// use serde_json::json;
456 ///
457 /// let query = query.where_eq("status", json!("active"))?;
458 /// ```
459 pub fn where_eq(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
460 // 验证字段和权限
461 self.validate_filter_field(field)?;
462
463 // 添加 WHERE 条件
464 self.query_params.where_conditions.push(WhereCondition::Eq {
465 field: field.to_string(),
466 value,
467 });
468
469 Ok(self)
470 }
471
472 /// 添加包含条件 (WHERE field IN (values))
473 ///
474 /// 添加 WHERE IN 条件,并验证:
475 /// 1. 字段是否存在于表配置中
476 /// 2. 用户是否有字段的筛选权限
477 ///
478 /// # 参数
479 ///
480 /// - `field`:字段名
481 /// - `values`:值列表
482 ///
483 /// # 返回值
484 ///
485 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
486 /// - `Err(BaseError)`:验证失败,返回错误
487 ///
488 /// # 错误
489 ///
490 /// - `BaseError::FieldNotFound`:字段不存在
491 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
492 ///
493 /// # 示例
494 ///
495 /// ```rust,ignore
496 /// use serde_json::json;
497 ///
498 /// let query = query.where_in("status", vec![json!(1), json!(2), json!(3)])?;
499 /// ```
500 pub fn where_in(mut self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
501 if values.is_empty() {
502 return Err(BaseError::ParamInvalid(
503 "values".to_string(),
504 "IN 列表不能为空".to_string(),
505 ));
506 }
507
508 // QRY-2: IN 列表元素数上限
509 if values.len() > Self::MAX_IN_LIST_SIZE {
510 return Err(BaseError::ParamInvalid(
511 "values".to_string(),
512 format!(
513 "IN 列表元素数 {} 超过上限 {}",
514 values.len(),
515 Self::MAX_IN_LIST_SIZE
516 ),
517 ));
518 }
519
520 // 验证字段和权限
521 self.validate_filter_field(field)?;
522
523 // 添加 WHERE 条件
524 self.query_params.where_conditions.push(WhereCondition::In {
525 field: field.to_string(),
526 values,
527 });
528
529 Ok(self)
530 }
531
532 /// 添加模糊匹配条件 (WHERE field LIKE pattern)
533 ///
534 /// 添加 WHERE LIKE 条件,并验证:
535 /// 1. 字段是否存在于表配置中
536 /// 2. 用户是否有字段的筛选权限
537 ///
538 /// # 参数
539 ///
540 /// - `field`:字段名
541 /// - `pattern`:匹配模式,支持 % 和 _ 通配符
542 ///
543 /// # 返回值
544 ///
545 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
546 /// - `Err(BaseError)`:验证失败,返回错误
547 ///
548 /// # 错误
549 ///
550 /// - `BaseError::FieldNotFound`:字段不存在
551 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
552 ///
553 /// # 示例
554 ///
555 /// ```rust,ignore
556 /// let query = query.where_like("name", "%alice%")?;
557 /// ```
558 pub fn where_like(mut self, field: &str, pattern: String) -> Result<Self, BaseError> {
559 // QRY-1: LIKE pattern 长度上限
560 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
561 return Err(BaseError::ParamInvalid(
562 "pattern".to_string(),
563 format!(
564 "LIKE pattern 长度 {} 超过上限 {}",
565 pattern.len(),
566 Self::MAX_LIKE_PATTERN_LEN
567 ),
568 ));
569 }
570
571 // 验证字段和权限
572 self.validate_filter_field(field)?;
573
574 // 添加 WHERE 条件
575 self.query_params
576 .where_conditions
577 .push(WhereCondition::Like {
578 field: field.to_string(),
579 pattern,
580 });
581
582 Ok(self)
583 }
584
585 /// 添加模糊匹配条件 (WHERE field LIKE '%keyword%')
586 ///
587 /// 便捷方法:自动将 `keyword` 用 `%` 包裹,并转义其中的 `%` 和 `_` 通配符,
588 /// 避免用户输入中的通配符被解释为 SQL LIKE 语法。
589 ///
590 /// # 参数
591 ///
592 /// - `field`:字段名
593 /// - `keyword`:搜索关键词(无需手动加 `%`)
594 ///
595 /// # 返回值
596 ///
597 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
598 /// - `Err(BaseError)`:验证失败(字段不存在 / 无权限 / 转义后超长)
599 ///
600 /// # 示例
601 ///
602 /// ```rust,ignore
603 /// // WHERE name LIKE '%alice%',且 "%" / "_" 被转义
604 /// let query = query.where_contains("name", "alice")?;
605 /// ```
606 pub fn where_contains(mut self, field: &str, keyword: &str) -> Result<Self, BaseError> {
607 if keyword.trim().is_empty() {
608 return Err(BaseError::ParamInvalid(
609 "keyword".to_string(),
610 "搜索关键词不能为空".to_string(),
611 ));
612 }
613
614 // 转义 LIKE 通配符:% → \%,_ → \_
615 let escaped = keyword
616 .replace('\\', "\\\\")
617 .replace('%', "\\%")
618 .replace('_', "\\_");
619 let pattern = format!("%{}%", escaped);
620
621 // 复用 where_like 的校验(含 pattern 长度上限 + 字段权限)
622 self = self.where_like(field, pattern)?;
623 Ok(self)
624 }
625
626 /// 添加不等于条件 (WHERE field <> value)
627 ///
628 /// 添加 WHERE 不等于条件,并验证:
629 /// 1. 字段是否存在于表配置中
630 /// 2. 用户是否有字段的筛选权限
631 ///
632 /// # 参数
633 ///
634 /// - `field`:字段名
635 /// - `value`:比较值
636 ///
637 /// # 返回值
638 ///
639 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
640 /// - `Err(BaseError)`:验证失败,返回错误
641 ///
642 /// # 错误
643 ///
644 /// - `BaseError::FieldNotFound`:字段不存在
645 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
646 pub fn where_ne(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
647 self.validate_filter_field(field)?;
648 self.query_params.where_conditions.push(WhereCondition::Ne {
649 field: field.to_string(),
650 value,
651 });
652 Ok(self)
653 }
654
655 /// 添加小于条件 (WHERE field < value)
656 ///
657 /// 添加 WHERE 小于条件,并验证:
658 /// 1. 字段是否存在于表配置中
659 /// 2. 用户是否有字段的筛选权限
660 ///
661 /// # 参数
662 ///
663 /// - `field`:字段名
664 /// - `value`:比较值
665 ///
666 /// # 返回值
667 ///
668 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
669 /// - `Err(BaseError)`:验证失败,返回错误
670 ///
671 /// # 错误
672 ///
673 /// - `BaseError::FieldNotFound`:字段不存在
674 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
675 pub fn where_lt(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
676 self.validate_filter_field(field)?;
677 self.query_params.where_conditions.push(WhereCondition::Lt {
678 field: field.to_string(),
679 value,
680 });
681 Ok(self)
682 }
683
684 /// 添加小于等于条件 (WHERE field <= value)
685 ///
686 /// 添加 WHERE 小于等于条件,并验证:
687 /// 1. 字段是否存在于表配置中
688 /// 2. 用户是否有字段的筛选权限
689 ///
690 /// # 参数
691 ///
692 /// - `field`:字段名
693 /// - `value`:比较值
694 ///
695 /// # 返回值
696 ///
697 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
698 /// - `Err(BaseError)`:验证失败,返回错误
699 ///
700 /// # 错误
701 ///
702 /// - `BaseError::FieldNotFound`:字段不存在
703 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
704 pub fn where_lte(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
705 self.validate_filter_field(field)?;
706 self.query_params
707 .where_conditions
708 .push(WhereCondition::Lte {
709 field: field.to_string(),
710 value,
711 });
712 Ok(self)
713 }
714
715 /// 添加大于条件 (WHERE field > value)
716 ///
717 /// 添加 WHERE 大于条件,并验证:
718 /// 1. 字段是否存在于表配置中
719 /// 2. 用户是否有字段的筛选权限
720 ///
721 /// # 参数
722 ///
723 /// - `field`:字段名
724 /// - `value`:比较值
725 ///
726 /// # 返回值
727 ///
728 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
729 /// - `Err(BaseError)`:验证失败,返回错误
730 ///
731 /// # 错误
732 ///
733 /// - `BaseError::FieldNotFound`:字段不存在
734 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
735 pub fn where_gt(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
736 self.validate_filter_field(field)?;
737 self.query_params.where_conditions.push(WhereCondition::Gt {
738 field: field.to_string(),
739 value,
740 });
741 Ok(self)
742 }
743
744 /// 添加大于等于条件 (WHERE field >= value)
745 ///
746 /// 添加 WHERE 大于等于条件,并验证:
747 /// 1. 字段是否存在于表配置中
748 /// 2. 用户是否有字段的筛选权限
749 ///
750 /// # 参数
751 ///
752 /// - `field`:字段名
753 /// - `value`:比较值
754 ///
755 /// # 返回值
756 ///
757 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
758 /// - `Err(BaseError)`:验证失败,返回错误
759 ///
760 /// # 错误
761 ///
762 /// - `BaseError::FieldNotFound`:字段不存在
763 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
764 pub fn where_gte(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
765 self.validate_filter_field(field)?;
766 self.query_params
767 .where_conditions
768 .push(WhereCondition::Gte {
769 field: field.to_string(),
770 value,
771 });
772 Ok(self)
773 }
774
775 /// 添加区间条件 (WHERE field BETWEEN lo AND hi)
776 ///
777 /// 添加 WHERE BETWEEN 条件,并验证:
778 /// 1. 字段是否存在于表配置中
779 /// 2. 用户是否有字段的筛选权限
780 ///
781 /// 当 `lo > hi` 时 BETWEEN 返回空集(MySQL 标准行为,框架不做特殊处理)。
782 ///
783 /// # 参数
784 ///
785 /// - `field`:字段名
786 /// - `lo`:区间下界(包含)
787 /// - `hi`:区间上界(包含)
788 ///
789 /// # 返回值
790 ///
791 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
792 /// - `Err(BaseError)`:验证失败,返回错误
793 ///
794 /// # 错误
795 ///
796 /// - `BaseError::FieldNotFound`:字段不存在
797 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
798 pub fn where_between(mut self, field: &str, lo: Value, hi: Value) -> Result<Self, BaseError> {
799 self.validate_filter_field(field)?;
800 self.query_params
801 .where_conditions
802 .push(WhereCondition::Between {
803 field: field.to_string(),
804 lo,
805 hi,
806 });
807 Ok(self)
808 }
809
810 /// 添加空值判断 (WHERE field IS NULL)
811 ///
812 /// 添加 WHERE IS NULL 条件,并验证:
813 /// 1. 字段是否存在于表配置中
814 /// 2. 用户是否有字段的筛选权限
815 ///
816 /// # 参数
817 ///
818 /// - `field`:字段名
819 ///
820 /// # 返回值
821 ///
822 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
823 /// - `Err(BaseError)`:验证失败,返回错误
824 ///
825 /// # 错误
826 ///
827 /// - `BaseError::FieldNotFound`:字段不存在
828 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
829 pub fn where_null(mut self, field: &str) -> Result<Self, BaseError> {
830 self.validate_filter_field(field)?;
831 self.query_params
832 .where_conditions
833 .push(WhereCondition::IsNull {
834 field: field.to_string(),
835 });
836 Ok(self)
837 }
838
839 /// 添加非空值判断 (WHERE field IS NOT NULL)
840 ///
841 /// 添加 WHERE IS NOT NULL 条件,并验证:
842 /// 1. 字段是否存在于表配置中
843 /// 2. 用户是否有字段的筛选权限
844 ///
845 /// # 参数
846 ///
847 /// - `field`:字段名
848 ///
849 /// # 返回值
850 ///
851 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
852 /// - `Err(BaseError)`:验证失败,返回错误
853 ///
854 /// # 错误
855 ///
856 /// - `BaseError::FieldNotFound`:字段不存在
857 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
858 pub fn where_not_null(mut self, field: &str) -> Result<Self, BaseError> {
859 self.validate_filter_field(field)?;
860 self.query_params
861 .where_conditions
862 .push(WhereCondition::IsNotNull {
863 field: field.to_string(),
864 });
865 Ok(self)
866 }
867
868 /// 添加不在列表条件 (WHERE field NOT IN (values))
869 ///
870 /// 添加 WHERE NOT IN 条件,并验证:
871 /// 1. 字段是否存在于表配置中
872 /// 2. 用户是否有字段的筛选权限
873 ///
874 /// # 参数
875 ///
876 /// - `field`:字段名
877 /// - `values`:排除值列表
878 ///
879 /// # 返回值
880 ///
881 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
882 /// - `Err(BaseError)`:验证失败,返回错误
883 ///
884 /// # 错误
885 ///
886 /// - `BaseError::FieldNotFound`:字段不存在
887 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
888 pub fn where_not_in(mut self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
889 if values.is_empty() {
890 return Err(BaseError::ParamInvalid(
891 "values".to_string(),
892 "NOT IN 列表不能为空".to_string(),
893 ));
894 }
895
896 // QRY-2: NOT IN 列表元素数上限
897 if values.len() > Self::MAX_IN_LIST_SIZE {
898 return Err(BaseError::ParamInvalid(
899 "values".to_string(),
900 format!(
901 "NOT IN 列表元素数 {} 超过上限 {}",
902 values.len(),
903 Self::MAX_IN_LIST_SIZE
904 ),
905 ));
906 }
907
908 self.validate_filter_field(field)?;
909 self.query_params
910 .where_conditions
911 .push(WhereCondition::NotIn {
912 field: field.to_string(),
913 values,
914 });
915 Ok(self)
916 }
917
918 /// 添加排序规则 (ORDER BY field direction)
919 ///
920 /// 添加排序规则,并验证:
921 /// 1. 字段是否存在于表配置中
922 /// 2. 用户是否有字段的排序权限
923 ///
924 /// # 参数
925 ///
926 /// - `field`:字段名
927 /// - `order`:排序方向 (Asc 或 Desc)
928 ///
929 /// # 返回值
930 ///
931 /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
932 /// - `Err(BaseError)`:验证失败,返回错误
933 ///
934 /// # 错误
935 ///
936 /// - `BaseError::FieldNotFound`:字段不存在
937 /// - `BaseError::FieldPermissionDenied`:用户无排序权限
938 ///
939 /// # 示例
940 ///
941 /// ```rust,ignore
942 /// use yang_base::table::SortOrder;
943 ///
944 /// let query = query.order_by("created_at", SortOrder::Desc)?;
945 /// ```
946 fn validate_order_field(&self, field: &str) -> Result<(), BaseError> {
947 // 1. 检查字段是否存在
948 let field_config = self.table_config.get_field(field).ok_or_else(|| {
949 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
950 })?;
951
952 // 2. 字段级排序开关:标记为不可排序的字段直接拒绝(先于角色权限,
953 // 确保 `.sortable(false)` 是硬约束而非可被空角色列表绕过的软提示)
954 if !field_config.sortable {
955 return Err(BaseError::FieldPermissionDenied(
956 self.table_config.table_name.clone(),
957 field.to_string(),
958 "字段不允许排序".to_string(),
959 ));
960 }
961
962 // 3. 检查用户是否有排序权限
963 if !field_config.permissions.can_sort(&self.user_roles_set) {
964 return Err(BaseError::FieldPermissionDenied(
965 self.table_config.table_name.clone(),
966 field.to_string(),
967 "用户无排序权限".to_string(),
968 ));
969 }
970
971 Ok(())
972 }
973
974 /// 添加排序规则。
975 ///
976 /// 会校验字段存在、字段允许排序,以及当前用户角色具备排序权限。
977 pub fn order_by(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
978 self.validate_order_field(field)?;
979
980 // 添加排序规则
981 self.query_params.order_by.push((field.to_string(), order));
982
983 Ok(self)
984 }
985
986 /// 设置分页参数 (LIMIT and OFFSET)
987 ///
988 /// 设置查询的分页参数
989 ///
990 /// # 参数
991 ///
992 /// - `page`:当前页码,从 1 开始
993 /// - `page_size`:每页大小
994 ///
995 /// # 返回值
996 ///
997 /// 返回 self 支持链式调用
998 ///
999 /// # 示例
1000 ///
1001 /// ```rust,ignore
1002 /// let query = query.page(1, 20)?;
1003 /// ```
1004 pub fn page(mut self, page: usize, page_size: usize) -> Result<Self, BaseError> {
1005 if page == 0 || page_size == 0 {
1006 return Err(BaseError::ParamInvalid(
1007 "page".to_string(),
1008 "页码与每页大小必须从 1 开始且大于 0".to_string(),
1009 ));
1010 }
1011 if page_size > MAX_TABLE_QUERY_PAGE_SIZE {
1012 return Err(BaseError::ParamInvalid(
1013 "page_size".to_string(),
1014 format!("每页大小不能超过 {}", MAX_TABLE_QUERY_PAGE_SIZE),
1015 ));
1016 }
1017 self.query_params.page = Some(page);
1018 self.query_params.page_size = Some(page_size);
1019 Ok(self)
1020 }
1021
1022 /// 在读取路径包含软删除记录
1023 ///
1024 /// 默认情况下,配置了 `soft_delete_field` 的表会在 select/count/paginate
1025 /// 时自动追加 `软删字段 IS NULL` 过滤,隐藏已软删行。调用本方法后,本次查询
1026 /// 读取全量数据(含已软删行)。
1027 ///
1028 /// # 返回值
1029 ///
1030 /// 返回 self 支持链式调用
1031 pub fn with_trashed(mut self) -> Self {
1032 self.include_trashed = true;
1033 self
1034 }
1035
1036 /// 允许无 WHERE 条件的全表 UPDATE/DELETE
1037 ///
1038 /// 默认情况下,未设置任何 WHERE 条件的更新/删除会返回
1039 /// [`BaseError::MissingWhereClause`] 以防止误操作整表。调用本方法显式放行
1040 /// 全表操作(如批量初始化、清空表)。
1041 ///
1042 /// # 返回值
1043 ///
1044 /// 返回 self 支持链式调用
1045 pub fn allow_full_table(mut self) -> Self {
1046 self.allow_full_table = true;
1047 self
1048 }
1049
1050 /// 验证筛选字段的权限
1051 ///
1052 /// 内部辅助方法,用于验证字段是否存在以及用户是否有筛选权限
1053 ///
1054 /// # 参数
1055 ///
1056 /// - `field`:字段名
1057 ///
1058 /// # 返回值
1059 ///
1060 /// - `Ok(())`:验证通过
1061 /// - `Err(BaseError)`:验证失败
1062 ///
1063 /// # 错误
1064 ///
1065 /// - `BaseError::FieldNotFound`:字段不存在
1066 /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
1067 fn validate_filter_field(&self, field: &str) -> Result<(), BaseError> {
1068 // 1. 检查字段是否存在
1069 let field_config = self.table_config.get_field(field).ok_or_else(|| {
1070 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
1071 })?;
1072
1073 // 2. 字段级筛选开关:标记为不可筛选的字段直接拒绝(先于角色权限,
1074 // 确保 `.filterable(false)` 是硬约束而非可被空角色列表绕过的软提示)
1075 if !field_config.filterable {
1076 return Err(BaseError::FieldPermissionDenied(
1077 self.table_config.table_name.clone(),
1078 field.to_string(),
1079 "字段不允许筛选".to_string(),
1080 ));
1081 }
1082
1083 // 3. 检查用户是否有筛选权限
1084 if !field_config.permissions.can_filter(&self.user_roles_set) {
1085 return Err(BaseError::FieldPermissionDenied(
1086 self.table_config.table_name.clone(),
1087 field.to_string(),
1088 "用户无筛选权限".to_string(),
1089 ));
1090 }
1091
1092 Ok(())
1093 }
1094
1095 /// 嵌套布尔条件的最大递归深度,防止深层嵌套(或恶意构造)爆栈。
1096 ///
1097 /// 校验期(`validate_condition_tree`)与渲染期(`render_condition`)共用同一上限。
1098 const MAX_WHERE_DEPTH: usize = 32;
1099
1100 /// LIKE pattern 最大字节长度(QRY-1 防 DoS)。
1101 ///
1102 /// 超长 pattern 会导致 MySQL 索引失效、全表扫描放大;`where_like` /
1103 /// `where_contains` / 校验期 / 渲染期统一拦截。
1104 const MAX_LIKE_PATTERN_LEN: usize = 128;
1105
1106 /// IN / NOT IN 列表最大元素数(QRY-2 防 DoS)。
1107 ///
1108 /// 过长的 IN 列表会导致 MySQL 优化器退化、解析/绑定开销放大;`where_in` /
1109 /// `where_not_in` / 校验期 / 渲染期统一拦截。
1110 const MAX_IN_LIST_SIZE: usize = 500;
1111
1112 /// 递归校验一棵 WHERE 条件树的字段与筛选权限。
1113 ///
1114 /// 叶子条件校验其字段存在且当前角色可筛选;逻辑组(`And`/`Or`)递归下钻校验
1115 /// 每个子条件。深度超过 [`Self::MAX_WHERE_DEPTH`] 返回 `ParamInvalid` 而非
1116 /// panic,与渲染期保持一致的防爆栈上限。
1117 ///
1118 /// # 错误
1119 ///
1120 /// - `BaseError::FieldNotFound`:某叶子字段不存在
1121 /// - `BaseError::FieldPermissionDenied`:某叶子字段无筛选权限
1122 /// - `BaseError::ParamInvalid`:嵌套层数超限
1123 fn validate_condition_tree(
1124 &self,
1125 condition: &WhereCondition,
1126 depth: usize,
1127 ) -> Result<(), BaseError> {
1128 if depth > Self::MAX_WHERE_DEPTH {
1129 return Err(BaseError::ParamInvalid(
1130 "where".to_string(),
1131 format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1132 ));
1133 }
1134
1135 match condition {
1136 WhereCondition::And { conditions } | WhereCondition::Or { conditions } => {
1137 // 空布尔组拒绝:空 And 渲染为 `1=1`、空 Or 渲染为 `1=0`,前者会使
1138 // `where_conditions` 非空从而绕过 UPDATE/DELETE 的全表写守卫,生成
1139 // `WHERE (1=1)` 全表改写。在校验期直接拒绝空组,杜绝该绕过路径。
1140 if conditions.is_empty() {
1141 return Err(BaseError::ParamInvalid(
1142 "where".to_string(),
1143 "AND/OR 布尔组不能为空".to_string(),
1144 ));
1145 }
1146 for child in conditions {
1147 self.validate_condition_tree(child, depth + 1)?;
1148 }
1149 Ok(())
1150 }
1151 // 叶子:必有字段,校验存在性与筛选权限;同时校验 LIKE/IN 上限(QRY-1/QRY-2)
1152 leaf => {
1153 let field = leaf.field().ok_or_else(|| {
1154 BaseError::ParamInvalid(
1155 "condition".to_string(),
1156 "条件节点缺少字段名".to_string(),
1157 )
1158 })?;
1159 self.validate_filter_field(field)?;
1160 // LIKE pattern 长度上限(QRY-1)
1161 if let WhereCondition::Like { pattern, .. } = leaf {
1162 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1163 return Err(BaseError::ParamInvalid(
1164 "pattern".to_string(),
1165 format!(
1166 "LIKE pattern 长度 {} 超过上限 {}",
1167 pattern.len(),
1168 Self::MAX_LIKE_PATTERN_LEN
1169 ),
1170 ));
1171 }
1172 }
1173 // IN / NOT IN 列表元素数上限(QRY-2)
1174 if let WhereCondition::In { values, .. } | WhereCondition::NotIn { values, .. } =
1175 leaf
1176 {
1177 if values.is_empty() {
1178 return Err(BaseError::ParamInvalid(
1179 "values".to_string(),
1180 "IN/NOT IN 列表不能为空".to_string(),
1181 ));
1182 }
1183
1184 if values.len() > Self::MAX_IN_LIST_SIZE {
1185 return Err(BaseError::ParamInvalid(
1186 "values".to_string(),
1187 format!(
1188 "IN/NOT IN 列表元素数 {} 超过上限 {}",
1189 values.len(),
1190 Self::MAX_IN_LIST_SIZE
1191 ),
1192 ));
1193 }
1194 }
1195 Ok(())
1196 }
1197 }
1198 }
1199
1200 /// 添加一个 OR 逻辑组 (WHERE ... AND (c1 OR c2 OR ...))
1201 ///
1202 /// 组内每个子条件递归校验字段存在性与筛选权限;通过后整组以 `Or` 节点追加到
1203 /// 顶层条件列表,与既有条件以隐式 AND 连接。空组等价于恒假(`1=0`)。
1204 ///
1205 /// 子条件可由 [`WhereCondition`] 直接构造,亦可嵌套 `And`/`Or` 组(深度上限
1206 /// [`Self::MAX_WHERE_DEPTH`])。
1207 ///
1208 /// # 参数
1209 ///
1210 /// - `conditions`:OR 组的子条件列表
1211 ///
1212 /// # 返回值
1213 ///
1214 /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1215 /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1216 ///
1217 /// # 示例
1218 ///
1219 /// ```rust,ignore
1220 /// use yang_base::table::WhereCondition;
1221 /// use serde_json::json;
1222 ///
1223 /// // WHERE status = 'active' AND (age >= 18 OR vip = true)
1224 /// let query = query
1225 /// .where_eq("status", json!("active"))?
1226 /// .where_or(vec![
1227 /// WhereCondition::Gte { field: "age".into(), value: json!(18) },
1228 /// WhereCondition::Eq { field: "vip".into(), value: json!(true) },
1229 /// ])?;
1230 /// ```
1231 pub fn where_or(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1232 let group = WhereCondition::Or { conditions };
1233 // 递归校验整棵子树(含嵌套组)
1234 self.validate_condition_tree(&group, 0)?;
1235 self.query_params.where_conditions.push(group);
1236 Ok(self)
1237 }
1238
1239 /// 添加一个 AND 逻辑组 (WHERE ... AND (c1 AND c2 AND ...))
1240 ///
1241 /// 语义同 [`TableQuery::where_or`],但组内子条件以 AND 连接。主要用于在 OR 组
1242 /// 内部嵌套 AND 子组;顶层多个条件本就隐式 AND,单独使用通常无必要。空组等价
1243 /// 于恒真(`1=1`)。
1244 ///
1245 /// # 参数
1246 ///
1247 /// - `conditions`:AND 组的子条件列表
1248 ///
1249 /// # 返回值
1250 ///
1251 /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1252 /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1253 pub fn where_and(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1254 let group = WhereCondition::And { conditions };
1255 self.validate_condition_tree(&group, 0)?;
1256 self.query_params.where_conditions.push(group);
1257 Ok(self)
1258 }
1259
1260 /// 追加一棵任意 WHERE 条件(叶子或 `And`/`Or` 组),递归校验后并入顶层条件。
1261 ///
1262 /// 这是类型化布尔树([`Filter`](crate::table::Filter))桥接到受保护层的统一入口:
1263 /// 整棵树先经 [`Self::validate_condition_tree`] 递归校验字段存在性、筛选权限与
1264 /// 嵌套深度,通过后作为单个条件追加(与既有条件隐式 AND 连接)。
1265 ///
1266 /// # 参数
1267 ///
1268 /// - `condition`:任意 `WhereCondition`(叶子或逻辑组)
1269 ///
1270 /// # 返回值
1271 ///
1272 /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1273 /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1274 pub fn where_tree(mut self, condition: WhereCondition) -> Result<Self, BaseError> {
1275 self.validate_condition_tree(&condition, 0)?;
1276 self.query_params.where_conditions.push(condition);
1277 Ok(self)
1278 }
1279
1280 /// 获取查询参数的引用
1281 ///
1282 /// 用于测试或调试,获取当前构建的查询参数
1283 ///
1284 /// # 返回值
1285 ///
1286 /// 返回查询参数的引用
1287 #[allow(dead_code)]
1288 pub fn get_query_params(&self) -> &QueryParams {
1289 &self.query_params
1290 }
1291
1292 /// 获取表配置的引用
1293 ///
1294 /// 用于测试或调试,获取表配置
1295 ///
1296 /// # 返回值
1297 ///
1298 /// 返回表配置的引用
1299 #[allow(dead_code)]
1300 pub fn get_table_config(&self) -> &Arc<TableConfig> {
1301 &self.table_config
1302 }
1303
1304 /// 获取用户角色列表的引用
1305 ///
1306 /// 用于测试或调试,获取用户角色列表
1307 ///
1308 /// # 返回值
1309 ///
1310 /// 返回用户角色列表的引用
1311 #[allow(dead_code)]
1312 pub fn get_user_roles(&self) -> &[String] {
1313 &self.user_roles
1314 }
1315
1316 /// 创建仅有表配置、无数据库连接池的查询构建器(测试用)
1317 ///
1318 /// 使用空的用户角色列表,适合访问无权限限制字段的单元测试。
1319 #[cfg(test)]
1320 pub fn new_without_pool(table_config: Arc<TableConfig>) -> Self {
1321 Self::new(table_config, Arc::from(vec![]), None)
1322 }
1323}
1324
1325/// 数据库执行方法(需要启用 `mysql` feature)
1326#[cfg(feature = "mysql")]
1327impl TableQuery {
1328 /// 执行分页查询操作
1329 ///
1330 /// 执行分页查询,包括以下步骤:
1331 /// 1. 执行 COUNT(*) 查询获取总记录数
1332 /// 2. 计算 LIMIT 和 OFFSET
1333 /// 3. 执行数据查询
1334 /// 4. 计算总页数
1335 /// 5. 构建并返回 PaginatedResult
1336 ///
1337 /// # 类型参数
1338 ///
1339 /// - `T`:结果类型,必须实现 `sqlx::FromRow` 和 `Serialize` trait
1340 ///
1341 /// # 返回值
1342 ///
1343 /// - `Ok(PaginatedResult<T>)`:查询成功,返回分页结果
1344 /// - `Err(BaseError)`:查询失败,返回错误
1345 ///
1346 /// # 错误
1347 ///
1348 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1349 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1350 ///
1351 /// # 示例
1352 ///
1353 /// ```rust,ignore
1354 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType, PaginatedResult};
1355 /// use std::sync::Arc;
1356 /// use serde::{Deserialize, Serialize};
1357 ///
1358 /// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
1359 /// struct User {
1360 /// id: i64,
1361 /// name: String,
1362 /// email: String,
1363 /// }
1364 ///
1365 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
1366 /// let table_config = Arc::new(
1367 /// TableConfig::new("users")
1368 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
1369 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
1370 /// .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
1371 /// );
1372 ///
1373 /// let query = TableQuery::new(
1374 /// table_config,
1375 /// vec!["user".to_string()],
1376 /// Some(pool),
1377 /// );
1378 ///
1379 /// // 执行分页查询
1380 /// let result: PaginatedResult<User> = query
1381 /// .select_fields(&["id", "name", "email"])?
1382 /// .where_eq("status", serde_json::json!("active"))?
1383 /// .order_by("created_at", SortOrder::Desc)?
1384 /// .page(1, 20)?
1385 /// .paginate()
1386 /// .await?;
1387 ///
1388 /// println!("总记录数: {}", result.total);
1389 /// println!("当前页: {}/{}", result.page, result.total_pages);
1390 /// println!("数据条数: {}", result.data.len());
1391 /// # Ok(())
1392 /// # }
1393 /// ```
1394 fn with_effective_pagination(self) -> Result<(Self, usize, usize), BaseError> {
1395 let page = self.query_params.page.unwrap_or(1);
1396 let page_size = self
1397 .query_params
1398 .page_size
1399 .unwrap_or(super::query_params::DEFAULT_QUERY_PAGE_SIZE);
1400 let query = self.page(page, page_size)?;
1401
1402 Ok((query, page, page_size))
1403 }
1404
1405 /// 执行分页查询。
1406 ///
1407 /// 未显式设置分页时会使用默认页码和默认每页大小,并确保数据查询带有 `LIMIT/OFFSET`。
1408 pub async fn paginate<T>(self) -> Result<crate::table::PaginatedResult<T>, BaseError>
1409 where
1410 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin + Serialize,
1411 {
1412 // 1. 检查数据库连接池是否存在
1413 let _pool = self
1414 .pool
1415 .as_ref()
1416 .ok_or(BaseError::DatabaseNotInitialized)?;
1417
1418 // 2. 获取分页参数,如果未设置则使用默认值,并写回数据查询
1419 let (query, page, page_size) = self.with_effective_pagination()?;
1420
1421 // 3. 执行 COUNT(*) 查询获取总记录数
1422 let total = query.count_internal().await?;
1423
1424 // 4. 如果总记录数为 0,直接返回空结果
1425 if total == 0 {
1426 return Ok(crate::table::PaginatedResult::empty(page, page_size));
1427 }
1428
1429 // 5. 执行数据查询
1430 let data = query.select().await?;
1431
1432 // 6. 构建并返回 PaginatedResult
1433 Ok(crate::table::PaginatedResult::new(
1434 data, total, page, page_size,
1435 ))
1436 }
1437
1438 /// 执行 COUNT 查询获取总记录数(内部方法,供 paginate 使用)
1439 ///
1440 /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
1441 /// 返回 `usize` 以与 `PaginatedResult::new` 的 `total: usize` 参数直接匹配;
1442 /// 公开接口 `count()` 通过 `as u64` 适配。
1443 ///
1444 /// # 返回值
1445 ///
1446 /// - `Ok(usize)`:查询成功,返回总记录数
1447 /// - `Err(BaseError)`:查询失败,返回错误
1448 ///
1449 /// # 错误
1450 ///
1451 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1452 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1453 async fn count_internal(&self) -> Result<usize, BaseError> {
1454 // 1. 检查数据库连接池是否存在
1455 let pool = self
1456 .pool
1457 .as_ref()
1458 .ok_or(BaseError::DatabaseNotInitialized)?;
1459
1460 // 2. 构建 COUNT SQL 语句
1461 let (sql, params) = self.build_count_sql()?;
1462
1463 // 3. 创建查询
1464 let mut query = sqlx::query_scalar::<_, i64>(&sql);
1465
1466 // 4. 绑定参数
1467 for param in params {
1468 query = Self::bind_count_param(query, ¶m);
1469 }
1470
1471 // 5. 执行查询(计时观测)
1472 let count = Self::timed(
1473 self.slow_threshold,
1474 self.request_id,
1475 &self.table_config.table_name,
1476 "count",
1477 query.fetch_one(pool.as_ref()),
1478 )
1479 .await
1480 .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))?;
1481
1482 Ok(count as usize)
1483 }
1484
1485 /// 执行 COUNT 查询获取总记录数
1486 ///
1487 /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
1488 ///
1489 /// # 返回值
1490 ///
1491 /// - `Ok(u64)`:查询成功,返回总记录数
1492 /// - `Err(BaseError)`:查询失败,返回错误
1493 ///
1494 /// # 错误
1495 ///
1496 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1497 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1498 ///
1499 /// # 示例
1500 ///
1501 /// ```rust,ignore
1502 /// let total = query
1503 /// .where_eq("status", serde_json::json!("active"))?
1504 /// .count()
1505 /// .await?;
1506 ///
1507 /// println!("总记录数: {}", total);
1508 /// ```
1509 pub async fn count(self) -> Result<u64, BaseError> {
1510 self.count_internal().await.map(|n| n as u64)
1511 }
1512
1513 /// 统一拼接 WHERE 子句到 SQL 字符串
1514 ///
1515 /// 集中处理 12 种叶子条件(Eq/Ne/In/NotIn/Like/Gt/Gte/Lt/Lte/Between/IsNull/IsNotNull)
1516 /// 与两种逻辑组(And/Or)的 SQL 拼接:顶层 `where_conditions` 列表仍以隐式 AND 连接
1517 /// (向后兼容),逻辑组递归渲染并用括号包裹。所有字段名通过 `quote_identifier`
1518 /// 反引号转义,防止 SQL 注入。
1519 ///
1520 /// # 参数
1521 ///
1522 /// - `sql`:目标 SQL 字符串(追加模式)
1523 /// - `params`:参数列表(追加模式)
1524 /// - `apply_soft_delete`:是否追加软删过滤(仅读路径)
1525 ///
1526 /// # 返回值
1527 ///
1528 /// - `Ok(())`:拼接成功
1529 /// - `Err(BaseError)`:字段名非法、参数转换失败或嵌套层数超限
1530 fn append_where_to_sql(
1531 &self,
1532 sql: &mut String,
1533 params: &mut Vec<SqlParam>,
1534 apply_soft_delete: bool,
1535 ) -> Result<(), BaseError> {
1536 // 计算是否需要追加软删过滤子句(仅读路径,且未显式 with_trashed)
1537 let has_soft_delete = apply_soft_delete
1538 && !self.include_trashed
1539 && self.table_config.soft_delete_field.is_some();
1540
1541 // 既无 WHERE 条件也无需软删过滤,直接返回
1542 if self.query_params.where_conditions.is_empty() && !has_soft_delete {
1543 return Ok(());
1544 }
1545
1546 sql.push_str(" WHERE ");
1547 let mut first = true;
1548
1549 // 顶层条件以隐式 AND 连接;每个条件递归渲染(组节点自带括号)
1550 for condition in &self.query_params.where_conditions {
1551 if !first {
1552 sql.push_str(" AND ");
1553 }
1554 first = false;
1555 self.render_condition(condition, sql, params, 0)?;
1556 }
1557
1558 // 读路径软删过滤:追加 `软删字段 IS NULL`(与已有条件用 AND 连接)
1559 if has_soft_delete {
1560 if let Some(field) = &self.table_config.soft_delete_field {
1561 let quoted = self.quote_identifier(field)?;
1562 if !first {
1563 sql.push_str(" AND ");
1564 }
1565 sql.push_str(&format!("{} IS NULL", quoted));
1566 }
1567 }
1568
1569 Ok(())
1570 }
1571
1572 /// 递归渲染单个 WHERE 条件到 SQL(叶子直接拼接,And/Or 组括号包裹后递归)。
1573 ///
1574 /// `depth` 从 0 起递增,超过 [`Self::MAX_WHERE_DEPTH`] 返回 `ParamInvalid`
1575 /// 而非 panic,保证受保护层不因深嵌套输入崩溃。
1576 fn render_condition(
1577 &self,
1578 condition: &WhereCondition,
1579 sql: &mut String,
1580 params: &mut Vec<SqlParam>,
1581 depth: usize,
1582 ) -> Result<(), BaseError> {
1583 if depth > Self::MAX_WHERE_DEPTH {
1584 return Err(BaseError::ParamInvalid(
1585 "where".to_string(),
1586 format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1587 ));
1588 }
1589
1590 match condition {
1591 WhereCondition::Eq { field, value } => {
1592 let quoted = self.quote_identifier(field)?;
1593 sql.push_str(&format!("{} = ?", quoted));
1594 params.push(SqlParam::from_json(value)?);
1595 }
1596 WhereCondition::In { field, values } => {
1597 // QRY-2 安全网:渲染期再次校验 IN 列表元素数上限
1598 if values.len() > Self::MAX_IN_LIST_SIZE {
1599 return Err(BaseError::ParamInvalid(
1600 "values".to_string(),
1601 format!(
1602 "IN 列表元素数 {} 超过上限 {}",
1603 values.len(),
1604 Self::MAX_IN_LIST_SIZE
1605 ),
1606 ));
1607 }
1608 let quoted = self.quote_identifier(field)?;
1609 if values.is_empty() {
1610 // 空 IN 集合:等价于恒假,避免拼出非法的 `IN ()`
1611 sql.push_str("1=0");
1612 } else {
1613 let placeholders = vec!["?"; values.len()].join(", ");
1614 sql.push_str(&format!("{} IN ({})", quoted, placeholders));
1615 for value in values {
1616 params.push(SqlParam::from_json(value)?);
1617 }
1618 }
1619 }
1620 WhereCondition::Like { field, pattern } => {
1621 // QRY-1 安全网:渲染期再次校验 LIKE pattern 长度上限
1622 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1623 return Err(BaseError::ParamInvalid(
1624 "pattern".to_string(),
1625 format!(
1626 "LIKE pattern 长度 {} 超过上限 {}",
1627 pattern.len(),
1628 Self::MAX_LIKE_PATTERN_LEN
1629 ),
1630 ));
1631 }
1632 let quoted = self.quote_identifier(field)?;
1633 sql.push_str(&format!("{} LIKE ?", quoted));
1634 params.push(SqlParam::String(pattern.clone()));
1635 }
1636 WhereCondition::Gt { field, value } => {
1637 let quoted = self.quote_identifier(field)?;
1638 sql.push_str(&format!("{} > ?", quoted));
1639 params.push(SqlParam::from_json(value)?);
1640 }
1641 WhereCondition::Gte { field, value } => {
1642 let quoted = self.quote_identifier(field)?;
1643 sql.push_str(&format!("{} >= ?", quoted));
1644 params.push(SqlParam::from_json(value)?);
1645 }
1646 WhereCondition::Lt { field, value } => {
1647 let quoted = self.quote_identifier(field)?;
1648 sql.push_str(&format!("{} < ?", quoted));
1649 params.push(SqlParam::from_json(value)?);
1650 }
1651 WhereCondition::Lte { field, value } => {
1652 let quoted = self.quote_identifier(field)?;
1653 sql.push_str(&format!("{} <= ?", quoted));
1654 params.push(SqlParam::from_json(value)?);
1655 }
1656 WhereCondition::IsNull { field } => {
1657 let quoted = self.quote_identifier(field)?;
1658 sql.push_str(&format!("{} IS NULL", quoted));
1659 }
1660 WhereCondition::IsNotNull { field } => {
1661 let quoted = self.quote_identifier(field)?;
1662 sql.push_str(&format!("{} IS NOT NULL", quoted));
1663 }
1664 WhereCondition::Ne { field, value } => {
1665 let quoted = self.quote_identifier(field)?;
1666 sql.push_str(&format!("{} <> ?", quoted));
1667 params.push(SqlParam::from_json(value)?);
1668 }
1669 WhereCondition::Between { field, lo, hi } => {
1670 let quoted = self.quote_identifier(field)?;
1671 sql.push_str(&format!("{} BETWEEN ? AND ?", quoted));
1672 params.push(SqlParam::from_json(lo)?);
1673 params.push(SqlParam::from_json(hi)?);
1674 }
1675 WhereCondition::NotIn { field, values } => {
1676 // QRY-2 安全网:渲染期再次校验 NOT IN 列表元素数上限
1677 if values.len() > Self::MAX_IN_LIST_SIZE {
1678 return Err(BaseError::ParamInvalid(
1679 "values".to_string(),
1680 format!(
1681 "NOT IN 列表元素数 {} 超过上限 {}",
1682 values.len(),
1683 Self::MAX_IN_LIST_SIZE
1684 ),
1685 ));
1686 }
1687 let quoted = self.quote_identifier(field)?;
1688 if values.is_empty() {
1689 // 空 NOT IN 集合:等价于恒真,不排除任何行
1690 sql.push_str("1=1");
1691 } else {
1692 let placeholders = vec!["?"; values.len()].join(", ");
1693 sql.push_str(&format!("{} NOT IN ({})", quoted, placeholders));
1694 for value in values {
1695 params.push(SqlParam::from_json(value)?);
1696 }
1697 }
1698 }
1699 // 逻辑组:括号包裹,子条件以 AND/OR 连接,递归渲染(深度 +1)
1700 WhereCondition::And { conditions } => {
1701 self.render_group(conditions, " AND ", "1=1", sql, params, depth)?;
1702 }
1703 WhereCondition::Or { conditions } => {
1704 self.render_group(conditions, " OR ", "1=0", sql, params, depth)?;
1705 }
1706 }
1707
1708 Ok(())
1709 }
1710
1711 /// 渲染逻辑组:`(c1 <sep> c2 <sep> ...)`;空组用 `empty_literal` 兜底
1712 /// (And→`1=1` 恒真,Or→`1=0` 恒假),避免拼出非法空括号。
1713 fn render_group(
1714 &self,
1715 conditions: &[WhereCondition],
1716 separator: &str,
1717 empty_literal: &str,
1718 sql: &mut String,
1719 params: &mut Vec<SqlParam>,
1720 depth: usize,
1721 ) -> Result<(), BaseError> {
1722 if conditions.is_empty() {
1723 sql.push_str(empty_literal);
1724 return Ok(());
1725 }
1726
1727 sql.push('(');
1728 let mut first = true;
1729 for cond in conditions {
1730 if !first {
1731 sql.push_str(separator);
1732 }
1733 first = false;
1734 self.render_condition(cond, sql, params, depth + 1)?;
1735 }
1736 sql.push(')');
1737 Ok(())
1738 }
1739
1740 /// 构建 COUNT SQL 语句
1741 ///
1742 /// # 返回值
1743 ///
1744 /// 返回 (SQL 语句, 参数列表) 元组
1745 ///
1746 /// # 错误
1747 ///
1748 /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
1749 fn build_count_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
1750 let mut sql = format!("SELECT COUNT(*) FROM {}", self.quoted_table_name()?);
1751 let mut params = Vec::new();
1752
1753 // 通过统一方法拼接 WHERE 子句(读路径,应用软删过滤)
1754 self.append_where_to_sql(&mut sql, &mut params, true)?;
1755
1756 Ok((sql, params))
1757 }
1758
1759 /// 绑定参数到 COUNT 查询
1760 ///
1761 /// # 参数
1762 ///
1763 /// - `query`:sqlx 查询对象
1764 /// - `param`:SQL 参数值
1765 ///
1766 /// # 返回值
1767 ///
1768 /// 绑定参数后的查询对象
1769 fn bind_count_param<'q>(
1770 query: sqlx::query::QueryScalar<'q, sqlx::MySql, i64, sqlx::mysql::MySqlArguments>,
1771 param: &SqlParam,
1772 ) -> sqlx::query::QueryScalar<'q, sqlx::MySql, i64, sqlx::mysql::MySqlArguments> {
1773 match param {
1774 SqlParam::Null => query.bind(Option::<i32>::None),
1775 SqlParam::Bool(b) => query.bind(*b),
1776 SqlParam::Int(i) => query.bind(*i),
1777 SqlParam::Uint(u) => query.bind(*u),
1778 SqlParam::Float(f) => query.bind(*f),
1779 SqlParam::String(s) => query.bind(s.clone()),
1780 SqlParam::DateTime(dt) => query.bind(*dt),
1781 SqlParam::Bytes(b) => query.bind(b.clone()),
1782 SqlParam::Json(j) => query.bind(j.clone()),
1783 }
1784 }
1785
1786 /// 执行 SELECT 查询操作
1787 ///
1788 /// 使用 sqlx 构建 SELECT 语句,应用已配置的字段选择、WHERE 条件和排序规则,
1789 /// 执行查询并将结果反序列化为指定的泛型类型 T。
1790 ///
1791 /// # 类型参数
1792 ///
1793 /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
1794 ///
1795 /// # 返回值
1796 ///
1797 /// - `Ok(Vec<T>)`:查询成功,返回结果列表
1798 /// - `Err(BaseError)`:查询失败,返回错误
1799 ///
1800 /// # 错误
1801 ///
1802 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1803 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1804 ///
1805 /// # 示例
1806 ///
1807 /// ```rust,ignore
1808 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
1809 /// use std::sync::Arc;
1810 /// use serde::{Deserialize, Serialize};
1811 ///
1812 /// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
1813 /// struct User {
1814 /// id: i64,
1815 /// name: String,
1816 /// email: String,
1817 /// }
1818 ///
1819 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
1820 /// let table_config = Arc::new(
1821 /// TableConfig::new("users")
1822 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
1823 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
1824 /// .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
1825 /// );
1826 ///
1827 /// let query = TableQuery::new(
1828 /// table_config,
1829 /// vec!["user".to_string()],
1830 /// Some(pool),
1831 /// );
1832 ///
1833 /// // 执行查询
1834 /// let users: Vec<User> = query
1835 /// .select_fields(&["id", "name", "email"])?
1836 /// .where_eq("status", serde_json::json!("active"))?
1837 /// .order_by("created_at", SortOrder::Desc)?
1838 /// .select()
1839 /// .await?;
1840 ///
1841 /// println!("找到 {} 个用户", users.len());
1842 /// # Ok(())
1843 /// # }
1844 /// ```
1845 pub async fn select<T>(self) -> Result<Vec<T>, BaseError>
1846 where
1847 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1848 {
1849 // 1. 检查数据库连接池是否存在
1850 let pool = self
1851 .pool
1852 .as_ref()
1853 .ok_or(BaseError::DatabaseNotInitialized)?;
1854
1855 // 2. 构建 SQL 语句
1856 let (sql, params) = self.build_select_sql(None)?;
1857
1858 // 3. 在连接池上执行查询(计时观测,慢查询超阈值 warn)
1859 Self::timed(
1860 self.slow_threshold,
1861 self.request_id,
1862 &self.table_config.table_name,
1863 "select",
1864 Self::run_fetch_all(pool.as_ref(), &sql, ¶ms),
1865 )
1866 .await
1867 }
1868
1869 /// 在事务中执行 SELECT 查询并返回多条记录
1870 ///
1871 /// 与 [`TableQuery::select`] 完全一致的建句与权限/软删逻辑,但在调用方提供的
1872 /// `yang_db::Transaction` 内执行,使「读-改-写」场景的读取与后续写入处于同一
1873 /// 事务、看到一致快照。
1874 ///
1875 /// # 参数
1876 ///
1877 /// - `tx`:由 [`ActionContext::begin_transaction`](crate::action::ActionContext::begin_transaction)
1878 /// 或 [`GlobalDatabase::transaction`](crate::database::GlobalDatabase::transaction) 取得的活动事务
1879 ///
1880 /// # 错误
1881 ///
1882 /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚,连接不可用
1883 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1884 pub async fn select_in_tx<T>(self, tx: &mut yang_db::Transaction) -> Result<Vec<T>, BaseError>
1885 where
1886 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1887 {
1888 // 构建 SQL(与普通路径一致,含字段权限/软删过滤)
1889 let (sql, params) = self.build_select_sql(None)?;
1890
1891 // 借出事务底层连接执行;事务已结束则返回错误而非 panic
1892 let executor = tx.executor().ok_or_else(|| {
1893 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
1894 "事务已提交或回滚".to_string(),
1895 ))
1896 })?;
1897
1898 Self::timed(
1899 self.slow_threshold,
1900 self.request_id,
1901 &self.table_config.table_name,
1902 "select_in_tx",
1903 Self::run_fetch_all(executor, &sql, ¶ms),
1904 )
1905 .await
1906 }
1907
1908 /// 构建 SELECT SQL 语句
1909 ///
1910 /// # 返回值
1911 ///
1912 /// 返回 (SQL 语句, 参数列表) 元组
1913 ///
1914 /// # 错误
1915 ///
1916 /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
1917 fn build_select_sql(
1918 &self,
1919 hard_limit: Option<usize>,
1920 ) -> Result<(String, Vec<SqlParam>), BaseError> {
1921 let mut sql = String::from("SELECT ");
1922 let mut params = Vec::new();
1923
1924 // 1. 字段列表(通过 quote_identifier 转义字段名)
1925 if let Some(fields) = &self.query_params.fields {
1926 if fields.is_empty() {
1927 self.validate_all_fields_readable()?;
1928 sql.push('*');
1929 } else {
1930 // 对每个字段名进行反引号转义
1931 let quoted_fields: Result<Vec<String>, BaseError> = fields
1932 .iter()
1933 .map(|f| {
1934 self.validate_read_field(f)?;
1935 self.quote_identifier(f)
1936 })
1937 .collect();
1938 sql.push_str("ed_fields?.join(", "));
1939 }
1940 } else {
1941 self.validate_all_fields_readable()?;
1942 sql.push('*');
1943 }
1944
1945 // 2. FROM 子句(表名走统一转义路径)
1946 sql.push_str(&format!(" FROM {}", self.quoted_table_name()?));
1947
1948 // 3. 通过统一方法拼接 WHERE 子句(读路径,应用软删过滤)
1949 self.append_where_to_sql(&mut sql, &mut params, true)?;
1950
1951 // 4. ORDER BY 子句:显式 order_by 优先,否则回退到表配置的 default_order
1952 let order_source = if !self.query_params.order_by.is_empty() {
1953 Some(&self.query_params.order_by)
1954 } else if !self.table_config.default_order.is_empty() {
1955 Some(&self.table_config.default_order)
1956 } else {
1957 None
1958 };
1959 if let Some(orders) = order_source {
1960 sql.push_str(" ORDER BY ");
1961 let order_clauses: Result<Vec<String>, BaseError> = orders
1962 .iter()
1963 .map(|(field, order)| {
1964 self.validate_order_field(field)?;
1965 let direction = match order {
1966 SortOrder::Asc => "ASC",
1967 SortOrder::Desc => "DESC",
1968 };
1969 self.quote_identifier(field)
1970 .map(|quoted| format!("{} {}", quoted, direction))
1971 })
1972 .collect();
1973 sql.push_str(&order_clauses?.join(", "));
1974 }
1975
1976 // 5. LIMIT 和 OFFSET 子句(分页与 hard_limit 互斥,避免拼出两段 LIMIT)
1977 if let (Some(page), Some(page_size)) = (self.query_params.page, self.query_params.page_size)
1978 {
1979 // 使用 saturating_sub 防止 page==0 时 usize 下溢(纵深防御,
1980 // 主校验在 page() 入口;直接构造 query_params 的调用方也安全)
1981 let offset = page.saturating_sub(1).saturating_mul(page_size);
1982 sql.push_str(&format!(" LIMIT {} OFFSET {}", page_size, offset));
1983 } else if let Some(limit) = hard_limit {
1984 // 无分页时应用硬上限(如 fetch_optional 仅需 1 行)
1985 sql.push_str(&format!(" LIMIT {}", limit));
1986 }
1987
1988 Ok((sql, params))
1989 }
1990
1991 /// 绑定参数到查询
1992 ///
1993 /// # 参数
1994 ///
1995 /// - `query`:sqlx 查询对象
1996 /// - `param`:SQL 参数值
1997 ///
1998 /// # 返回值
1999 ///
2000 /// 绑定参数后的查询对象
2001 fn bind_param<'q, T>(
2002 query: sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>,
2003 param: &SqlParam,
2004 ) -> sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>
2005 where
2006 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
2007 {
2008 match param {
2009 SqlParam::Null => query.bind(Option::<i32>::None),
2010 SqlParam::Bool(b) => query.bind(*b),
2011 SqlParam::Int(i) => query.bind(*i),
2012 SqlParam::Uint(u) => query.bind(*u),
2013 SqlParam::Float(f) => query.bind(*f),
2014 SqlParam::String(s) => query.bind(s.clone()),
2015 SqlParam::DateTime(dt) => query.bind(*dt),
2016 SqlParam::Bytes(b) => query.bind(b.clone()),
2017 SqlParam::Json(j) => query.bind(j.clone()),
2018 }
2019 }
2020
2021 /// 执行查询并返回可选的单条记录
2022 ///
2023 /// 执行 SELECT 查询,返回第一条匹配记录,如果没有匹配记录则返回 None。
2024 /// 通常与 `where_eq` 等条件方法配合使用,用于按主键查询单条记录。
2025 ///
2026 /// # 类型参数
2027 ///
2028 /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
2029 ///
2030 /// # 返回值
2031 ///
2032 /// - `Ok(Some(T))`:找到匹配记录
2033 /// - `Ok(None)`:没有匹配记录
2034 /// - `Err(BaseError)`:查询失败
2035 ///
2036 /// # 错误
2037 ///
2038 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2039 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
2040 ///
2041 /// # 示例
2042 ///
2043 /// ```rust,ignore
2044 /// use yang_base::table::DynamicRow;
2045 ///
2046 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2047 /// // 按主键查询单条记录
2048 /// let row: Option<DynamicRow> = query
2049 /// .where_eq("id", serde_json::json!(1))?
2050 /// .fetch_optional()
2051 /// .await?;
2052 ///
2053 /// match row {
2054 /// Some(r) => println!("找到记录: {:?}", r.columns),
2055 /// None => println!("记录不存在"),
2056 /// }
2057 /// # Ok(())
2058 /// # }
2059 /// ```
2060 pub async fn fetch_optional<T>(self) -> Result<Option<T>, BaseError>
2061 where
2062 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
2063 {
2064 // 1. 检查数据库连接池是否存在
2065 let pool = self
2066 .pool
2067 .as_ref()
2068 .ok_or(BaseError::DatabaseNotInitialized)?;
2069
2070 // 2. 构建 SQL 语句(限制返回 1 条记录)
2071 let (sql, params) = self.build_select_sql(Some(1))?;
2072
2073 // 3. 创建查询
2074 let mut query = sqlx::query_as::<_, T>(&sql);
2075
2076 // 4. 绑定参数
2077 for param in params {
2078 query = Self::bind_param(query, ¶m);
2079 }
2080
2081 // 5. 执行查询,返回可选结果(计时观测)
2082 let result = Self::timed(
2083 self.slow_threshold,
2084 self.request_id,
2085 &self.table_config.table_name,
2086 "fetch_optional",
2087 query.fetch_optional(pool.as_ref()),
2088 )
2089 .await
2090 .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))?;
2091
2092 Ok(result)
2093 }
2094
2095 /// 执行 INSERT 操作
2096 ///
2097 /// 插入数据到表中,包括以下步骤:
2098 /// 1. 验证所有字段值的合法性(使用 FieldConfig::validate)
2099 /// 2. 检查用户是否有字段的写入权限
2100 /// 3. 构建 INSERT SQL 语句
2101 /// 4. 执行插入操作
2102 /// 5. 返回影响行数
2103 ///
2104 /// # 参数
2105 ///
2106 /// - `data`:要插入的数据,格式为 HashMap<String, Value>
2107 ///
2108 /// # 返回值
2109 ///
2110 /// - `Ok(u64)`:插入成功,返回影响行数(通常为 1)
2111 /// - `Err(BaseError)`:插入失败,返回错误
2112 ///
2113 /// # 错误
2114 ///
2115 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2116 /// - `BaseError::FieldRequired`:必填字段缺失
2117 /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2118 /// - `BaseError::ValidationFailed`:字段值验证失败
2119 /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2120 ///
2121 /// # 示例
2122 ///
2123 /// ```rust,ignore
2124 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2125 /// use std::sync::Arc;
2126 /// use std::collections::HashMap;
2127 /// use serde_json::json;
2128 ///
2129 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2130 /// let table_config = Arc::new(
2131 /// TableConfig::new("users")
2132 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2133 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 }).required(true)).expect("有效字段配置应注册成功")
2134 /// .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
2135 /// );
2136 ///
2137 /// let query = TableQuery::new(
2138 /// table_config,
2139 /// vec!["user".to_string()],
2140 /// Some(pool),
2141 /// );
2142 ///
2143 /// // 准备插入数据
2144 /// let mut data = HashMap::new();
2145 /// data.insert("name".to_string(), json!("张三"));
2146 /// data.insert("email".to_string(), json!("zhangsan@example.com"));
2147 ///
2148 /// // 执行插入
2149 /// let affected = query.insert(data).await?;
2150 /// println!("插入成功,影响行数: {}", affected);
2151 /// # Ok(())
2152 /// # }
2153 /// ```
2154 pub async fn insert(
2155 self,
2156 data: std::collections::HashMap<String, Value>,
2157 ) -> Result<u64, BaseError> {
2158 // 1. 检查数据库连接池是否存在
2159 let pool = self
2160 .pool
2161 .as_ref()
2162 .ok_or(BaseError::DatabaseNotInitialized)?;
2163
2164 // 2. 填充默认值/时间戳并校验(顺序:写权限→填充默认值→必填/类型校验)
2165 let data = self.prepare_and_validate_insert(data)?;
2166
2167 // 3. 构建 INSERT SQL 语句
2168 let (sql, params) = self.build_insert_sql(&data)?;
2169
2170 // 4. 在连接池上执行插入(计时观测)
2171 let result = Self::timed(
2172 self.slow_threshold,
2173 self.request_id,
2174 &self.table_config.table_name,
2175 "insert",
2176 Self::run_execute(pool.as_ref(), &sql, ¶ms),
2177 )
2178 .await?;
2179
2180 Ok(result.rows_affected())
2181 }
2182
2183 /// 在事务中执行 INSERT 操作
2184 ///
2185 /// 与 [`TableQuery::insert`] 完全一致的写权限校验/默认值填充/时间戳/必填校验
2186 /// 流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
2187 ///
2188 /// # 错误
2189 ///
2190 /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2191 /// - 其余同 [`TableQuery::insert`]
2192 pub async fn insert_in_tx(
2193 self,
2194 tx: &mut yang_db::Transaction,
2195 data: std::collections::HashMap<String, Value>,
2196 ) -> Result<u64, BaseError> {
2197 let data = self.prepare_and_validate_insert(data)?;
2198 let (sql, params) = self.build_insert_sql(&data)?;
2199
2200 let executor = tx.executor().ok_or_else(|| {
2201 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2202 "事务已提交或回滚".to_string(),
2203 ))
2204 })?;
2205
2206 let result = Self::timed(
2207 self.slow_threshold,
2208 self.request_id,
2209 &self.table_config.table_name,
2210 "insert_in_tx",
2211 Self::run_execute(executor, &sql, ¶ms),
2212 )
2213 .await?;
2214 Ok(result.rows_affected())
2215 }
2216
2217 /// 执行 INSERT 操作并返回自增主键
2218 ///
2219 /// 与 [`TableQuery::insert`] 完全一致的校验与拼 SQL 流程,但额外返回本次
2220 /// INSERT 产生的自增主键值(`last_insert_id`),便于调用方拿到新建记录 ID。
2221 ///
2222 /// # 参数
2223 ///
2224 /// - `data`:要插入的数据
2225 ///
2226 /// # 返回值
2227 ///
2228 /// - `Ok((affected, id))`:插入成功,返回 (影响行数, 自增主键值)。
2229 /// 表无自增列时 `id` 为 0。
2230 /// - `Err(BaseError)`:插入失败
2231 ///
2232 /// # 错误
2233 ///
2234 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2235 /// - `BaseError::FieldRequired`:必填字段缺失
2236 /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2237 /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2238 pub async fn insert_returning_id(
2239 self,
2240 data: std::collections::HashMap<String, Value>,
2241 ) -> Result<(u64, u64), BaseError> {
2242 let pool = self
2243 .pool
2244 .as_ref()
2245 .ok_or(BaseError::DatabaseNotInitialized)?;
2246
2247 let data = self.prepare_and_validate_insert(data)?;
2248 let (sql, params) = self.build_insert_sql(&data)?;
2249
2250 let result = Self::timed(
2251 self.slow_threshold,
2252 self.request_id,
2253 &self.table_config.table_name,
2254 "insert_returning_id",
2255 Self::run_execute(pool.as_ref(), &sql, ¶ms),
2256 )
2257 .await?;
2258
2259 Ok((result.rows_affected(), result.last_insert_id()))
2260 }
2261
2262 /// 在事务中执行 INSERT 并返回自增主键
2263 ///
2264 /// 与 [`TableQuery::insert_returning_id`] 一致,但在事务内执行。批量写入或
2265 /// 「插入父行→用其主键插入子行」等需要拿到新 ID 再继续的原子场景使用。
2266 pub async fn insert_returning_id_in_tx(
2267 self,
2268 tx: &mut yang_db::Transaction,
2269 data: std::collections::HashMap<String, Value>,
2270 ) -> Result<(u64, u64), BaseError> {
2271 let data = self.prepare_and_validate_insert(data)?;
2272 let (sql, params) = self.build_insert_sql(&data)?;
2273
2274 let executor = tx.executor().ok_or_else(|| {
2275 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2276 "事务已提交或回滚".to_string(),
2277 ))
2278 })?;
2279
2280 let result = Self::timed(
2281 self.slow_threshold,
2282 self.request_id,
2283 &self.table_config.table_name,
2284 "insert_returning_id_in_tx",
2285 Self::run_execute(executor, &sql, ¶ms),
2286 )
2287 .await?;
2288 Ok((result.rows_affected(), result.last_insert_id()))
2289 }
2290
2291 /// 填充默认值/时间戳并验证插入数据
2292 ///
2293 /// 处理顺序(修复 required+default 字段被误报 FieldRequired 的问题):
2294 /// 1. 写权限校验:对调用方显式提供了非 null 值、但用户无写权限的字段拒绝
2295 /// 2. 填充默认值:data 中缺失或为 null 且配置了 `default_value` 的字段补默认值
2296 /// 3. 填充时间戳:`timestamp_fields` 配置且列存在、调用方未提供时,写入当前时间
2297 /// 4. 必填/类型/验证器校验:在补齐后的数据上执行
2298 ///
2299 /// # 参数
2300 ///
2301 /// - `data`:调用方提供的原始插入数据
2302 ///
2303 /// # 返回值
2304 ///
2305 /// - `Ok(HashMap)`:补齐默认值与时间戳后的最终插入数据
2306 /// - `Err(BaseError)`:权限或校验失败
2307 fn prepare_and_validate_insert(
2308 &self,
2309 data: std::collections::HashMap<String, Value>,
2310 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
2311 let mut prepared = data;
2312
2313 // 1. 写权限校验:仅拦截"无权限却显式赋了非 null 值"的字段
2314 for (field_name, field_config) in &self.table_config.fields {
2315 if !field_config.permissions.can_write(&self.user_roles_set) {
2316 if let Some(v) = prepared.get(field_name) {
2317 if !v.is_null() {
2318 return Err(BaseError::FieldPermissionDenied(
2319 self.table_config.table_name.clone(),
2320 field_name.clone(),
2321 "用户无写入权限".to_string(),
2322 ));
2323 }
2324 }
2325 }
2326 }
2327
2328 // 2. 填充默认值(缺失或为 null 且配置了 default_value)
2329 for (field_name, field_config) in &self.table_config.fields {
2330 if let Some(default) = &field_config.default_value {
2331 let missing = prepared
2332 .get(field_name)
2333 .map(|v| v.is_null())
2334 .unwrap_or(true);
2335 if missing {
2336 prepared.insert(field_name.clone(), default.clone());
2337 }
2338 }
2339 }
2340
2341 // 3. 填充创建/更新时间戳(列存在且调用方未提供时)
2342 if let Some(ts) = &self.table_config.timestamp_fields {
2343 let now = chrono::Utc::now().timestamp();
2344 for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
2345 if self.table_config.fields.contains_key(ts_field) {
2346 let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
2347 if missing {
2348 prepared.insert(ts_field.clone(), Value::Number(now.into()));
2349 }
2350 }
2351 }
2352 }
2353
2354 // 4. 在补齐后的数据上执行必填/类型/验证器校验
2355 for (field_name, field_config) in &self.table_config.fields {
2356 if !field_config.permissions.can_write(&self.user_roles_set) {
2357 continue;
2358 }
2359 let value = prepared.get(field_name).unwrap_or(&Value::Null);
2360 field_config.validate(value)?;
2361 }
2362
2363 Ok(prepared)
2364 }
2365
2366 /// 构建 INSERT SQL 语句
2367 ///
2368 /// # 参数
2369 ///
2370 /// - `data`:要插入的数据
2371 ///
2372 /// # 返回值
2373 ///
2374 /// 返回 (SQL 语句, 参数列表) 元组
2375 ///
2376 /// # 错误
2377 ///
2378 /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2379 fn build_insert_sql(
2380 &self,
2381 data: &std::collections::HashMap<String, Value>,
2382 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2383 let mut fields = Vec::with_capacity(data.len());
2384 let mut placeholders = Vec::with_capacity(data.len());
2385 let mut params = Vec::with_capacity(data.len());
2386
2387 // 遍历数据,构建字段列表和参数列表
2388 for (field_name, value) in data {
2389 // 检查字段是否存在于表配置中
2390 if !self.table_config.fields.contains_key(field_name) {
2391 return Err(BaseError::FieldNotFound(
2392 self.table_config.table_name.clone(),
2393 field_name.clone(),
2394 ));
2395 }
2396
2397 // 写入权限已在 validate_insert_data 集中校验(无权限且赋非 null 值会
2398 // 直接报错),此处不再二次跳过,保证 data 中所有字段一致入列。
2399
2400 // 对字段名进行反引号转义,防止 SQL 注入
2401 let quoted = self.quote_identifier(field_name)?;
2402 fields.push(quoted);
2403 placeholders.push("?".to_string());
2404 params.push(SqlParam::from_json(value)?);
2405 }
2406
2407 // 构建 SQL 语句(表名走统一转义路径)
2408 let sql = format!(
2409 "INSERT INTO {} ({}) VALUES ({})",
2410 self.quoted_table_name()?,
2411 fields.join(", "),
2412 placeholders.join(", ")
2413 );
2414
2415 Ok((sql, params))
2416 }
2417
2418 /// 执行 UPDATE 操作
2419 ///
2420 /// 更新表中的数据,包括以下步骤:
2421 /// 1. 验证所有字段值的合法性(使用 FieldConfig::validate)
2422 /// 2. 检查用户是否有字段的写入权限
2423 /// 3. 构建 UPDATE SQL 语句
2424 /// 4. 应用已配置的 WHERE 条件
2425 /// 5. 执行更新操作
2426 /// 6. 返回影响行数
2427 ///
2428 /// # 参数
2429 ///
2430 /// - `data`:要更新的数据,格式为 HashMap<String, Value>
2431 ///
2432 /// # 返回值
2433 ///
2434 /// - `Ok(u64)`:更新成功,返回影响行数
2435 /// - `Err(BaseError)`:更新失败,返回错误
2436 ///
2437 /// # 错误
2438 ///
2439 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2440 /// - `BaseError::FieldNotFound`:字段不存在
2441 /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2442 /// - `BaseError::ValidationFailed`:字段值验证失败
2443 /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2444 ///
2445 /// # 示例
2446 ///
2447 /// ```rust,ignore
2448 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2449 /// use std::sync::Arc;
2450 /// use std::collections::HashMap;
2451 /// use serde_json::json;
2452 ///
2453 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2454 /// let table_config = Arc::new(
2455 /// TableConfig::new("users")
2456 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2457 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
2458 /// .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
2459 /// );
2460 ///
2461 /// let query = TableQuery::new(
2462 /// table_config,
2463 /// vec!["user".to_string()],
2464 /// Some(pool),
2465 /// );
2466 ///
2467 /// // 准备更新数据
2468 /// let mut data = HashMap::new();
2469 /// data.insert("name".to_string(), json!("李四"));
2470 /// data.insert("email".to_string(), json!("lisi@example.com"));
2471 ///
2472 /// // 执行更新(需要先设置 WHERE 条件)
2473 /// let affected = query
2474 /// .where_eq("id", json!(1))?
2475 /// .update(data)
2476 /// .await?;
2477 /// println!("更新成功,影响行数: {}", affected);
2478 /// # Ok(())
2479 /// # }
2480 /// ```
2481 pub async fn update(
2482 self,
2483 data: std::collections::HashMap<String, Value>,
2484 ) -> Result<u64, BaseError> {
2485 // 1. 检查数据库连接池是否存在
2486 let pool = self
2487 .pool
2488 .as_ref()
2489 .ok_or(BaseError::DatabaseNotInitialized)?;
2490
2491 // 2. 验证所有字段值的合法性和权限
2492 self.validate_update_data(&data)?;
2493
2494 // 3. 构建 UPDATE SQL 语句
2495 let (sql, params) = self.build_update_sql(&data)?;
2496
2497 // 4. 在连接池上执行更新(计时观测)
2498 let result = Self::timed(
2499 self.slow_threshold,
2500 self.request_id,
2501 &self.table_config.table_name,
2502 "update",
2503 Self::run_execute(pool.as_ref(), &sql, ¶ms),
2504 )
2505 .await?;
2506
2507 Ok(result.rows_affected())
2508 }
2509
2510 /// 在事务中执行 UPDATE 操作
2511 ///
2512 /// 与 [`TableQuery::update`] 一致的字段校验/权限/WHERE 守卫/自动 `updated_at`
2513 /// 逻辑,但在事务内执行。
2514 ///
2515 /// # 错误
2516 ///
2517 /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2518 /// - 其余同 [`TableQuery::update`]
2519 pub async fn update_in_tx(
2520 self,
2521 tx: &mut yang_db::Transaction,
2522 data: std::collections::HashMap<String, Value>,
2523 ) -> Result<u64, BaseError> {
2524 self.validate_update_data(&data)?;
2525 let (sql, params) = self.build_update_sql(&data)?;
2526
2527 let executor = tx.executor().ok_or_else(|| {
2528 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2529 "事务已提交或回滚".to_string(),
2530 ))
2531 })?;
2532
2533 let result = Self::timed(
2534 self.slow_threshold,
2535 self.request_id,
2536 &self.table_config.table_name,
2537 "update_in_tx",
2538 Self::run_execute(executor, &sql, ¶ms),
2539 )
2540 .await?;
2541 Ok(result.rows_affected())
2542 }
2543
2544 /// 验证更新数据
2545 ///
2546 /// 验证所有要更新的字段值的合法性和用户权限
2547 ///
2548 /// # 参数
2549 ///
2550 /// - `data`:要更新的数据
2551 ///
2552 /// # 返回值
2553 ///
2554 /// - `Ok(())`:验证通过
2555 /// - `Err(BaseError)`:验证失败
2556 ///
2557 /// # 错误
2558 ///
2559 /// - `BaseError::FieldNotFound`:字段不存在
2560 /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2561 /// - `BaseError::ValidationFailed`:字段值验证失败
2562 #[cfg(test)]
2563 pub fn validate_update_data(
2564 &self,
2565 data: &std::collections::HashMap<String, Value>,
2566 ) -> Result<(), BaseError> {
2567 self.validate_update_data_impl(data)
2568 }
2569
2570 /// 验证更新数据(内部实现)
2571 #[cfg(not(test))]
2572 fn validate_update_data(
2573 &self,
2574 data: &std::collections::HashMap<String, Value>,
2575 ) -> Result<(), BaseError> {
2576 self.validate_update_data_impl(data)
2577 }
2578
2579 /// 验证更新数据的实际实现
2580 fn validate_update_data_impl(
2581 &self,
2582 data: &std::collections::HashMap<String, Value>,
2583 ) -> Result<(), BaseError> {
2584 // 只验证提供的字段(与 INSERT 不同,UPDATE 不需要验证所有字段)
2585 for (field_name, value) in data {
2586 // 1. 检查字段是否存在于表配置中
2587 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
2588 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
2589 })?;
2590
2591 // 2. 检查用户是否有写入权限
2592 if !field_config.permissions.can_write(&self.user_roles_set) {
2593 return Err(BaseError::FieldPermissionDenied(
2594 self.table_config.table_name.clone(),
2595 field_name.clone(),
2596 "用户无写入权限".to_string(),
2597 ));
2598 }
2599
2600 // 3. 验证字段值(包括类型检查和验证器检查)
2601 // 注意:UPDATE 操作中,字段不一定是必填的,因为我们只更新部分字段
2602 // 所以这里不检查 required 约束,只检查类型和验证器
2603 field_config.validate(value)?;
2604 }
2605
2606 Ok(())
2607 }
2608
2609 /// 构建 UPDATE SQL 语句
2610 ///
2611 /// # 参数
2612 ///
2613 /// - `data`:要更新的数据
2614 ///
2615 /// # 返回值
2616 ///
2617 /// 返回 (SQL 语句, 参数列表) 元组
2618 ///
2619 /// # 错误
2620 ///
2621 /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2622 #[cfg(test)]
2623 #[allow(private_interfaces)]
2624 pub fn build_update_sql(
2625 &self,
2626 data: &std::collections::HashMap<String, Value>,
2627 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2628 self.build_update_sql_impl(data)
2629 }
2630
2631 /// 构建 UPDATE SQL 语句(内部实现)
2632 #[cfg(not(test))]
2633 fn build_update_sql(
2634 &self,
2635 data: &std::collections::HashMap<String, Value>,
2636 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2637 self.build_update_sql_impl(data)
2638 }
2639
2640 /// 构建 UPDATE SQL 语句的实际实现
2641 fn build_update_sql_impl(
2642 &self,
2643 data: &std::collections::HashMap<String, Value>,
2644 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2645 // 0. 拒绝空更新:用户未提供任何可更新字段
2646 if data.is_empty() {
2647 return Err(BaseError::ParamInvalid(
2648 "data".to_string(),
2649 "无可更新字段".to_string(),
2650 ));
2651 }
2652
2653 // 1. 自动刷新 updated_at(若已配置且列存在于表),仅在需要时克隆
2654 let need_timestamp = self
2655 .table_config
2656 .timestamp_fields
2657 .as_ref()
2658 .and_then(|ts| ts.updated_at.as_ref())
2659 .is_some_and(|updated_at| self.table_config.fields.contains_key(updated_at));
2660
2661 let mut owned_data;
2662 let working: &std::collections::HashMap<String, Value> = if need_timestamp {
2663 owned_data = data.clone();
2664 // SAFETY: need_timestamp 为 true 意味着 timestamp_fields 和 updated_at 一定存在
2665 let ts = self.table_config.timestamp_fields.as_ref().unwrap();
2666 let updated_at = ts.updated_at.as_ref().unwrap();
2667 let now = chrono::Utc::now().timestamp();
2668 owned_data.insert(updated_at.clone(), Value::Number(now.into()));
2669 &owned_data
2670 } else {
2671 data
2672 };
2673
2674 let mut set_clauses = Vec::with_capacity(working.len());
2675 let mut params = Vec::with_capacity(working.len());
2676
2677 // 2. 构建 SET 子句(通过 quote_identifier 转义字段名)
2678 for (field_name, value) in working {
2679 // 检查字段是否存在于表配置中
2680 if !self.table_config.fields.contains_key(field_name) {
2681 return Err(BaseError::FieldNotFound(
2682 self.table_config.table_name.clone(),
2683 field_name.clone(),
2684 ));
2685 }
2686
2687 // 对字段名进行反引号转义
2688 let quoted = self.quote_identifier(field_name)?;
2689 set_clauses.push(format!("{} = ?", quoted));
2690 params.push(SqlParam::from_json(value)?);
2691 }
2692
2693 // 3. 构建基本 UPDATE 语句(表名走统一转义路径)
2694 let mut sql = format!(
2695 "UPDATE {} SET {}",
2696 self.quoted_table_name()?,
2697 set_clauses.join(", ")
2698 );
2699
2700 // 4. WHERE 守卫:无 WHERE 且未显式放行全表,拒绝全表更新
2701 if self.query_params.where_conditions.is_empty() && !self.allow_full_table {
2702 return Err(BaseError::MissingWhereClause("UPDATE".to_string()));
2703 }
2704
2705 // 5. 通过统一方法拼接 WHERE 子句(写路径,不应用软删过滤)
2706 self.append_where_to_sql(&mut sql, &mut params, false)?;
2707
2708 Ok((sql, params))
2709 }
2710
2711 /// 执行 DELETE 操作
2712 ///
2713 /// 删除表中的数据,支持软删除和物理删除两种模式:
2714 /// 1. 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
2715 /// 2. 如果未配置软删除字段,执行物理删除
2716 /// 3. 应用已配置的 WHERE 条件
2717 /// 4. 返回影响行数
2718 ///
2719 /// # 返回值
2720 ///
2721 /// - `Ok(u64)`:删除成功,返回影响行数
2722 /// - `Err(BaseError)`:删除失败,返回错误
2723 ///
2724 /// # 错误
2725 ///
2726 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2727 /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2728 ///
2729 /// # 示例
2730 ///
2731 /// ```rust,ignore
2732 /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2733 /// use std::sync::Arc;
2734 /// use serde_json::json;
2735 ///
2736 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2737 /// // 配置了软删除字段的表
2738 /// let table_config = Arc::new(
2739 /// TableConfig::new("users")
2740 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2741 /// .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
2742 /// .field(FieldConfig::new("deleted_at", FieldType::BigInt)).expect("有效字段配置应注册成功")
2743 /// .soft_delete_field("deleted_at") // 配置软删除字段
2744 /// );
2745 ///
2746 /// let query = TableQuery::new(
2747 /// table_config,
2748 /// vec!["admin".to_string()],
2749 /// Some(pool),
2750 /// );
2751 ///
2752 /// // 执行软删除(实际上是 UPDATE deleted_at = <timestamp>)
2753 /// let affected = query
2754 /// .where_eq("id", json!(1))?
2755 /// .delete()
2756 /// .await?;
2757 /// println!("删除成功,影响行数: {}", affected);
2758 ///
2759 /// // 未配置软删除字段的表将执行物理删除
2760 /// let table_config2 = Arc::new(
2761 /// TableConfig::new("logs")
2762 /// .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2763 /// .field(FieldConfig::new("message", FieldType::Text)).expect("有效字段配置应注册成功")
2764 /// // 未配置 soft_delete_field
2765 /// );
2766 ///
2767 /// let query2 = TableQuery::new(
2768 /// table_config2,
2769 /// vec!["admin".to_string()],
2770 /// Some(pool),
2771 /// );
2772 ///
2773 /// // 执行物理删除(实际上是 DELETE FROM logs WHERE ...)
2774 /// let affected2 = query2
2775 /// .where_eq("id", json!(1))?
2776 /// .delete()
2777 /// .await?;
2778 /// println!("物理删除成功,影响行数: {}", affected2);
2779 /// # Ok(())
2780 /// # }
2781 /// ```
2782 pub async fn delete(self) -> Result<u64, BaseError> {
2783 // 1. 检查是否配置了软删除字段
2784 if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2785 // 软删除:走 build_update_sql_impl 跳过 validate_update_data_impl
2786 // 的用户写权限检查,与 updated_at 自动写入语义对称。
2787 let now = chrono::Utc::now().timestamp();
2788 let mut data = std::collections::HashMap::new();
2789 data.insert(soft_delete_field.clone(), Value::Number(now.into()));
2790 let (sql, params) = self.build_update_sql_impl(&data)?;
2791 let pool = self
2792 .pool
2793 .as_ref()
2794 .ok_or(BaseError::DatabaseNotInitialized)?;
2795 let result = Self::timed(
2796 self.slow_threshold,
2797 self.request_id,
2798 &self.table_config.table_name,
2799 "delete",
2800 Self::run_execute(pool.as_ref(), &sql, ¶ms),
2801 )
2802 .await?;
2803 return Ok(result.rows_affected());
2804 }
2805
2806 // 2. 物理删除:检查连接池
2807 let pool = self
2808 .pool
2809 .as_ref()
2810 .ok_or(BaseError::DatabaseNotInitialized)?;
2811
2812 // 3. 物理删除:构建 DELETE SQL 语句
2813 let (sql, params) = self.build_delete_sql()?;
2814
2815 // 4. 在连接池上执行删除(计时观测)
2816 let result = Self::timed(
2817 self.slow_threshold,
2818 self.request_id,
2819 &self.table_config.table_name,
2820 "delete",
2821 Self::run_execute(pool.as_ref(), &sql, ¶ms),
2822 )
2823 .await?;
2824
2825 Ok(result.rows_affected())
2826 }
2827
2828 /// 在事务中执行 DELETE 操作
2829 ///
2830 /// 与 [`TableQuery::delete`] 一致:配置了软删除字段时走 UPDATE 标记(同样在
2831 /// 事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
2832 ///
2833 /// # 错误
2834 ///
2835 /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2836 /// - 其余同 [`TableQuery::delete`]
2837 pub async fn delete_in_tx(self, tx: &mut yang_db::Transaction) -> Result<u64, BaseError> {
2838 // 软删除:走 build_update_sql_impl 跳过 validate_update_data_impl
2839 // 的用户写权限检查,与 updated_at 自动写入语义对称。
2840 if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2841 let now = chrono::Utc::now().timestamp();
2842 let mut data = std::collections::HashMap::new();
2843 data.insert(soft_delete_field.clone(), Value::Number(now.into()));
2844 let (sql, params) = self.build_update_sql_impl(&data)?;
2845 let executor = tx.executor().ok_or_else(|| {
2846 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2847 "事务已提交或回滚".to_string(),
2848 ))
2849 })?;
2850 let result = Self::timed(
2851 self.slow_threshold,
2852 self.request_id,
2853 &self.table_config.table_name,
2854 "delete_in_tx",
2855 Self::run_execute(executor, &sql, ¶ms),
2856 )
2857 .await?;
2858 return Ok(result.rows_affected());
2859 }
2860
2861 let (sql, params) = self.build_delete_sql()?;
2862
2863 let executor = tx.executor().ok_or_else(|| {
2864 BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2865 "事务已提交或回滚".to_string(),
2866 ))
2867 })?;
2868
2869 let result = Self::timed(
2870 self.slow_threshold,
2871 self.request_id,
2872 &self.table_config.table_name,
2873 "delete_in_tx",
2874 Self::run_execute(executor, &sql, ¶ms),
2875 )
2876 .await?;
2877 Ok(result.rows_affected())
2878 }
2879
2880 /// 构建 DELETE SQL 语句
2881 ///
2882 /// # 返回值
2883 ///
2884 /// 返回 (SQL 语句, 参数列表) 元组
2885 ///
2886 /// # 错误
2887 ///
2888 /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2889 #[cfg(test)]
2890 #[allow(private_interfaces)]
2891 pub fn build_delete_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2892 self.build_delete_sql_impl()
2893 }
2894
2895 /// 构建 SELECT SQL 语句(仅供测试使用)
2896 #[cfg(test)]
2897 #[allow(private_interfaces)]
2898 pub fn build_select_sql_for_test(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2899 self.build_select_sql(None)
2900 }
2901
2902 /// 构建 INSERT SQL 语句(仅供测试使用)
2903 ///
2904 /// 先经 `prepare_and_validate_insert` 补默认值/时间戳并校验,再拼 SQL,
2905 /// 等价于 `insert`/`insert_returning_id` 的建句路径,但无需数据库连接。
2906 #[cfg(test)]
2907 #[allow(private_interfaces)]
2908 pub fn build_insert_sql_for_test(
2909 &self,
2910 data: std::collections::HashMap<String, Value>,
2911 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2912 let prepared = self.prepare_and_validate_insert(data)?;
2913 self.build_insert_sql(&prepared)
2914 }
2915
2916 /// 构建 DELETE SQL 语句(内部实现)
2917 #[cfg(not(test))]
2918 fn build_delete_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2919 self.build_delete_sql_impl()
2920 }
2921
2922 /// 构建 DELETE SQL 语句的实际实现
2923 fn build_delete_sql_impl(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2924 // 表名走统一转义路径
2925 let mut sql = format!("DELETE FROM {}", self.quoted_table_name()?);
2926 let mut params = Vec::new();
2927
2928 // WHERE 守卫:无 WHERE 且未显式放行全表,拒绝全表物理删除
2929 if self.query_params.where_conditions.is_empty() && !self.allow_full_table {
2930 return Err(BaseError::MissingWhereClause("DELETE".to_string()));
2931 }
2932
2933 // 通过统一方法拼接 WHERE 子句(写路径,不应用软删过滤)
2934 self.append_where_to_sql(&mut sql, &mut params, false)?;
2935
2936 Ok((sql, params))
2937 }
2938
2939 /// 绑定参数到执行查询
2940 ///
2941 /// # 参数
2942 ///
2943 /// - `query`:sqlx 查询对象
2944 /// - `param`:SQL 参数值
2945 ///
2946 /// # 返回值
2947 ///
2948 /// 绑定参数后的查询对象
2949 fn bind_execute_param<'q>(
2950 query: sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments>,
2951 param: &SqlParam,
2952 ) -> sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments> {
2953 match param {
2954 SqlParam::Null => query.bind(Option::<i32>::None),
2955 SqlParam::Bool(b) => query.bind(*b),
2956 SqlParam::Int(i) => query.bind(*i),
2957 SqlParam::Uint(u) => query.bind(*u),
2958 SqlParam::Float(f) => query.bind(*f),
2959 SqlParam::String(s) => query.bind(s.clone()),
2960 SqlParam::DateTime(dt) => query.bind(*dt),
2961 SqlParam::Bytes(b) => query.bind(b.clone()),
2962 SqlParam::Json(j) => query.bind(j.clone()),
2963 }
2964 }
2965
2966 /// 执行边界计时(慢查询观测,C4)。
2967 ///
2968 /// 包裹一次数据库执行 `fut`:`threshold` 为 `None`(默认)时仅一次
2969 /// `Instant::now()`,无额外分配、无日志;为 `Some(d)` 且实际耗时超过 `d` 时
2970 /// 发一条 `tracing::warn!`(含表名、操作、耗时毫秒、request_id)。
2971 ///
2972 /// 设计为关联函数(不借用 `&self`),以便在消费 `self` 的终端方法里,与
2973 /// 借用 `self.pool`/`sql`/`params` 的执行 future 共存而不冲突借用检查。
2974 /// SQL 文本**默认不记**(防泄漏 + 防高基数)。`op` 为静态操作名。
2975 pub(crate) async fn timed<F, R>(
2976 threshold: Option<std::time::Duration>,
2977 request_id: Option<crate::action::RequestId>,
2978 table: &str,
2979 op: &'static str,
2980 fut: F,
2981 ) -> R
2982 where
2983 F: std::future::Future<Output = R>,
2984 {
2985 // 阈值未配置:直接 await,热路径仅一次分支判断,无 Instant
2986 let threshold = match threshold {
2987 Some(t) => t,
2988 None => return fut.await,
2989 };
2990 let start = std::time::Instant::now();
2991 let result = fut.await;
2992 let elapsed = start.elapsed();
2993 if elapsed >= threshold {
2994 let elapsed_ms = elapsed.as_secs_f64() * 1000.0;
2995 match request_id {
2996 Some(rid) => tracing::warn!(
2997 table = %table,
2998 op,
2999 elapsed_ms,
3000 request_id = %rid,
3001 "慢查询",
3002 ),
3003 None => tracing::warn!(table = %table, op, elapsed_ms, "慢查询"),
3004 }
3005 }
3006 result
3007 }
3008
3009 /// 在给定执行器上绑定参数并执行写语句(INSERT/UPDATE/DELETE 共用)
3010 ///
3011 /// 执行器既可以是 `&MySqlPool`(普通路径),也可以是
3012 /// `&mut sqlx::MySqlConnection`(事务路径,经 [`yang_db::Transaction::executor`]
3013 /// 取得)。如此一来,受保护层的写操作可以直接执行,也可纳入同一事务原子提交,
3014 /// 而所有权限/校验/软删/WHERE 守卫逻辑在调用方保持不变。
3015 ///
3016 /// 返回 `MySqlQueryResult`,由调用方按需提取 `rows_affected()` /
3017 /// `last_insert_id()`。
3018 async fn run_execute<'e, E>(
3019 executor: E,
3020 sql: &str,
3021 params: &[SqlParam],
3022 ) -> Result<sqlx::mysql::MySqlQueryResult, BaseError>
3023 where
3024 E: sqlx::Executor<'e, Database = sqlx::MySql>,
3025 {
3026 let mut query = sqlx::query(sql);
3027 for param in params {
3028 query = Self::bind_execute_param(query, param);
3029 }
3030 query
3031 .execute(executor)
3032 .await
3033 .map_err(|e| BaseError::DatabaseExecuteFailed(yang_db::DbError::from(e)))
3034 }
3035
3036 /// 在给定执行器上绑定参数并执行 SELECT 查询,返回多行
3037 ///
3038 /// 与 [`TableQuery::run_execute`] 同理对执行器泛型,使 `select` 既能走连接池
3039 /// 也能在事务内执行(read-modify-write 场景)。
3040 async fn run_fetch_all<'e, E, T>(
3041 executor: E,
3042 sql: &str,
3043 params: &[SqlParam],
3044 ) -> Result<Vec<T>, BaseError>
3045 where
3046 E: sqlx::Executor<'e, Database = sqlx::MySql>,
3047 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
3048 {
3049 let mut query = sqlx::query_as::<_, T>(sql);
3050 for param in params {
3051 query = Self::bind_param(query, param);
3052 }
3053 query
3054 .fetch_all(executor)
3055 .await
3056 .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))
3057 }
3058}
3059
3060/// SQL 参数类型
3061///
3062/// 用于表示 SQL 查询中的参数值
3063#[cfg(feature = "mysql")]
3064#[derive(Debug, Clone)]
3065#[cfg_attr(test, derive(PartialEq))]
3066#[allow(dead_code)] // DateTime/Bytes/Json 已声明,待 from_json 外部构造路径落地
3067pub(crate) enum SqlParam {
3068 /// 空值
3069 Null,
3070 /// 布尔值
3071 Bool(bool),
3072 /// 整数
3073 Int(i64),
3074 /// 无符号整数(保留超出 i64 范围的 u64 值,避免精度丢失)
3075 Uint(u64),
3076 /// 浮点数
3077 Float(f64),
3078 /// 字符串
3079 String(String),
3080 /// 日期时间(ISO 8601 字符串解析)
3081 DateTime(chrono::NaiveDateTime),
3082 /// 二进制数据
3083 Bytes(Vec<u8>),
3084 /// JSON 值
3085 Json(serde_json::Value),
3086}
3087
3088#[cfg(feature = "mysql")]
3089impl SqlParam {
3090 /// 从 JSON 值创建 SQL 参数
3091 ///
3092 /// # 参数
3093 ///
3094 /// - `value`:JSON 值
3095 ///
3096 /// # 返回值
3097 ///
3098 /// - `Ok(SqlParam)`:转换成功
3099 /// - `Err(BaseError)`:转换失败
3100 fn from_json(value: &Value) -> Result<Self, BaseError> {
3101 match value {
3102 Value::Null => Ok(SqlParam::Null),
3103 Value::Bool(b) => Ok(SqlParam::Bool(*b)),
3104 Value::Number(n) => {
3105 if let Some(i) = n.as_i64() {
3106 Ok(SqlParam::Int(i))
3107 } else if let Some(u) = n.as_u64() {
3108 // 超出 i64 范围的正整数,保留为 u64 避免精度丢失
3109 Ok(SqlParam::Uint(u))
3110 } else if let Some(f) = n.as_f64() {
3111 Ok(SqlParam::Float(f))
3112 } else {
3113 Err(BaseError::DatabaseQueryFailed(
3114 yang_db::DbError::QueryError(format!("不支持的数字类型: {}", n)),
3115 ))
3116 }
3117 }
3118 Value::String(s) => {
3119 // QRY-5: 尝试解析为 DateTime(ISO 8601 格式)
3120 if let Ok(dt) = chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S")
3121 .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S"))
3122 .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S%.f"))
3123 {
3124 return Ok(SqlParam::DateTime(dt));
3125 }
3126 Ok(SqlParam::String(s.clone()))
3127 }
3128 Value::Array(_) => Ok(SqlParam::Json(value.clone())),
3129 Value::Object(_) => Ok(SqlParam::Json(value.clone())),
3130 }
3131 }
3132}
3133
3134#[cfg(all(test, feature = "mysql"))]
3135mod tests {
3136 use super::*;
3137 use std::collections::HashSet;
3138 use std::sync::Arc;
3139
3140 fn test_query() -> TableQuery {
3141 let config = Arc::new(
3142 crate::table::TableConfig::new("users")
3143 .field(crate::table::FieldConfig::new(
3144 "id",
3145 crate::table::FieldType::Integer,
3146 ))
3147 .expect("有效字段配置应注册成功"),
3148 );
3149 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3150 TableQuery::new(config, roles, None)
3151 }
3152
3153 #[test]
3154 fn test_page_rejects_page_size_above_production_limit() {
3155 let err = test_query()
3156 .page(1, 101)
3157 .expect_err("page_size 超过 100 应被拒绝");
3158
3159 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "page_size"));
3160 }
3161
3162 #[test]
3163 fn test_default_order_rejects_unsortable_field() {
3164 let config = Arc::new(
3165 crate::table::TableConfig::new("users")
3166 .field(
3167 crate::table::FieldConfig::new("secret_rank", crate::table::FieldType::Integer)
3168 .sortable(false),
3169 )
3170 .expect("有效字段配置应注册成功")
3171 .default_order(vec![(
3172 "secret_rank".to_string(),
3173 crate::table::SortOrder::Desc,
3174 )]),
3175 );
3176 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3177 let query = TableQuery::new(config, roles, None);
3178
3179 let err = query
3180 .build_select_sql(None)
3181 .expect_err("默认排序不应绕过 sortable(false)");
3182
3183 assert!(
3184 matches!(err, BaseError::FieldPermissionDenied(table, field, _) if table == "users" && field == "secret_rank")
3185 );
3186 }
3187
3188 #[test]
3189 fn test_select_star_rejects_unreadable_field() {
3190 let protected_permissions = crate::table::FieldPermissions {
3191 readable_roles: HashSet::from(["admin".to_string()]),
3192 ..crate::table::FieldPermissions::default()
3193 };
3194 let config = Arc::new(
3195 crate::table::TableConfig::new("users")
3196 .field(crate::table::FieldConfig::new(
3197 "id",
3198 crate::table::FieldType::Integer,
3199 ))
3200 .expect("有效字段配置应注册成功")
3201 .field(
3202 crate::table::FieldConfig::new(
3203 "secret",
3204 crate::table::FieldType::String { max_length: 64 },
3205 )
3206 .permissions(protected_permissions),
3207 )
3208 .expect("有效字段配置应注册成功"),
3209 );
3210 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3211 let query = TableQuery::new(config, roles, None);
3212
3213 let err = query
3214 .build_select_sql(None)
3215 .expect_err("SELECT * 不应返回用户无权读取的字段");
3216
3217 assert!(
3218 matches!(err, BaseError::FieldPermissionDenied(table, field, _) if table == "users" && field == "secret")
3219 );
3220 }
3221
3222 #[test]
3223 fn test_select_projection_permission_matrix() {
3224 let protected = crate::table::FieldPermissions {
3225 readable_roles: HashSet::from(["admin".to_string()]),
3226 ..crate::table::FieldPermissions::default()
3227 };
3228
3229 let all_readable = Arc::new(
3230 crate::table::TableConfig::new("public_rows")
3231 .field(crate::table::FieldConfig::new(
3232 "id",
3233 crate::table::FieldType::Integer,
3234 ))
3235 .expect("公开字段配置应有效")
3236 .field(crate::table::FieldConfig::new(
3237 "name",
3238 crate::table::FieldType::String { max_length: 64 },
3239 ))
3240 .expect("公开字段配置应有效"),
3241 );
3242 let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3243 let (sql, _) = TableQuery::new(all_readable, Arc::clone(&roles), None)
3244 .build_select_sql(None)
3245 .expect("全部字段可读时 SELECT * 应成功");
3246 assert!(sql.starts_with("SELECT * FROM `public_rows`"));
3247
3248 let partially_readable = Arc::new(
3249 crate::table::TableConfig::new("mixed_rows")
3250 .field(crate::table::FieldConfig::new(
3251 "id",
3252 crate::table::FieldType::Integer,
3253 ))
3254 .expect("公开字段配置应有效")
3255 .field(
3256 crate::table::FieldConfig::new(
3257 "secret",
3258 crate::table::FieldType::String { max_length: 64 },
3259 )
3260 .permissions(protected.clone()),
3261 )
3262 .expect("受限字段配置应有效"),
3263 );
3264 let partial_err =
3265 TableQuery::new(Arc::clone(&partially_readable), Arc::clone(&roles), None)
3266 .build_select_sql(None)
3267 .expect_err("部分字段不可读时 SELECT * 应 fail-closed");
3268 assert!(
3269 matches!(partial_err, BaseError::FieldPermissionDenied(table, field, _) if table == "mixed_rows" && field == "secret")
3270 );
3271
3272 let explicit_err = TableQuery::new(partially_readable, Arc::clone(&roles), None)
3273 .select_fields(&["id", "secret"])
3274 .expect_err("显式请求受限字段应被拒绝");
3275 assert!(
3276 matches!(explicit_err, BaseError::FieldPermissionDenied(table, field, _) if table == "mixed_rows" && field == "secret")
3277 );
3278
3279 let none_readable = Arc::new(
3280 crate::table::TableConfig::new("private_rows")
3281 .field(
3282 crate::table::FieldConfig::new("alpha", crate::table::FieldType::Integer)
3283 .permissions(protected.clone()),
3284 )
3285 .expect("受限字段配置应有效")
3286 .field(
3287 crate::table::FieldConfig::new("beta", crate::table::FieldType::Integer)
3288 .permissions(protected),
3289 )
3290 .expect("受限字段配置应有效"),
3291 );
3292 let none_err = TableQuery::new(none_readable, roles, None)
3293 .build_select_sql(None)
3294 .expect_err("零字段可读时 SELECT * 应 fail-closed");
3295 assert!(matches!(
3296 none_err,
3297 BaseError::FieldPermissionDenied(table, _, _) if table == "private_rows"
3298 ));
3299 }
3300
3301 #[test]
3302 fn test_unreadable_field_errors_are_deterministic() {
3303 let protected = crate::table::FieldPermissions {
3304 readable_roles: HashSet::from(["admin".to_string()]),
3305 ..crate::table::FieldPermissions::default()
3306 };
3307 let user = crate::action::User::new(1, "reader").with_roles(["user"]);
3308
3309 for _ in 0..64 {
3310 let config = Arc::new(
3311 crate::table::TableConfig::new("secrets")
3312 .field(
3313 crate::table::FieldConfig::new(
3314 "z_secret",
3315 crate::table::FieldType::Integer,
3316 )
3317 .permissions(protected.clone()),
3318 )
3319 .expect("受限字段配置应有效")
3320 .field(
3321 crate::table::FieldConfig::new(
3322 "a_secret",
3323 crate::table::FieldType::Integer,
3324 )
3325 .permissions(protected.clone()),
3326 )
3327 .expect("受限字段配置应有效")
3328 .field(
3329 crate::table::FieldConfig::new(
3330 "m_secret",
3331 crate::table::FieldType::Integer,
3332 )
3333 .permissions(protected.clone()),
3334 )
3335 .expect("受限字段配置应有效"),
3336 );
3337 let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3338 let query = TableQuery::new(config, roles, None);
3339
3340 let sql_err = query
3341 .build_select_sql(None)
3342 .expect_err("SELECT * 应拒绝受限字段");
3343 assert!(
3344 matches!(sql_err, BaseError::FieldPermissionDenied(_, field, _) if field == "a_secret")
3345 );
3346
3347 let action_err = query
3348 .ensure_fields_readable(&user)
3349 .expect_err("整实体 Action 应拒绝受限字段");
3350 assert!(
3351 matches!(action_err, BaseError::FieldPermissionDenied(_, field, _) if field == "a_secret")
3352 );
3353 }
3354 }
3355
3356 #[test]
3357 fn test_effective_pagination_applies_default_limit_to_data_query_sql() {
3358 let (query, page, page_size) = test_query()
3359 .with_effective_pagination()
3360 .expect("默认分页参数应合法");
3361
3362 assert_eq!(page, 1);
3363 assert_eq!(
3364 page_size,
3365 crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3366 );
3367
3368 let (sql, _) = query
3369 .build_select_sql(None)
3370 .expect("默认分页后的 SELECT SQL 应可构建");
3371
3372 assert!(
3373 sql.contains(&format!(
3374 " LIMIT {} OFFSET 0",
3375 crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3376 )),
3377 "分页数据查询必须包含默认 LIMIT,实际 SQL: {sql}"
3378 );
3379 }
3380}