1use crate::error::BaseError;
37use crate::table::{QueryParams, SortOrder, TableConfig, WhereCondition};
38#[cfg(feature = "mysql")]
39use serde::Serialize;
40use serde_json::Value;
41use std::collections::HashSet;
42use std::sync::Arc;
43
44pub const MAX_TABLE_QUERY_PAGE_SIZE: usize = super::query_params::MAX_QUERY_PAGE_SIZE;
50
51#[derive(Debug, Clone)]
91pub struct TableQuery {
92 table_config: Arc<TableConfig>,
96
97 user_roles: Arc<[String]>,
101 user_roles_set: HashSet<String>,
103
104 query_params: QueryParams,
108
109 include_trashed: bool,
115
116 tenant_scope: Option<(String, Value)>,
118
119 #[cfg(feature = "mysql")]
123 #[allow(dead_code)]
124 pool: Option<Arc<sqlx::MySqlPool>>,
125
126 slow_threshold: Option<std::time::Duration>,
133
134 request_id: Option<crate::action::RequestId>,
136}
137
138impl TableQuery {
139 #[cfg(feature = "mysql")]
140 fn compile_predicate(
141 &self,
142 condition: &WhereCondition,
143 ) -> Result<yang_db::Predicate, BaseError> {
144 let field = |name: &str| {
145 self.table_config
146 .get_field_ref(name)
147 .cloned()
148 .ok_or_else(|| {
149 BaseError::FieldNotFound(self.table_config.table_name.clone(), name.to_string())
150 })
151 };
152 Ok(match condition {
153 WhereCondition::Eq { field: name, value } => {
154 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Eq, value.clone())
155 }
156 WhereCondition::Ne { field: name, value } => {
157 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Ne, value.clone())
158 }
159 WhereCondition::Gt { field: name, value } => {
160 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Gt, value.clone())
161 }
162 WhereCondition::Gte { field: name, value } => {
163 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Gte, value.clone())
164 }
165 WhereCondition::Lt { field: name, value } => {
166 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Lt, value.clone())
167 }
168 WhereCondition::Lte { field: name, value } => {
169 yang_db::Predicate::Compare(field(name)?, yang_db::CompareOp::Lte, value.clone())
170 }
171 WhereCondition::Like {
172 field: name,
173 pattern,
174 } => yang_db::Predicate::Compare(
175 field(name)?,
176 yang_db::CompareOp::Like,
177 Value::String(pattern.clone()),
178 ),
179 WhereCondition::In {
180 field: name,
181 values,
182 } => yang_db::Predicate::In(field(name)?, values.clone()),
183 WhereCondition::NotIn {
184 field: name,
185 values,
186 } => yang_db::Predicate::NotIn(field(name)?, values.clone()),
187 WhereCondition::Between {
188 field: name,
189 lo,
190 hi,
191 } => yang_db::Predicate::Between(field(name)?, lo.clone(), hi.clone()),
192 WhereCondition::IsNull { field: name } => yang_db::Predicate::IsNull(field(name)?),
193 WhereCondition::IsNotNull { field: name } => {
194 yang_db::Predicate::IsNotNull(field(name)?)
195 }
196 WhereCondition::And { conditions } => yang_db::Predicate::And(
197 conditions
198 .iter()
199 .map(|value| self.compile_predicate(value))
200 .collect::<Result<Vec<_>, _>>()?,
201 ),
202 WhereCondition::Or { conditions } => yang_db::Predicate::Or(
203 conditions
204 .iter()
205 .map(|value| self.compile_predicate(value))
206 .collect::<Result<Vec<_>, _>>()?,
207 ),
208 })
209 }
210
211 #[cfg(feature = "mysql")]
212 fn compile_db_query(&self) -> Result<yang_db::QueryBuilder<'_>, BaseError> {
213 let pool = self
214 .pool
215 .as_deref()
216 .ok_or(BaseError::DatabaseNotInitialized)?;
217 self.apply_db_plan(yang_db::QueryBuilder::from_pool(
218 pool,
219 &self.table_config.table_ref,
220 ))
221 }
222
223 #[cfg(feature = "mysql")]
224 fn apply_db_plan<'a>(
225 &self,
226 mut query: yang_db::QueryBuilder<'a>,
227 ) -> Result<yang_db::QueryBuilder<'a>, BaseError> {
228 let selected = self.query_params.fields.as_ref().map_or_else(
229 || {
230 self.default_read_fields()
231 .map(|values| values.into_iter().map(str::to_string).collect())
232 },
233 |values| Ok(values.clone()),
234 )?;
235 for name in selected {
236 let field = self.table_config.get_field_ref(&name).ok_or_else(|| {
237 BaseError::FieldNotFound(self.table_config.table_name.clone(), name.clone())
238 })?;
239 query = query.field(field);
240 }
241 for condition in &self.query_params.where_conditions {
242 query = query
243 .where_predicate(&self.compile_predicate(condition)?)
244 .map_err(BaseError::DatabaseQueryFailed)?;
245 }
246 if !self.include_trashed {
247 if let Some(name) = &self.table_config.soft_delete_field {
248 let field = self.table_config.get_field_ref(name).ok_or_else(|| {
249 BaseError::FieldNotFound(self.table_config.table_name.clone(), name.clone())
250 })?;
251 query = query.where_null(field);
252 }
253 }
254 let orders = if self.query_params.order_by.is_empty() {
255 &self.table_config.default_order
256 } else {
257 &self.query_params.order_by
258 };
259 for (name, order) in orders {
260 let field = self.table_config.get_field_ref(name).ok_or_else(|| {
261 BaseError::FieldNotFound(self.table_config.table_name.clone(), name.clone())
262 })?;
263 let order = match order {
264 SortOrder::Asc => yang_db::SortOrder::Asc,
265 SortOrder::Desc => yang_db::SortOrder::Desc,
266 };
267 query = query.order(field, order);
268 }
269 if let Some(page_size) = self.query_params.page_size {
270 let page = self.query_params.page.unwrap_or(1).max(1);
271 let limit = u64::try_from(page_size).map_err(|_| {
272 BaseError::ParamInvalid("page_size".to_string(), "分页大小超出范围".to_string())
273 })?;
274 let offset = u64::try_from((page - 1).saturating_mul(page_size)).map_err(|_| {
275 BaseError::ParamInvalid("page".to_string(), "分页偏移超出范围".to_string())
276 })?;
277 query = query.limit(limit).offset(offset);
278 }
279 Ok(query)
280 }
281
282 #[cfg(feature = "mysql")]
296 #[cfg(test)]
297 fn quote_identifier(&self, field: &str) -> Result<String, BaseError> {
298 self.table_config
299 .get_field_ref(field)
300 .map(|field| field.mysql_quoted().to_string())
301 .ok_or_else(|| {
302 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
303 })
304 }
305
306 #[cfg(feature = "mysql")]
316 #[cfg(test)]
317 fn quoted_table_name(&self) -> Result<String, BaseError> {
318 Ok(format!("`{}`", self.table_config.table_ref.as_str()))
319 }
320
321 #[cfg(feature = "mysql")]
333 pub(crate) fn new(
334 table_config: Arc<TableConfig>,
335 user_roles: Arc<[String]>,
336 pool: Option<Arc<sqlx::MySqlPool>>,
337 ) -> Self {
338 let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
339 Self {
340 table_config,
341 user_roles,
342 user_roles_set,
343 query_params: QueryParams::new(),
344 include_trashed: false,
345 tenant_scope: None,
346 pool,
347 slow_threshold: None,
348 request_id: None,
349 }
350 }
351
352 #[cfg(not(feature = "mysql"))]
356 pub(crate) fn new(
357 table_config: Arc<TableConfig>,
358 user_roles: Arc<[String]>,
359 _pool: Option<()>,
360 ) -> Self {
361 let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
362 Self {
363 table_config,
364 user_roles,
365 user_roles_set,
366 query_params: QueryParams::new(),
367 include_trashed: false,
368 tenant_scope: None,
369 slow_threshold: None,
370 request_id: None,
371 }
372 }
373
374 pub fn with_slow_threshold(mut self, threshold: Option<std::time::Duration>) -> Self {
379 self.slow_threshold = threshold;
380 self
381 }
382
383 pub fn with_request_id(mut self, request_id: crate::action::RequestId) -> Self {
385 self.request_id = Some(request_id);
386 self
387 }
388
389 fn validate_read_field(&self, field_name: &str) -> Result<(), BaseError> {
391 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
392 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.to_string())
393 })?;
394
395 if !field_config.permissions.can_read(&self.user_roles_set) {
396 return Err(BaseError::FieldPermissionDenied(
397 self.table_config.table_name.clone(),
398 field_name.to_string(),
399 "用户无读取权限".to_string(),
400 ));
401 }
402
403 Ok(())
404 }
405
406 #[cfg(feature = "mysql")]
407 fn default_read_fields(&self) -> Result<Vec<&str>, BaseError> {
408 let mut fields: Vec<&str> = self
409 .table_config
410 .fields
411 .iter()
412 .filter_map(|(name, field)| {
413 (!field.hidden && field.permissions.can_read(&self.user_roles_set))
414 .then_some(name.as_str())
415 })
416 .collect();
417 fields.sort_unstable();
418 if fields.is_empty() {
419 return Err(BaseError::FieldPermissionDenied(
420 self.table_config.table_name.clone(),
421 "*".to_string(),
422 "当前角色没有可读字段".to_string(),
423 ));
424 }
425 Ok(fields)
426 }
427
428 #[cfg(feature = "mysql")]
429 pub(crate) fn ensure_readable_projection(&self) -> Result<(), BaseError> {
430 self.default_read_fields().map(|_| ())
431 }
432
433 pub fn select_fields(mut self, fields: &[&str]) -> Result<Self, BaseError> {
437 if fields.is_empty() {
438 return Err(BaseError::ParamInvalid(
439 "fields".to_string(),
440 "查询字段列表不能为空".to_string(),
441 ));
442 }
443
444 for field_name in fields {
446 self.validate_read_field(field_name)?;
447 }
448
449 self.query_params.fields = Some(fields.iter().map(|s| s.to_string()).collect());
451
452 Ok(self)
453 }
454
455 pub fn where_eq(self, field: &str, value: Value) -> Result<Self, BaseError> {
484 self.push_where_condition(WhereCondition::Eq {
485 field: field.to_string(),
486 value,
487 })
488 }
489
490 pub fn where_in(self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
519 if values.is_empty() {
520 return Err(BaseError::ParamInvalid(
521 "values".to_string(),
522 "IN 列表不能为空".to_string(),
523 ));
524 }
525
526 if values.len() > Self::MAX_IN_LIST_SIZE {
528 return Err(BaseError::ParamInvalid(
529 "values".to_string(),
530 format!(
531 "IN 列表元素数 {} 超过上限 {}",
532 values.len(),
533 Self::MAX_IN_LIST_SIZE
534 ),
535 ));
536 }
537
538 self.push_where_condition(WhereCondition::In {
539 field: field.to_string(),
540 values,
541 })
542 }
543
544 pub fn where_like(self, field: &str, pattern: String) -> Result<Self, BaseError> {
571 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
573 return Err(BaseError::ParamInvalid(
574 "pattern".to_string(),
575 format!(
576 "LIKE pattern 长度 {} 超过上限 {}",
577 pattern.len(),
578 Self::MAX_LIKE_PATTERN_LEN
579 ),
580 ));
581 }
582
583 self.push_where_condition(WhereCondition::Like {
584 field: field.to_string(),
585 pattern,
586 })
587 }
588
589 pub fn where_contains(mut self, field: &str, keyword: &str) -> Result<Self, BaseError> {
611 if keyword.trim().is_empty() {
612 return Err(BaseError::ParamInvalid(
613 "keyword".to_string(),
614 "搜索关键词不能为空".to_string(),
615 ));
616 }
617
618 let escaped = keyword
620 .replace('\\', "\\\\")
621 .replace('%', "\\%")
622 .replace('_', "\\_");
623 let pattern = format!("%{}%", escaped);
624
625 self = self.where_like(field, pattern)?;
627 Ok(self)
628 }
629
630 pub fn where_ne(self, field: &str, value: Value) -> Result<Self, BaseError> {
651 self.push_where_condition(WhereCondition::Ne {
652 field: field.to_string(),
653 value,
654 })
655 }
656
657 pub fn where_lt(self, field: &str, value: Value) -> Result<Self, BaseError> {
678 self.push_where_condition(WhereCondition::Lt {
679 field: field.to_string(),
680 value,
681 })
682 }
683
684 pub fn where_lte(self, field: &str, value: Value) -> Result<Self, BaseError> {
705 self.push_where_condition(WhereCondition::Lte {
706 field: field.to_string(),
707 value,
708 })
709 }
710
711 pub fn where_gt(self, field: &str, value: Value) -> Result<Self, BaseError> {
732 self.push_where_condition(WhereCondition::Gt {
733 field: field.to_string(),
734 value,
735 })
736 }
737
738 pub fn where_gte(self, field: &str, value: Value) -> Result<Self, BaseError> {
759 self.push_where_condition(WhereCondition::Gte {
760 field: field.to_string(),
761 value,
762 })
763 }
764
765 pub fn where_between(self, field: &str, lo: Value, hi: Value) -> Result<Self, BaseError> {
789 self.push_where_condition(WhereCondition::Between {
790 field: field.to_string(),
791 lo,
792 hi,
793 })
794 }
795
796 pub fn where_null(self, field: &str) -> Result<Self, BaseError> {
816 self.push_where_condition(WhereCondition::IsNull {
817 field: field.to_string(),
818 })
819 }
820
821 pub fn where_not_null(self, field: &str) -> Result<Self, BaseError> {
841 self.push_where_condition(WhereCondition::IsNotNull {
842 field: field.to_string(),
843 })
844 }
845
846 pub fn where_not_in(self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
867 if values.is_empty() {
868 return Err(BaseError::ParamInvalid(
869 "values".to_string(),
870 "NOT IN 列表不能为空".to_string(),
871 ));
872 }
873
874 if values.len() > Self::MAX_IN_LIST_SIZE {
876 return Err(BaseError::ParamInvalid(
877 "values".to_string(),
878 format!(
879 "NOT IN 列表元素数 {} 超过上限 {}",
880 values.len(),
881 Self::MAX_IN_LIST_SIZE
882 ),
883 ));
884 }
885
886 self.push_where_condition(WhereCondition::NotIn {
887 field: field.to_string(),
888 values,
889 })
890 }
891
892 fn validate_order_field(&self, field: &str) -> Result<(), BaseError> {
921 let field_config = self.table_config.get_field(field).ok_or_else(|| {
923 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
924 })?;
925
926 if !field_config.sortable {
929 return Err(BaseError::FieldPermissionDenied(
930 self.table_config.table_name.clone(),
931 field.to_string(),
932 "字段不允许排序".to_string(),
933 ));
934 }
935
936 if !field_config.permissions.can_sort(&self.user_roles_set) {
938 return Err(BaseError::FieldPermissionDenied(
939 self.table_config.table_name.clone(),
940 field.to_string(),
941 "用户无排序权限".to_string(),
942 ));
943 }
944
945 Ok(())
946 }
947
948 pub fn order_by(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
952 self.validate_order_field(field)?;
953
954 self.query_params.order_by.push((field.to_string(), order));
956
957 Ok(self)
958 }
959
960 pub fn page(mut self, page: usize, page_size: usize) -> Result<Self, BaseError> {
979 if page == 0 || page_size == 0 {
980 return Err(BaseError::ParamInvalid(
981 "page".to_string(),
982 "页码与每页大小必须从 1 开始且大于 0".to_string(),
983 ));
984 }
985 if page_size > MAX_TABLE_QUERY_PAGE_SIZE {
986 return Err(BaseError::ParamInvalid(
987 "page_size".to_string(),
988 format!("每页大小不能超过 {}", MAX_TABLE_QUERY_PAGE_SIZE),
989 ));
990 }
991 self.query_params.page = Some(page);
992 self.query_params.page_size = Some(page_size);
993 Ok(self)
994 }
995
996 #[cfg(feature = "mysql")]
1002 pub(crate) fn prefetch_limit(mut self, limit: usize) -> Result<Self, BaseError> {
1003 if limit == 0 {
1004 return Err(BaseError::ParamInvalid(
1005 "limit".to_string(),
1006 "预取上限必须大于 0".to_string(),
1007 ));
1008 }
1009 self.query_params.page = Some(1);
1010 self.query_params.page_size = Some(limit);
1011 Ok(self)
1012 }
1013
1014 pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
1022 let Some(keyword) = keyword.map(str::trim).filter(|value| !value.is_empty()) else {
1023 return Ok(self);
1024 };
1025 let mut fields = self
1026 .table_config
1027 .fields
1028 .iter()
1029 .filter(|(_, field)| {
1030 field.field_type.is_text()
1031 && field.searchable
1032 && field.permissions.can_read(&self.user_roles_set)
1033 && !field.hidden
1034 })
1035 .map(|(name, _)| name.clone())
1036 .collect::<Vec<_>>();
1037 fields.sort();
1038 if fields.is_empty() {
1039 return Err(BaseError::PermissionDenied(format!(
1040 "表 {} 没有当前角色可搜索的文本字段",
1041 self.table_config.table_name
1042 )));
1043 }
1044 let pattern = format!("%{keyword}%");
1045 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1046 return Err(BaseError::ParamInvalid(
1047 "pattern".to_string(),
1048 format!(
1049 "LIKE pattern 长度 {} 超过上限 {}",
1050 pattern.len(),
1051 Self::MAX_LIKE_PATTERN_LEN
1052 ),
1053 ));
1054 }
1055 let group = WhereCondition::Or {
1056 conditions: fields
1057 .into_iter()
1058 .map(|field| WhereCondition::Like {
1059 field,
1060 pattern: pattern.clone(),
1061 })
1062 .collect(),
1063 };
1064 self.query_params.where_conditions.push(group);
1065 Ok(self)
1066 }
1067
1068 pub fn with_trashed(mut self) -> Self {
1078 self.include_trashed = true;
1079 self
1080 }
1081
1082 pub(crate) fn scope_tenant(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
1084 let config = self.table_config.get_field(field).ok_or_else(|| {
1085 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
1086 })?;
1087 if !config.tenant_key {
1088 return Err(BaseError::ConfigError(format!(
1089 "字段 {}.{} 未声明为 tenant_key",
1090 self.table_config.table_name, field
1091 )));
1092 }
1093 config.field_type.validate(field, &value)?;
1094 self.query_params.where_conditions.push(WhereCondition::Eq {
1095 field: field.to_string(),
1096 value: value.clone(),
1097 });
1098 self.tenant_scope = Some((field.to_string(), value));
1099 Ok(self)
1100 }
1101
1102 #[cfg(feature = "mysql")]
1108 pub(crate) fn where_primary_key_eq(mut self, value: Value) -> Result<Self, BaseError> {
1109 let field = self.table_config.primary_key.clone();
1110 let config = self.table_config.get_field(&field).ok_or_else(|| {
1111 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.clone())
1112 })?;
1113 if !value.is_null() {
1114 config.field_type.validate(&field, &value)?;
1115 }
1116 self.query_params
1117 .where_conditions
1118 .push(WhereCondition::Eq { field, value });
1119 Ok(self)
1120 }
1121
1122 fn validate_filter_field(&self, field: &str) -> Result<(), BaseError> {
1140 let field_config = self.table_config.get_field(field).ok_or_else(|| {
1142 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
1143 })?;
1144
1145 if !field_config.filterable {
1148 return Err(BaseError::FieldPermissionDenied(
1149 self.table_config.table_name.clone(),
1150 field.to_string(),
1151 "字段不允许筛选".to_string(),
1152 ));
1153 }
1154
1155 if !field_config.permissions.can_filter(&self.user_roles_set) {
1157 return Err(BaseError::FieldPermissionDenied(
1158 self.table_config.table_name.clone(),
1159 field.to_string(),
1160 "用户无筛选权限".to_string(),
1161 ));
1162 }
1163
1164 Ok(())
1165 }
1166
1167 fn push_where_condition(mut self, condition: WhereCondition) -> Result<Self, BaseError> {
1169 self.validate_condition_tree(&condition, 0)?;
1170 self.query_params.where_conditions.push(condition);
1171 Ok(self)
1172 }
1173
1174 fn validate_condition_values(
1176 &self,
1177 condition: &WhereCondition,
1178 field: &str,
1179 ) -> Result<(), BaseError> {
1180 let field_config = self.table_config.get_field(field).ok_or_else(|| {
1181 BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
1182 })?;
1183 let field_type = &field_config.field_type;
1184
1185 let reject_operator = |operator: &str| {
1186 BaseError::ParamInvalid(
1187 field.to_string(),
1188 format!("字段类型 {field_type:?} 不支持 {operator} 条件"),
1189 )
1190 };
1191 let validate = |value: &Value| field_type.validate(field, value);
1192 let is_orderable = matches!(
1193 field_type,
1194 crate::table::FieldType::String { .. }
1195 | crate::table::FieldType::Integer
1196 | crate::table::FieldType::BigInt
1197 | crate::table::FieldType::Float
1198 | crate::table::FieldType::Double
1199 | crate::table::FieldType::Decimal { .. }
1200 | crate::table::FieldType::Date
1201 | crate::table::FieldType::DateTime
1202 | crate::table::FieldType::Timestamp
1203 | crate::table::FieldType::Text
1204 | crate::table::FieldType::Enum { .. }
1205 );
1206 let is_textual = matches!(
1207 field_type,
1208 crate::table::FieldType::String { .. }
1209 | crate::table::FieldType::Text
1210 | crate::table::FieldType::Enum { .. }
1211 );
1212
1213 match condition {
1214 WhereCondition::Eq { value, .. } | WhereCondition::Ne { value, .. } => {
1215 if value.is_null() {
1217 Ok(())
1218 } else {
1219 validate(value)
1220 }
1221 }
1222 WhereCondition::In { values, .. } | WhereCondition::NotIn { values, .. } => {
1223 values.iter().try_for_each(validate)
1224 }
1225 WhereCondition::Like { .. } => {
1226 if is_textual {
1227 Ok(())
1228 } else {
1229 Err(reject_operator("LIKE"))
1230 }
1231 }
1232 WhereCondition::Gt { value, .. }
1233 | WhereCondition::Gte { value, .. }
1234 | WhereCondition::Lt { value, .. }
1235 | WhereCondition::Lte { value, .. } => {
1236 if !is_orderable {
1237 return Err(reject_operator("范围比较"));
1238 }
1239 validate(value)
1240 }
1241 WhereCondition::Between { lo, hi, .. } => {
1242 if !is_orderable {
1243 return Err(reject_operator("BETWEEN"));
1244 }
1245 validate(lo)?;
1246 validate(hi)
1247 }
1248 WhereCondition::IsNull { .. } | WhereCondition::IsNotNull { .. } => Ok(()),
1249 WhereCondition::And { .. } | WhereCondition::Or { .. } => Err(BaseError::ParamInvalid(
1250 "condition".to_string(),
1251 "逻辑组不能作为叶子条件校验".to_string(),
1252 )),
1253 }
1254 }
1255
1256 const MAX_WHERE_DEPTH: usize = 32;
1260
1261 const MAX_LIKE_PATTERN_LEN: usize = 128;
1266
1267 const MAX_IN_LIST_SIZE: usize = 500;
1272
1273 fn validate_condition_tree(
1285 &self,
1286 condition: &WhereCondition,
1287 depth: usize,
1288 ) -> Result<(), BaseError> {
1289 if depth > Self::MAX_WHERE_DEPTH {
1290 return Err(BaseError::ParamInvalid(
1291 "where".to_string(),
1292 format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1293 ));
1294 }
1295
1296 match condition {
1297 WhereCondition::And { conditions } | WhereCondition::Or { conditions } => {
1298 if conditions.is_empty() {
1302 return Err(BaseError::ParamInvalid(
1303 "where".to_string(),
1304 "AND/OR 布尔组不能为空".to_string(),
1305 ));
1306 }
1307 for child in conditions {
1308 self.validate_condition_tree(child, depth + 1)?;
1309 }
1310 Ok(())
1311 }
1312 leaf => {
1314 let field = leaf.field().ok_or_else(|| {
1315 BaseError::ParamInvalid(
1316 "condition".to_string(),
1317 "条件节点缺少字段名".to_string(),
1318 )
1319 })?;
1320 self.validate_filter_field(field)?;
1321 if let WhereCondition::Like { pattern, .. } = leaf {
1323 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1324 return Err(BaseError::ParamInvalid(
1325 "pattern".to_string(),
1326 format!(
1327 "LIKE pattern 长度 {} 超过上限 {}",
1328 pattern.len(),
1329 Self::MAX_LIKE_PATTERN_LEN
1330 ),
1331 ));
1332 }
1333 }
1334 if let WhereCondition::In { values, .. } | WhereCondition::NotIn { values, .. } =
1336 leaf
1337 {
1338 if values.is_empty() {
1339 return Err(BaseError::ParamInvalid(
1340 "values".to_string(),
1341 "IN/NOT IN 列表不能为空".to_string(),
1342 ));
1343 }
1344
1345 if values.len() > Self::MAX_IN_LIST_SIZE {
1346 return Err(BaseError::ParamInvalid(
1347 "values".to_string(),
1348 format!(
1349 "IN/NOT IN 列表元素数 {} 超过上限 {}",
1350 values.len(),
1351 Self::MAX_IN_LIST_SIZE
1352 ),
1353 ));
1354 }
1355 }
1356 self.validate_condition_values(leaf, field)
1357 }
1358 }
1359 }
1360
1361 pub fn where_or(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1393 let group = WhereCondition::Or { conditions };
1394 self.validate_condition_tree(&group, 0)?;
1396 self.query_params.where_conditions.push(group);
1397 Ok(self)
1398 }
1399
1400 pub fn where_and(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1415 let group = WhereCondition::And { conditions };
1416 self.validate_condition_tree(&group, 0)?;
1417 self.query_params.where_conditions.push(group);
1418 Ok(self)
1419 }
1420
1421 pub fn where_tree(mut self, condition: WhereCondition) -> Result<Self, BaseError> {
1436 self.validate_condition_tree(&condition, 0)?;
1437 self.query_params.where_conditions.push(condition);
1438 Ok(self)
1439 }
1440
1441 #[allow(dead_code)]
1449 pub fn get_query_params(&self) -> &QueryParams {
1450 &self.query_params
1451 }
1452
1453 pub fn apply_params(mut self, mut params: QueryParams) -> Result<Self, BaseError> {
1455 params.normalize();
1456 if let Some(fields) = params.fields {
1457 let names = fields.iter().map(String::as_str).collect::<Vec<_>>();
1458 self = self.select_fields(&names)?;
1459 }
1460 for condition in params.where_conditions {
1461 self = self.where_tree(condition)?;
1462 }
1463 for (field, order) in params.order_by {
1464 self = self.order_by(&field, order)?;
1465 }
1466 if params.page.is_some() || params.page_size.is_some() {
1467 self = self.page(
1468 params.page.unwrap_or(1),
1469 params
1470 .page_size
1471 .unwrap_or(crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE),
1472 )?;
1473 }
1474 Ok(self)
1475 }
1476
1477 #[allow(dead_code)]
1485 pub(crate) fn get_table_config(&self) -> &Arc<TableConfig> {
1486 &self.table_config
1487 }
1488
1489 #[allow(dead_code)]
1497 pub fn get_user_roles(&self) -> &[String] {
1498 &self.user_roles
1499 }
1500
1501 #[cfg(all(test, feature = "mysql"))]
1505 pub(crate) fn new_without_pool(table_config: Arc<TableConfig>) -> Self {
1506 Self::new(table_config, Arc::from(vec![]), None)
1507 }
1508}
1509
1510#[cfg(feature = "mysql")]
1512impl TableQuery {
1513 fn with_effective_pagination(self) -> Result<(Self, usize, usize), BaseError> {
1537 let page = self.query_params.page.unwrap_or(1);
1538 let page_size = self
1539 .query_params
1540 .page_size
1541 .unwrap_or(super::query_params::DEFAULT_QUERY_PAGE_SIZE);
1542 let query = self.page(page, page_size)?;
1543
1544 Ok((query, page, page_size))
1545 }
1546
1547 pub(crate) async fn paginate<T>(self) -> Result<crate::table::PaginatedResult<T>, BaseError>
1551 where
1552 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin + Serialize,
1553 {
1554 let _pool = self
1556 .pool
1557 .as_ref()
1558 .ok_or(BaseError::DatabaseNotInitialized)?;
1559
1560 let (query, page, page_size) = self.with_effective_pagination()?;
1562
1563 let total = query.count_internal().await?;
1565
1566 if total == 0 {
1568 return Ok(crate::table::PaginatedResult::empty(page, page_size));
1569 }
1570
1571 let data = query.select().await?;
1573
1574 Ok(crate::table::PaginatedResult::new(
1576 data, total, page, page_size,
1577 ))
1578 }
1579
1580 pub async fn paginate_records(
1582 self,
1583 ) -> Result<crate::table::PaginatedResult<crate::table::Record>, BaseError> {
1584 self.paginate::<crate::table::Record>().await
1585 }
1586
1587 async fn count_internal(&self) -> Result<usize, BaseError> {
1603 self.ensure_readable_projection()?;
1605 let mut count_query = self.clone();
1608 count_query.query_params.page = None;
1609 count_query.query_params.page_size = None;
1610 let count = count_query
1611 .compile_db_query()?
1612 .count()
1613 .await
1614 .map_err(BaseError::DatabaseQueryFailed)?;
1615 usize::try_from(count).map_err(|_| {
1616 BaseError::DatabaseQueryFailed(yang_db::DbError::QueryError(
1617 "COUNT 结果超出 usize 范围".to_string(),
1618 ))
1619 })
1620 }
1621
1622 pub async fn count(self) -> Result<u64, BaseError> {
1647 self.count_internal().await.map(|n| n as u64)
1648 }
1649
1650 #[cfg(test)]
1668 fn append_where_to_sql(
1669 &self,
1670 sql: &mut String,
1671 params: &mut Vec<SqlParam>,
1672 apply_soft_delete: bool,
1673 ) -> Result<(), BaseError> {
1674 let has_soft_delete = apply_soft_delete
1676 && !self.include_trashed
1677 && self.table_config.soft_delete_field.is_some();
1678
1679 if self.query_params.where_conditions.is_empty() && !has_soft_delete {
1681 return Ok(());
1682 }
1683
1684 sql.push_str(" WHERE ");
1685 let mut first = true;
1686
1687 for condition in &self.query_params.where_conditions {
1689 if !first {
1690 sql.push_str(" AND ");
1691 }
1692 first = false;
1693 self.render_condition(condition, sql, params, 0)?;
1694 }
1695
1696 if has_soft_delete {
1698 if let Some(field) = &self.table_config.soft_delete_field {
1699 let quoted = self.quote_identifier(field)?;
1700 if !first {
1701 sql.push_str(" AND ");
1702 }
1703 sql.push_str(&format!("{} IS NULL", quoted));
1704 }
1705 }
1706
1707 Ok(())
1708 }
1709
1710 #[cfg(test)]
1715 fn render_condition(
1716 &self,
1717 condition: &WhereCondition,
1718 sql: &mut String,
1719 params: &mut Vec<SqlParam>,
1720 depth: usize,
1721 ) -> Result<(), BaseError> {
1722 if depth > Self::MAX_WHERE_DEPTH {
1723 return Err(BaseError::ParamInvalid(
1724 "where".to_string(),
1725 format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1726 ));
1727 }
1728
1729 match condition {
1730 WhereCondition::Eq { field, value } => {
1731 let quoted = self.quote_identifier(field)?;
1732 if value.is_null() {
1733 sql.push_str(&format!("{} IS NULL", quoted));
1734 } else {
1735 sql.push_str(&format!("{} = ?", quoted));
1736 params.push(SqlParam::from_json(value)?);
1737 }
1738 }
1739 WhereCondition::In { field, values } => {
1740 if values.len() > Self::MAX_IN_LIST_SIZE {
1742 return Err(BaseError::ParamInvalid(
1743 "values".to_string(),
1744 format!(
1745 "IN 列表元素数 {} 超过上限 {}",
1746 values.len(),
1747 Self::MAX_IN_LIST_SIZE
1748 ),
1749 ));
1750 }
1751 let quoted = self.quote_identifier(field)?;
1752 if values.is_empty() {
1753 sql.push_str("1=0");
1755 } else {
1756 let placeholders = vec!["?"; values.len()].join(", ");
1757 sql.push_str(&format!("{} IN ({})", quoted, placeholders));
1758 for value in values {
1759 params.push(SqlParam::from_json(value)?);
1760 }
1761 }
1762 }
1763 WhereCondition::Like { field, pattern } => {
1764 if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1766 return Err(BaseError::ParamInvalid(
1767 "pattern".to_string(),
1768 format!(
1769 "LIKE pattern 长度 {} 超过上限 {}",
1770 pattern.len(),
1771 Self::MAX_LIKE_PATTERN_LEN
1772 ),
1773 ));
1774 }
1775 let quoted = self.quote_identifier(field)?;
1776 sql.push_str(&format!("{} LIKE ?", quoted));
1777 params.push(SqlParam::String(pattern.clone()));
1778 }
1779 WhereCondition::Gt { field, value } => {
1780 let quoted = self.quote_identifier(field)?;
1781 sql.push_str(&format!("{} > ?", quoted));
1782 params.push(SqlParam::from_json(value)?);
1783 }
1784 WhereCondition::Gte { field, value } => {
1785 let quoted = self.quote_identifier(field)?;
1786 sql.push_str(&format!("{} >= ?", quoted));
1787 params.push(SqlParam::from_json(value)?);
1788 }
1789 WhereCondition::Lt { field, value } => {
1790 let quoted = self.quote_identifier(field)?;
1791 sql.push_str(&format!("{} < ?", quoted));
1792 params.push(SqlParam::from_json(value)?);
1793 }
1794 WhereCondition::Lte { field, value } => {
1795 let quoted = self.quote_identifier(field)?;
1796 sql.push_str(&format!("{} <= ?", quoted));
1797 params.push(SqlParam::from_json(value)?);
1798 }
1799 WhereCondition::IsNull { field } => {
1800 let quoted = self.quote_identifier(field)?;
1801 sql.push_str(&format!("{} IS NULL", quoted));
1802 }
1803 WhereCondition::IsNotNull { field } => {
1804 let quoted = self.quote_identifier(field)?;
1805 sql.push_str(&format!("{} IS NOT NULL", quoted));
1806 }
1807 WhereCondition::Ne { field, value } => {
1808 let quoted = self.quote_identifier(field)?;
1809 if value.is_null() {
1810 sql.push_str(&format!("{} IS NOT NULL", quoted));
1811 } else {
1812 sql.push_str(&format!("{} <> ?", quoted));
1813 params.push(SqlParam::from_json(value)?);
1814 }
1815 }
1816 WhereCondition::Between { field, lo, hi } => {
1817 let quoted = self.quote_identifier(field)?;
1818 sql.push_str(&format!("{} BETWEEN ? AND ?", quoted));
1819 params.push(SqlParam::from_json(lo)?);
1820 params.push(SqlParam::from_json(hi)?);
1821 }
1822 WhereCondition::NotIn { field, values } => {
1823 if values.len() > Self::MAX_IN_LIST_SIZE {
1825 return Err(BaseError::ParamInvalid(
1826 "values".to_string(),
1827 format!(
1828 "NOT IN 列表元素数 {} 超过上限 {}",
1829 values.len(),
1830 Self::MAX_IN_LIST_SIZE
1831 ),
1832 ));
1833 }
1834 let quoted = self.quote_identifier(field)?;
1835 if values.is_empty() {
1836 sql.push_str("1=1");
1838 } else {
1839 let placeholders = vec!["?"; values.len()].join(", ");
1840 sql.push_str(&format!("{} NOT IN ({})", quoted, placeholders));
1841 for value in values {
1842 params.push(SqlParam::from_json(value)?);
1843 }
1844 }
1845 }
1846 WhereCondition::And { conditions } => {
1848 self.render_group(conditions, " AND ", "1=1", sql, params, depth)?;
1849 }
1850 WhereCondition::Or { conditions } => {
1851 self.render_group(conditions, " OR ", "1=0", sql, params, depth)?;
1852 }
1853 }
1854
1855 Ok(())
1856 }
1857
1858 #[cfg(test)]
1861 fn render_group(
1862 &self,
1863 conditions: &[WhereCondition],
1864 separator: &str,
1865 empty_literal: &str,
1866 sql: &mut String,
1867 params: &mut Vec<SqlParam>,
1868 depth: usize,
1869 ) -> Result<(), BaseError> {
1870 if conditions.is_empty() {
1871 sql.push_str(empty_literal);
1872 return Ok(());
1873 }
1874
1875 sql.push('(');
1876 let mut first = true;
1877 for cond in conditions {
1878 if !first {
1879 sql.push_str(separator);
1880 }
1881 first = false;
1882 self.render_condition(cond, sql, params, depth + 1)?;
1883 }
1884 sql.push(')');
1885 Ok(())
1886 }
1887
1888 pub(crate) async fn select<T>(self) -> Result<Vec<T>, BaseError>
1908 where
1909 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1910 {
1911 self.compile_db_query()?
1912 .select::<T>()
1913 .await
1914 .map_err(BaseError::DatabaseQueryFailed)
1915 }
1916
1917 pub async fn all(self) -> Result<Vec<crate::table::Record>, BaseError> {
1919 self.select::<crate::table::Record>().await
1920 }
1921
1922 pub(crate) async fn select_in_tx<T>(
1938 self,
1939 tx: &mut yang_db::Transaction,
1940 ) -> Result<Vec<T>, BaseError>
1941 where
1942 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1943 {
1944 let query = tx.table(&self.table_config.table_ref);
1945 self.apply_db_plan(query)?
1946 .select::<T>()
1947 .await
1948 .map_err(BaseError::DatabaseQueryFailed)
1949 }
1950
1951 pub async fn all_in_tx(
1953 self,
1954 tx: &mut yang_db::Transaction,
1955 ) -> Result<Vec<crate::table::Record>, BaseError> {
1956 self.select_in_tx::<crate::table::Record>(tx).await
1957 }
1958
1959 #[cfg(test)]
1969 fn build_select_sql(
1970 &self,
1971 hard_limit: Option<usize>,
1972 ) -> Result<(String, Vec<SqlParam>), BaseError> {
1973 let mut sql = String::from("SELECT ");
1974 let mut params = Vec::new();
1975
1976 if let Some(fields) = &self.query_params.fields {
1978 if fields.is_empty() {
1979 let quoted_fields = self
1980 .default_read_fields()?
1981 .into_iter()
1982 .map(|field| self.quote_identifier(field))
1983 .collect::<Result<Vec<_>, _>>()?;
1984 sql.push_str("ed_fields.join(", "));
1985 } else {
1986 let quoted_fields: Result<Vec<String>, BaseError> = fields
1988 .iter()
1989 .map(|f| {
1990 self.validate_read_field(f)?;
1991 self.quote_identifier(f)
1992 })
1993 .collect();
1994 sql.push_str("ed_fields?.join(", "));
1995 }
1996 } else {
1997 let quoted_fields = self
1998 .default_read_fields()?
1999 .into_iter()
2000 .map(|field| self.quote_identifier(field))
2001 .collect::<Result<Vec<_>, _>>()?;
2002 sql.push_str("ed_fields.join(", "));
2003 }
2004
2005 sql.push_str(&format!(" FROM {}", self.quoted_table_name()?));
2007
2008 self.append_where_to_sql(&mut sql, &mut params, true)?;
2010
2011 let order_source = if !self.query_params.order_by.is_empty() {
2013 Some(&self.query_params.order_by)
2014 } else if !self.table_config.default_order.is_empty() {
2015 Some(&self.table_config.default_order)
2016 } else {
2017 None
2018 };
2019 if let Some(orders) = order_source {
2020 sql.push_str(" ORDER BY ");
2021 let order_clauses: Result<Vec<String>, BaseError> = orders
2022 .iter()
2023 .map(|(field, order)| {
2024 self.validate_order_field(field)?;
2025 let direction = match order {
2026 SortOrder::Asc => "ASC",
2027 SortOrder::Desc => "DESC",
2028 };
2029 self.quote_identifier(field)
2030 .map(|quoted| format!("{} {}", quoted, direction))
2031 })
2032 .collect();
2033 sql.push_str(&order_clauses?.join(", "));
2034 }
2035
2036 if let (Some(page), Some(page_size)) = (self.query_params.page, self.query_params.page_size)
2038 {
2039 let offset = page.saturating_sub(1).saturating_mul(page_size);
2042 sql.push_str(&format!(" LIMIT {} OFFSET {}", page_size, offset));
2043 } else if let Some(limit) = hard_limit {
2044 sql.push_str(&format!(" LIMIT {}", limit));
2046 }
2047
2048 Ok((sql, params))
2049 }
2050
2051 pub(crate) async fn fetch_optional<T>(self) -> Result<Option<T>, BaseError>
2091 where
2092 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
2093 {
2094 self.compile_db_query()?
2095 .find::<T>()
2096 .await
2097 .map_err(BaseError::DatabaseQueryFailed)
2098 }
2099
2100 pub async fn optional(self) -> Result<Option<crate::table::Record>, BaseError> {
2102 self.fetch_optional::<crate::table::Record>().await
2103 }
2104
2105 pub async fn one(self) -> Result<crate::table::Record, BaseError> {
2107 let table_name = self.table_config.table_name.clone();
2108 self.optional()
2109 .await?
2110 .ok_or_else(|| BaseError::RecordNotFound(format!("表 {table_name} 中没有匹配记录")))
2111 }
2112
2113 pub async fn insert(self, data: crate::table::Record) -> Result<u64, BaseError> {
2156 let data = self.prepare_and_validate_insert(data.into_columns())?;
2158 self.compile_db_query()?
2159 .insert(&data)
2160 .await
2161 .map_err(BaseError::DatabaseExecuteFailed)?;
2162 Ok(1)
2163 }
2164
2165 pub async fn insert_in_tx(
2175 self,
2176 tx: &mut yang_db::Transaction,
2177 data: crate::table::Record,
2178 ) -> Result<u64, BaseError> {
2179 let data = self.prepare_and_validate_insert(data.into_columns())?;
2180 let query = tx.table(&self.table_config.table_ref);
2181 self.apply_db_plan(query)?
2182 .insert(&data)
2183 .await
2184 .map_err(BaseError::DatabaseExecuteFailed)?;
2185 Ok(1)
2186 }
2187
2188 pub async fn insert_returning_id(
2210 self,
2211 data: crate::table::Record,
2212 ) -> Result<(u64, u64), BaseError> {
2213 let data = self.prepare_and_validate_insert(data.into_columns())?;
2214 let id = self
2215 .compile_db_query()?
2216 .insert(&data)
2217 .await
2218 .map_err(BaseError::DatabaseExecuteFailed)?;
2219 Ok((1, id))
2220 }
2221
2222 pub async fn insert_returning_id_in_tx(
2227 self,
2228 tx: &mut yang_db::Transaction,
2229 data: crate::table::Record,
2230 ) -> Result<(u64, u64), BaseError> {
2231 let data = self.prepare_and_validate_insert(data.into_columns())?;
2232 let query = tx.table(&self.table_config.table_ref);
2233 let id = self
2234 .apply_db_plan(query)?
2235 .insert(&data)
2236 .await
2237 .map_err(BaseError::DatabaseExecuteFailed)?;
2238 Ok((1, id))
2239 }
2240
2241 fn prepare_and_validate_insert(
2259 &self,
2260 data: std::collections::HashMap<String, Value>,
2261 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
2262 let mut prepared = data;
2263
2264 if let Some((field, value)) = &self.tenant_scope {
2266 if prepared.contains_key(field) {
2267 return Err(BaseError::PermissionDenied(format!(
2268 "禁止显式写入租户字段: {field}"
2269 )));
2270 }
2271 prepared.insert(field.clone(), value.clone());
2272 }
2273
2274 for (field_name, value) in &prepared {
2277 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
2278 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
2279 })?;
2280 let omitted_auto_increment = field_config.auto_increment && value.is_null();
2281 let injected_tenant = self
2282 .tenant_scope
2283 .as_ref()
2284 .is_some_and(|(tenant_field, _)| tenant_field == field_name);
2285 if !injected_tenant
2286 && !omitted_auto_increment
2287 && !field_config.permissions.can_write(&self.user_roles_set)
2288 {
2289 return Err(BaseError::FieldPermissionDenied(
2290 self.table_config.table_name.clone(),
2291 field_name.clone(),
2292 "用户无写入权限".to_string(),
2293 ));
2294 }
2295 }
2296
2297 for (field_name, field_config) in &self.table_config.fields {
2299 if field_config.auto_increment
2300 && prepared
2301 .get(field_name)
2302 .map(serde_json::Value::is_null)
2303 .unwrap_or(true)
2304 {
2305 prepared.remove(field_name);
2306 }
2307 }
2308
2309 for (field_name, field_config) in &self.table_config.fields {
2311 if field_config.auto_increment {
2312 continue;
2313 }
2314 if let Some(default) = &field_config.default_value {
2315 if !prepared.contains_key(field_name) {
2316 prepared.insert(field_name.clone(), default.clone());
2317 }
2318 }
2319 }
2320
2321 if let Some(ts) = &self.table_config.timestamp_fields {
2323 let now = chrono::Utc::now().timestamp();
2324 for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
2325 if self.table_config.fields.contains_key(ts_field) {
2326 let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
2327 if missing {
2328 prepared.insert(ts_field.clone(), Value::Number(now.into()));
2329 }
2330 }
2331 }
2332 }
2333
2334 for (field_name, field_config) in &self.table_config.fields {
2336 if !field_config.permissions.can_write(&self.user_roles_set) {
2337 continue;
2338 }
2339 if field_config.auto_increment && !prepared.contains_key(field_name) {
2340 continue;
2341 }
2342 let value = prepared.get(field_name).unwrap_or(&Value::Null);
2343 field_config.validate(value)?;
2344 }
2345
2346 Ok(prepared)
2347 }
2348
2349 #[cfg(test)]
2363 fn build_insert_sql(
2364 &self,
2365 data: &std::collections::HashMap<String, Value>,
2366 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2367 let mut fields = Vec::with_capacity(data.len());
2368 let mut placeholders = Vec::with_capacity(data.len());
2369 let mut params = Vec::with_capacity(data.len());
2370
2371 for (field_name, value) in data {
2373 if !self.table_config.fields.contains_key(field_name) {
2375 return Err(BaseError::FieldNotFound(
2376 self.table_config.table_name.clone(),
2377 field_name.clone(),
2378 ));
2379 }
2380
2381 let quoted = self.quote_identifier(field_name)?;
2386 fields.push(quoted);
2387 placeholders.push("?".to_string());
2388 params.push(SqlParam::from_json(value)?);
2389 }
2390
2391 let sql = format!(
2393 "INSERT INTO {} ({}) VALUES ({})",
2394 self.quoted_table_name()?,
2395 fields.join(", "),
2396 placeholders.join(", ")
2397 );
2398
2399 Ok((sql, params))
2400 }
2401
2402 pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
2450 let data = self.prepare_update_data(data.into_columns())?;
2451 self.compile_db_query()?
2452 .update(&data)
2453 .await
2454 .map_err(BaseError::DatabaseExecuteFailed)
2455 }
2456
2457 pub async fn update_in_tx(
2467 self,
2468 tx: &mut yang_db::Transaction,
2469 data: crate::table::Record,
2470 ) -> Result<u64, BaseError> {
2471 let data = self.prepare_update_data(data.into_columns())?;
2472 let query = tx.table(&self.table_config.table_ref);
2473 self.apply_db_plan(query)?
2474 .update(&data)
2475 .await
2476 .map_err(BaseError::DatabaseExecuteFailed)
2477 }
2478
2479 fn prepare_update_data(
2480 &self,
2481 data: std::collections::HashMap<String, Value>,
2482 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
2483 self.validate_update_data(&data)?;
2484 self.with_updated_timestamp(data)
2485 }
2486
2487 fn with_updated_timestamp(
2488 &self,
2489 mut data: std::collections::HashMap<String, Value>,
2490 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
2491 if data.is_empty() {
2492 return Err(BaseError::ParamInvalid(
2493 "data".to_string(),
2494 "无可更新字段".to_string(),
2495 ));
2496 }
2497 if let Some(updated_at) = self
2498 .table_config
2499 .timestamp_fields
2500 .as_ref()
2501 .and_then(|fields| fields.updated_at.as_ref())
2502 .filter(|name| self.table_config.fields.contains_key(*name))
2503 {
2504 data.insert(
2505 updated_at.clone(),
2506 Value::Number(chrono::Utc::now().timestamp().into()),
2507 );
2508 }
2509 Ok(data)
2510 }
2511
2512 #[cfg(test)]
2531 pub fn validate_update_data(
2532 &self,
2533 data: &std::collections::HashMap<String, Value>,
2534 ) -> Result<(), BaseError> {
2535 self.validate_update_data_impl(data)
2536 }
2537
2538 #[cfg(not(test))]
2540 fn validate_update_data(
2541 &self,
2542 data: &std::collections::HashMap<String, Value>,
2543 ) -> Result<(), BaseError> {
2544 self.validate_update_data_impl(data)
2545 }
2546
2547 fn validate_update_data_impl(
2549 &self,
2550 data: &std::collections::HashMap<String, Value>,
2551 ) -> Result<(), BaseError> {
2552 if data.is_empty() {
2553 return Err(BaseError::ParamInvalid(
2554 "data".to_string(),
2555 "至少需要一个更新字段".to_string(),
2556 ));
2557 }
2558 for (field_name, value) in data {
2560 if self
2561 .tenant_scope
2562 .as_ref()
2563 .is_some_and(|(tenant_field, _)| tenant_field == field_name)
2564 {
2565 return Err(BaseError::PermissionDenied(format!(
2566 "禁止修改租户字段: {field_name}"
2567 )));
2568 }
2569 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
2571 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
2572 })?;
2573
2574 if !field_config.permissions.can_write(&self.user_roles_set) {
2576 return Err(BaseError::FieldPermissionDenied(
2577 self.table_config.table_name.clone(),
2578 field_name.clone(),
2579 "用户无写入权限".to_string(),
2580 ));
2581 }
2582
2583 field_config.validate(value)?;
2586 }
2587
2588 Ok(())
2589 }
2590
2591 #[cfg(test)]
2605 #[allow(private_interfaces)]
2606 pub fn build_update_sql(
2607 &self,
2608 data: &std::collections::HashMap<String, Value>,
2609 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2610 self.build_update_sql_impl(data)
2611 }
2612
2613 #[cfg(test)]
2615 fn build_update_sql_impl(
2616 &self,
2617 data: &std::collections::HashMap<String, Value>,
2618 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2619 if data.is_empty() {
2621 return Err(BaseError::ParamInvalid(
2622 "data".to_string(),
2623 "无可更新字段".to_string(),
2624 ));
2625 }
2626
2627 let need_timestamp = self
2629 .table_config
2630 .timestamp_fields
2631 .as_ref()
2632 .and_then(|ts| ts.updated_at.as_ref())
2633 .is_some_and(|updated_at| self.table_config.fields.contains_key(updated_at));
2634
2635 let mut owned_data;
2636 let working: &std::collections::HashMap<String, Value> = if need_timestamp {
2637 owned_data = data.clone();
2638 let ts = self.table_config.timestamp_fields.as_ref().unwrap();
2640 let updated_at = ts.updated_at.as_ref().unwrap();
2641 let now = chrono::Utc::now().timestamp();
2642 owned_data.insert(updated_at.clone(), Value::Number(now.into()));
2643 &owned_data
2644 } else {
2645 data
2646 };
2647
2648 let mut set_clauses = Vec::with_capacity(working.len());
2649 let mut params = Vec::with_capacity(working.len());
2650
2651 for (field_name, value) in working {
2653 if !self.table_config.fields.contains_key(field_name) {
2655 return Err(BaseError::FieldNotFound(
2656 self.table_config.table_name.clone(),
2657 field_name.clone(),
2658 ));
2659 }
2660
2661 let quoted = self.quote_identifier(field_name)?;
2663 set_clauses.push(format!("{} = ?", quoted));
2664 params.push(SqlParam::from_json(value)?);
2665 }
2666
2667 let mut sql = format!(
2669 "UPDATE {} SET {}",
2670 self.quoted_table_name()?,
2671 set_clauses.join(", ")
2672 );
2673
2674 if self.query_params.where_conditions.is_empty() {
2676 return Err(BaseError::MissingWhereClause("UPDATE".to_string()));
2677 }
2678
2679 self.append_where_to_sql(&mut sql, &mut params, false)?;
2681
2682 Ok((sql, params))
2683 }
2684
2685 pub async fn delete(self) -> Result<u64, BaseError> {
2730 if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2731 let data = self.with_updated_timestamp(std::collections::HashMap::from([(
2732 soft_delete_field.clone(),
2733 Value::Number(chrono::Utc::now().timestamp().into()),
2734 )]))?;
2735 return self
2736 .compile_db_query()?
2737 .update(&data)
2738 .await
2739 .map_err(BaseError::DatabaseExecuteFailed);
2740 }
2741 self.compile_db_query()?
2742 .delete()
2743 .await
2744 .map_err(BaseError::DatabaseExecuteFailed)
2745 }
2746
2747 pub async fn delete_in_tx(self, tx: &mut yang_db::Transaction) -> Result<u64, BaseError> {
2757 let query = tx.table(&self.table_config.table_ref);
2758 if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2759 let data = self.with_updated_timestamp(std::collections::HashMap::from([(
2760 soft_delete_field.clone(),
2761 Value::Number(chrono::Utc::now().timestamp().into()),
2762 )]))?;
2763 return self
2764 .apply_db_plan(query)?
2765 .update(&data)
2766 .await
2767 .map_err(BaseError::DatabaseExecuteFailed);
2768 }
2769 self.apply_db_plan(query)?
2770 .delete()
2771 .await
2772 .map_err(BaseError::DatabaseExecuteFailed)
2773 }
2774
2775 #[cfg(test)]
2785 #[allow(private_interfaces)]
2786 pub fn build_delete_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2787 self.build_delete_sql_impl()
2788 }
2789
2790 #[cfg(test)]
2792 #[allow(private_interfaces)]
2793 pub fn build_select_sql_for_test(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2794 self.build_select_sql(None)
2795 }
2796
2797 #[cfg(test)]
2802 #[allow(private_interfaces)]
2803 pub fn build_insert_sql_for_test(
2804 &self,
2805 data: std::collections::HashMap<String, Value>,
2806 ) -> Result<(String, Vec<SqlParam>), BaseError> {
2807 let prepared = self.prepare_and_validate_insert(data)?;
2808 self.build_insert_sql(&prepared)
2809 }
2810
2811 #[cfg(test)]
2813 fn build_delete_sql_impl(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2814 let mut sql = format!("DELETE FROM {}", self.quoted_table_name()?);
2816 let mut params = Vec::new();
2817
2818 if self.query_params.where_conditions.is_empty() {
2820 return Err(BaseError::MissingWhereClause("DELETE".to_string()));
2821 }
2822
2823 self.append_where_to_sql(&mut sql, &mut params, false)?;
2825
2826 Ok((sql, params))
2827 }
2828
2829 #[cfg(test)]
2839 pub(crate) async fn timed<F, R>(
2840 threshold: Option<std::time::Duration>,
2841 request_id: Option<crate::action::RequestId>,
2842 table: &str,
2843 op: &'static str,
2844 fut: F,
2845 ) -> R
2846 where
2847 F: std::future::Future<Output = R>,
2848 {
2849 let threshold = match threshold {
2851 Some(t) => t,
2852 None => return fut.await,
2853 };
2854 let start = std::time::Instant::now();
2855 let result = fut.await;
2856 let elapsed = start.elapsed();
2857 if elapsed >= threshold {
2858 let elapsed_ms = elapsed.as_secs_f64() * 1000.0;
2859 match request_id {
2860 Some(rid) => tracing::warn!(
2861 table = %table,
2862 op,
2863 elapsed_ms,
2864 request_id = %rid,
2865 "慢查询",
2866 ),
2867 None => tracing::warn!(table = %table, op, elapsed_ms, "慢查询"),
2868 }
2869 }
2870 result
2871 }
2872}
2873
2874#[cfg(all(test, feature = "mysql"))]
2878#[derive(Debug, Clone)]
2879#[cfg_attr(test, derive(PartialEq))]
2880#[allow(dead_code)] pub(crate) enum SqlParam {
2882 Null,
2884 Bool(bool),
2886 Int(i64),
2888 Uint(u64),
2890 Float(f64),
2892 String(String),
2894 DateTime(chrono::NaiveDateTime),
2896 Bytes(Vec<u8>),
2898 Json(serde_json::Value),
2900}
2901
2902#[cfg(all(test, feature = "mysql"))]
2903impl SqlParam {
2904 fn from_json(value: &Value) -> Result<Self, BaseError> {
2915 match value {
2916 Value::Null => Ok(SqlParam::Null),
2917 Value::Bool(b) => Ok(SqlParam::Bool(*b)),
2918 Value::Number(n) => {
2919 if let Some(i) = n.as_i64() {
2920 Ok(SqlParam::Int(i))
2921 } else if let Some(u) = n.as_u64() {
2922 Ok(SqlParam::Uint(u))
2924 } else if let Some(f) = n.as_f64() {
2925 Ok(SqlParam::Float(f))
2926 } else {
2927 Err(BaseError::DatabaseQueryFailed(
2928 yang_db::DbError::QueryError(format!("不支持的数字类型: {}", n)),
2929 ))
2930 }
2931 }
2932 Value::String(s) => {
2933 if let Ok(dt) = chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S")
2935 .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S"))
2936 .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S%.f"))
2937 {
2938 return Ok(SqlParam::DateTime(dt));
2939 }
2940 Ok(SqlParam::String(s.clone()))
2941 }
2942 Value::Array(_) => Ok(SqlParam::Json(value.clone())),
2943 Value::Object(_) => Ok(SqlParam::Json(value.clone())),
2944 }
2945 }
2946}
2947
2948#[cfg(all(test, feature = "mysql"))]
2949mod tests {
2950 use super::*;
2951 use std::sync::Arc;
2952
2953 fn test_config(table: crate::table::Table) -> Arc<TableConfig> {
2954 table.build().expect("测试表定义应有效").shared_config()
2955 }
2956
2957 fn test_query() -> TableQuery {
2958 let config = test_config(
2959 crate::table::Table::new("users")
2960 .fields([crate::table::Field::integer("id").required().primary_key()]),
2961 );
2962 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
2963 TableQuery::new(config, roles, None)
2964 }
2965
2966 #[test]
2967 fn test_insert_omits_database_generated_auto_increment_field() {
2968 let config = test_config(crate::table::Table::new("accounts").fields([
2969 crate::table::Field::id("id"),
2970 crate::table::Field::string("username", 64).required(),
2971 ]));
2972 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
2973 let query = TableQuery::new(config, roles, None);
2974 let data = std::collections::HashMap::from([(
2975 "username".to_string(),
2976 Value::String("alice".to_string()),
2977 )]);
2978
2979 let prepared = query
2980 .prepare_and_validate_insert(data)
2981 .expect("数据库生成的自增主键不应要求调用方提供");
2982
2983 assert!(!prepared.contains_key("id"));
2984
2985 let data_with_null_id = std::collections::HashMap::from([
2986 ("id".to_string(), Value::Null),
2987 ("username".to_string(), Value::String("bob".to_string())),
2988 ]);
2989 let prepared = query
2990 .prepare_and_validate_insert(data_with_null_id)
2991 .expect("null 自增主键应等价于未提供");
2992
2993 assert!(!prepared.contains_key("id"));
2994 }
2995
2996 #[test]
2997 fn tenant_scope_is_fail_closed_for_query_and_writes() {
2998 let config = test_config(
2999 crate::table::Table::new("tenant_rows").fields([
3000 crate::table::Field::id("id"),
3001 crate::table::Field::bigint("org_id")
3002 .required()
3003 .tenant_key(),
3004 crate::table::Field::string("name", 64).required(),
3005 ]),
3006 );
3007 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3008 let query = TableQuery::new(config, roles, None)
3009 .scope_tenant("org_id", serde_json::json!(7))
3010 .expect("tenant scope 应有效");
3011
3012 let (sql, params) = query.build_select_sql(None).expect("租户查询 SQL 应可构建");
3013 assert!(sql.contains("`org_id` = ?"));
3014 assert!(params.contains(&SqlParam::Int(7)));
3015
3016 let prepared = query
3017 .prepare_and_validate_insert(
3018 [("name".to_string(), serde_json::json!("row"))]
3019 .into_iter()
3020 .collect(),
3021 )
3022 .expect("租户字段应由上下文注入");
3023 assert_eq!(prepared.get("org_id"), Some(&serde_json::json!(7)));
3024
3025 let explicit_tenant = query.prepare_and_validate_insert(
3026 [
3027 ("name".to_string(), serde_json::json!("row")),
3028 ("org_id".to_string(), serde_json::json!(9)),
3029 ]
3030 .into_iter()
3031 .collect(),
3032 );
3033 assert!(matches!(
3034 explicit_tenant,
3035 Err(BaseError::PermissionDenied(_))
3036 ));
3037 }
3038
3039 #[test]
3040 fn test_insert_rejects_explicit_null_for_non_writable_field() {
3041 let config = test_config(crate::table::Table::new("accounts").fields([
3042 crate::table::Field::id("id"),
3043 crate::table::Field::string("username", 64).required(),
3044 crate::table::Field::string("internal_note", 255).not_writable(),
3045 ]));
3046 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3047 let query = TableQuery::new(config, roles, None);
3048 let data = std::collections::HashMap::from([
3049 ("username".to_string(), Value::String("alice".to_string())),
3050 ("internal_note".to_string(), Value::Null),
3051 ]);
3052
3053 let error = query
3054 .prepare_and_validate_insert(data)
3055 .expect_err("显式提交只读字段时,即使值为 null 也必须拒绝");
3056
3057 assert!(matches!(
3058 error,
3059 BaseError::FieldPermissionDenied(table, field, _)
3060 if table == "accounts" && field == "internal_note"
3061 ));
3062 }
3063
3064 #[test]
3065 fn test_page_rejects_page_size_above_production_limit() {
3066 let err = test_query()
3067 .page(1, 101)
3068 .expect_err("page_size 超过 100 应被拒绝");
3069
3070 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "page_size"));
3071 }
3072
3073 #[test]
3074 fn trusted_prefetch_limit_reaches_sql_without_public_page_cap() {
3075 let query = test_query()
3076 .prefetch_limit(10_001)
3077 .expect("可信树上限应允许 max_nodes + 1 探针");
3078 let (sql, _) = query.build_select_sql(None).expect("有界预取 SQL 应可构建");
3079
3080 assert!(sql.ends_with("LIMIT 10001 OFFSET 0"), "实际 SQL: {sql}");
3081 }
3082
3083 #[test]
3084 fn test_default_order_rejects_unsortable_field() {
3085 let config = test_config(
3086 crate::table::Table::new("users")
3087 .fields([
3088 crate::table::Field::id("id"),
3089 crate::table::Field::integer("secret_rank").not_sortable(),
3090 ])
3091 .default_order(crate::table::col("secret_rank").desc()),
3092 );
3093 let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3094 let query = TableQuery::new(config, roles, None);
3095
3096 let err = query
3097 .build_select_sql(None)
3098 .expect_err("默认排序不应绕过 sortable(false)");
3099
3100 assert!(
3101 matches!(err, BaseError::FieldPermissionDenied(table, field, _) if table == "users" && field == "secret_rank")
3102 );
3103 }
3104
3105 #[test]
3106 fn test_default_projection_excludes_unreadable_and_secret_fields() {
3107 let config = test_config(
3108 crate::table::Table::new("users").fields([
3109 crate::table::Field::integer("id").required().primary_key(),
3110 crate::table::Field::string("name", 64),
3111 crate::table::Field::string("restricted", 64).readable_by(["admin"]),
3112 crate::table::Field::string("password_hash", 255)
3113 .secret()
3114 .readable_by(["user"]),
3115 ]),
3116 );
3117 let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3118 let query = TableQuery::new(config, roles, None);
3119
3120 query
3121 .ensure_readable_projection()
3122 .expect("存在可读且非 secret 字段时默认投影应可用");
3123 let (sql, _) = query
3124 .build_select_sql(None)
3125 .expect("默认查询应只投影当前角色可读且非 secret 的字段");
3126
3127 assert_eq!(sql, "SELECT `id`, `name` FROM `users`");
3128 assert!(!sql.contains("restricted"));
3129 assert!(!sql.contains("password_hash"));
3130 }
3131
3132 #[test]
3133 fn test_select_projection_permission_matrix() {
3134 let all_readable = test_config(crate::table::Table::new("public_rows").fields([
3135 crate::table::Field::integer("id").required().primary_key(),
3136 crate::table::Field::string("name", 64),
3137 ]));
3138 let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3139 let (sql, _) = TableQuery::new(all_readable, Arc::clone(&roles), None)
3140 .build_select_sql(None)
3141 .expect("全部字段可读时默认投影应成功");
3142 assert_eq!(sql, "SELECT `id`, `name` FROM `public_rows`");
3143
3144 let partially_readable = test_config(
3145 crate::table::Table::new("mixed_rows").fields([
3146 crate::table::Field::integer("id").required().primary_key(),
3147 crate::table::Field::string("restricted", 64).readable_by(["admin"]),
3148 crate::table::Field::string("password_hash", 255)
3149 .secret()
3150 .readable_by(["user"]),
3151 ]),
3152 );
3153 let (partial_sql, _) =
3154 TableQuery::new(Arc::clone(&partially_readable), Arc::clone(&roles), None)
3155 .build_select_sql(None)
3156 .expect("部分字段受限时默认投影应保留可读字段");
3157 assert_eq!(partial_sql, "SELECT `id` FROM `mixed_rows`");
3158
3159 let explicit_err = TableQuery::new(partially_readable, Arc::clone(&roles), None)
3160 .select_fields(&["id", "restricted"])
3161 .expect_err("显式请求受限字段应被拒绝");
3162 assert!(
3163 matches!(explicit_err, BaseError::FieldPermissionDenied(table, field, _) if table == "mixed_rows" && field == "restricted")
3164 );
3165
3166 let none_readable = test_config(
3167 crate::table::Table::new("private_rows").fields([
3168 crate::table::Field::integer("alpha")
3169 .required()
3170 .primary_key()
3171 .readable_by(["admin"]),
3172 crate::table::Field::integer("beta").readable_by(["admin"]),
3173 ]),
3174 );
3175 let none_err = TableQuery::new(none_readable, roles, None)
3176 .build_select_sql(None)
3177 .expect_err("零字段可读时默认投影应 fail-closed");
3178 assert!(matches!(
3179 none_err,
3180 BaseError::FieldPermissionDenied(table, field, _) if table == "private_rows" && field == "*"
3181 ));
3182 }
3183
3184 #[test]
3185 fn test_default_projection_is_deterministic_and_excludes_hidden_fields() {
3186 for _ in 0..64 {
3187 let config = test_config(
3188 crate::table::Table::new("secrets").fields([
3189 crate::table::Field::id("id"),
3190 crate::table::Field::integer("z_secret").readable_by(["admin"]),
3191 crate::table::Field::integer("a_secret").readable_by(["admin"]),
3192 crate::table::Field::integer("m_secret")
3193 .secret()
3194 .readable_by(["user"]),
3195 ]),
3196 );
3197 let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3198 let query = TableQuery::new(config, roles, None);
3199
3200 let (sql, _) = query
3201 .build_select_sql(None)
3202 .expect("默认投影应保留公开字段");
3203 assert_eq!(sql, "SELECT `id` FROM `secrets`");
3204 }
3205 }
3206
3207 #[test]
3208 fn test_effective_pagination_applies_default_limit_to_data_query_sql() {
3209 let (query, page, page_size) = test_query()
3210 .with_effective_pagination()
3211 .expect("默认分页参数应合法");
3212
3213 assert_eq!(page, 1);
3214 assert_eq!(
3215 page_size,
3216 crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3217 );
3218
3219 let (sql, _) = query
3220 .build_select_sql(None)
3221 .expect("默认分页后的 SELECT SQL 应可构建");
3222
3223 assert!(
3224 sql.contains(&format!(
3225 " LIMIT {} OFFSET 0",
3226 crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3227 )),
3228 "分页数据查询必须包含默认 LIMIT,实际 SQL: {sql}"
3229 );
3230 }
3231}