1#[cfg(any(feature = "mysql", feature = "postgres"))]
4use super::RelationBatchExecutor;
5use super::{
6 PaginatedResult, QueryParams, Record, RelationData, RelationLoader, SortOrder, TableQuery,
7 WhereCondition, DEFAULT_QUERY_PAGE_SIZE,
8};
9use crate::definition::CompiledTableView;
10use crate::error::BaseError;
11use serde_json::Value;
12use std::collections::{HashMap, HashSet};
13
14pub const DEFAULT_TREE_MAX_NODES: usize = 10_000;
20
21pub const DEFAULT_TREE_MAX_DEPTH: usize = 1_024;
27
28#[cfg(any(feature = "mysql", feature = "postgres", test))]
30fn ensure_tree_node_cap(count: usize, max_nodes: usize) -> Result<(), BaseError> {
31 if count > max_nodes {
32 return Err(BaseError::ParamInvalid(
33 "tree".to_string(),
34 format!("树节点数 {count} 超过上限 {max_nodes},请先收窄查询范围"),
35 ));
36 }
37 Ok(())
38}
39
40fn ensure_tree_depth_cap(depth: usize, max_depth: usize) -> Result<(), BaseError> {
45 if depth > max_depth {
46 return Err(BaseError::ParamInvalid(
47 "tree".to_string(),
48 format!("树嵌套深度 {depth} 超过上限 {max_depth},请先收窄查询范围"),
49 ));
50 }
51 Ok(())
52}
53
54#[derive(Debug, Clone, serde::Serialize)]
56pub struct TableListResult {
57 pub page: PaginatedResult<Record>,
59 pub relations: RelationData,
61}
62
63#[derive(Debug, Clone, serde::Serialize)]
65pub struct TableTreeNode {
66 #[serde(flatten)]
68 pub record: Record,
69 pub children: Vec<TableTreeNode>,
71}
72
73#[derive(Debug, Clone)]
75pub struct Tables {
76 query: TableQuery,
77 relation_loader: RelationLoader,
78}
79
80impl Tables {
81 pub fn new(query: TableQuery) -> Self {
83 Self {
84 query,
85 relation_loader: RelationLoader::default(),
86 }
87 }
88
89 pub fn view(mut self, view: &CompiledTableView) -> Result<Self, BaseError> {
91 let fields = view
92 .fields()
93 .iter()
94 .map(|field| {
95 field
96 .as_str()
97 .rsplit_once('.')
98 .map_or(field.as_str(), |(_, name)| name)
99 })
100 .collect::<Vec<_>>();
101 self.query = self.query.select_fields(&fields)?;
102 Ok(self)
103 }
104
105 pub fn relations(mut self, loader: RelationLoader) -> Self {
107 self.relation_loader = loader;
108 self
109 }
110
111 pub fn where_from(mut self, conditions: &[WhereCondition]) -> Result<Self, BaseError> {
113 if conditions.is_empty() {
114 return Ok(self);
115 }
116 self.query = self.query.where_and(conditions.to_vec())?;
117 Ok(self)
118 }
119
120 pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
122 self.query = self.query.search(keyword)?;
123 Ok(self)
124 }
125
126 pub fn order(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
128 self.query = self.query.order_by(field, order)?;
129 Ok(self)
130 }
131
132 pub fn page(mut self, page: usize, limit: usize) -> Result<Self, BaseError> {
134 self.query = self.query.page(page, limit)?;
135 Ok(self)
136 }
137
138 pub fn params(mut self, params: QueryParams) -> Result<Self, BaseError> {
140 self.query = self.query.apply_params(params)?;
141 Ok(self)
142 }
143
144 pub fn params_table() -> QueryParams {
146 QueryParams::new().with_pagination(1, DEFAULT_QUERY_PAGE_SIZE)
147 }
148
149 #[cfg(any(feature = "mysql", feature = "postgres"))]
151 pub async fn table_list(self) -> Result<PaginatedResult<Record>, BaseError> {
152 self.query.paginate_records().await
153 }
154
155 #[cfg(any(feature = "mysql", feature = "postgres"))]
160 pub async fn table_select(self) -> Result<Vec<Record>, BaseError> {
161 self.query.all().await
162 }
163
164 #[cfg(any(feature = "mysql", feature = "postgres"))]
169 pub async fn table_tree(self) -> Result<Vec<TableTreeNode>, BaseError> {
170 let read_limit = DEFAULT_TREE_MAX_NODES
171 .checked_add(1)
172 .ok_or_else(|| BaseError::ConfigError("默认树节点上限无法计算截断探针".to_string()))?;
173 let rows = self.query.prefetch_limit(read_limit)?.all().await?;
174 ensure_tree_node_cap(rows.len(), DEFAULT_TREE_MAX_NODES)?;
175 Self::build_tree(rows, "id", "parent_id")
176 }
177
178 #[cfg(any(feature = "mysql", feature = "postgres"))]
183 pub async fn table_tree_view(
184 self,
185 view: &CompiledTableView,
186 ) -> Result<Vec<TableTreeNode>, BaseError> {
187 let tree = view
188 .tree()
189 .ok_or_else(|| BaseError::ConfigError(format!("View {} 未声明树拓扑", view.name())))?;
190 let max_nodes = tree.max_nodes();
191 let read_limit = max_nodes.checked_add(1).ok_or_else(|| {
192 BaseError::ConfigError(format!("View {} 的树节点上限过大", view.name()))
193 })?;
194 let rows = self
195 .view(view)?
196 .query
197 .prefetch_limit(read_limit)?
198 .all()
199 .await?;
200 ensure_tree_node_cap(rows.len(), max_nodes)?;
201 Self::build_tree(rows, tree.id_field_name(), tree.parent_field_name())
202 }
203
204 pub fn build_tree(
206 rows: Vec<Record>,
207 id_field: &str,
208 parent_field: &str,
209 ) -> Result<Vec<TableTreeNode>, BaseError> {
210 let mut ids = HashMap::with_capacity(rows.len());
211 for (index, row) in rows.iter().enumerate() {
212 let id = row.get(id_field).ok_or_else(|| {
213 BaseError::ParamInvalid(id_field.to_string(), "树节点缺少主键".to_string())
214 })?;
215 if id.is_null() {
216 return Err(BaseError::ParamInvalid(
217 id_field.to_string(),
218 "树节点主键不能为 null".to_string(),
219 ));
220 }
221 if ids.insert(value_key(id), index).is_some() {
222 return Err(BaseError::ConfigError(format!(
223 "树节点主键重复: {id_field}={id}"
224 )));
225 }
226 }
227
228 let mut children = vec![Vec::new(); rows.len()];
229 let mut roots = Vec::new();
230 for (index, row) in rows.iter().enumerate() {
231 let parent = row.get(parent_field).unwrap_or(&Value::Null);
232 if parent.is_null() {
233 roots.push(index);
234 } else if let Some(parent_index) = ids.get(&value_key(parent)).copied() {
235 children[parent_index].push(index);
236 } else {
237 roots.push(index);
238 }
239 }
240
241 let mut rows = rows.into_iter().map(Some).collect::<Vec<_>>();
242 let mut visiting = HashSet::new();
243 let mut stack: Vec<TreeBuildFrame> = roots
246 .iter()
247 .rev()
248 .map(|&index| TreeBuildFrame::Enter { index, depth: 1 })
249 .collect();
250 let mut pending: Vec<(usize, Record, Vec<TableTreeNode>)> = Vec::new();
252 let mut nodes = Vec::with_capacity(roots.len());
253 while let Some(frame) = stack.pop() {
254 match frame {
255 TreeBuildFrame::Enter { index, depth } => {
256 ensure_tree_depth_cap(depth, DEFAULT_TREE_MAX_DEPTH)?;
257 if !visiting.insert(index) {
258 return Err(BaseError::ConfigError("树关系包含循环".to_string()));
259 }
260 let record = rows[index]
261 .take()
262 .ok_or_else(|| BaseError::ConfigError("树节点被重复引用".to_string()))?;
263 pending.push((index, record, Vec::new()));
264 stack.push(TreeBuildFrame::Leave { index });
265 stack.extend(children[index].iter().rev().map(|&child| {
267 TreeBuildFrame::Enter {
268 index: child,
269 depth: depth + 1,
270 }
271 }));
272 }
273 TreeBuildFrame::Leave { index } => {
274 visiting.remove(&index);
275 let (owner, record, child_nodes) =
276 pending.pop().ok_or_else(work_stack_error)?;
277 if owner != index {
278 return Err(work_stack_error());
279 }
280 let node = TableTreeNode {
281 record,
282 children: child_nodes,
283 };
284 match pending.last_mut() {
286 Some((_, _, siblings)) => siblings.push(node),
287 None => nodes.push(node),
288 }
289 }
290 }
291 }
292 if rows.iter().any(Option::is_some) {
293 return Err(BaseError::ConfigError("树关系包含循环".to_string()));
294 }
295 Ok(nodes)
296 }
297
298 #[cfg(any(feature = "mysql", feature = "postgres"))]
300 pub async fn table_list_with_relations<E>(
301 self,
302 executor: &E,
303 ) -> Result<TableListResult, BaseError>
304 where
305 E: RelationBatchExecutor,
306 {
307 let page = self.query.paginate_records().await?;
308 let relations = self.relation_loader.load(&page.data, executor).await?;
309 Ok(TableListResult { page, relations })
310 }
311}
312
313fn value_key(value: &Value) -> String {
314 serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
315}
316
317enum TreeBuildFrame {
319 Enter { index: usize, depth: usize },
321 Leave { index: usize },
323}
324
325fn work_stack_error() -> BaseError {
327 BaseError::ConfigError("树构建工作栈与结果不符".to_string())
328}
329
330#[cfg(test)]
331mod tests {
332 use super::*;
333
334 fn linear_chain(len: usize) -> Vec<Record> {
336 (0..len)
337 .map(|index| {
338 Record::new().set("id", index).set(
339 "parent_id",
340 if index == 0 {
341 Value::Null
342 } else {
343 serde_json::json!(index - 1)
344 },
345 )
346 })
347 .collect()
348 }
349
350 fn chain_depth(tree: &[TableTreeNode]) -> usize {
352 let mut depth = 0;
353 let mut cursor = tree.first();
354 while let Some(node) = cursor {
355 depth += 1;
356 cursor = node.children.first();
357 }
358 depth
359 }
360
361 #[test]
362 fn tree_node_cap_rejects_overflow() {
363 ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES, DEFAULT_TREE_MAX_NODES)
365 .expect("节点数等于上限应放行");
366 ensure_tree_node_cap(3, 10).expect("节点数低于上限应放行");
367
368 let error = ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES + 1, DEFAULT_TREE_MAX_NODES)
369 .expect_err("节点数超过上限必须报错");
370 assert!(
371 matches!(error, BaseError::ParamInvalid(_, _)),
372 "树节点超限应返回 ParamInvalid: {error:?}"
373 );
374
375 let error = ensure_tree_node_cap(11, 10).expect_err("自定义上限超限必须报错");
377 assert!(matches!(error, BaseError::ParamInvalid(_, _)));
378 }
379
380 #[test]
381 fn tree_builder_keeps_order_and_nests_children() {
382 let rows = vec![
383 Record::new().set("id", 1).set("parent_id", Value::Null),
384 Record::new().set("id", 2).set("parent_id", 1),
385 ];
386 let tree = Tables::build_tree(rows, "id", "parent_id").expect("树关系应有效");
387 assert_eq!(tree.len(), 1);
388 assert_eq!(tree[0].children.len(), 1);
389 assert_eq!(
390 tree[0].children[0].record.get("id"),
391 Some(&serde_json::json!(2))
392 );
393 }
394
395 #[test]
396 fn tree_builder_rejects_null_and_duplicate_ids() {
397 let null_id = Tables::build_tree(
398 vec![Record::new()
399 .set("id", Value::Null)
400 .set("parent_id", Value::Null)],
401 "id",
402 "parent_id",
403 )
404 .expect_err("null 主键必须失败");
405 assert!(matches!(null_id, BaseError::ParamInvalid(_, _)));
406
407 let duplicate = Tables::build_tree(
408 vec![
409 Record::new().set("id", 1).set("parent_id", Value::Null),
410 Record::new().set("id", 1).set("parent_id", Value::Null),
411 ],
412 "id",
413 "parent_id",
414 )
415 .expect_err("重复主键必须失败");
416 assert!(matches!(duplicate, BaseError::ConfigError(_)));
417 }
418
419 #[test]
420 fn tree_depth_cap_rejects_overflow() {
421 ensure_tree_depth_cap(DEFAULT_TREE_MAX_DEPTH, DEFAULT_TREE_MAX_DEPTH)
423 .expect("深度等于上限应放行");
424 ensure_tree_depth_cap(3, 10).expect("深度低于上限应放行");
425
426 let error = ensure_tree_depth_cap(DEFAULT_TREE_MAX_DEPTH + 1, DEFAULT_TREE_MAX_DEPTH)
427 .expect_err("深度超过上限必须报错");
428 assert!(
429 matches!(error, BaseError::ParamInvalid(_, _)),
430 "树深度超限应返回 ParamInvalid: {error:?}"
431 );
432 }
433
434 #[test]
437 fn tree_builder_rejects_linear_chain_deeper_than_cap() {
438 let error = Tables::build_tree(linear_chain(2_000), "id", "parent_id")
439 .expect_err("超深线性链必须报错而不是爆栈");
440 assert!(
441 matches!(error, BaseError::ParamInvalid(_, _)),
442 "超深线性链应返回 ParamInvalid: {error:?}"
443 );
444 }
445
446 #[test]
449 fn tree_builder_accepts_linear_chain_at_depth_cap() {
450 let tree = Tables::build_tree(linear_chain(DEFAULT_TREE_MAX_DEPTH), "id", "parent_id")
451 .expect("等于深度上限的线性链应组装成功");
452 assert_eq!(tree.len(), 1, "线性链只应有一个根节点");
453 assert_eq!(chain_depth(&tree), DEFAULT_TREE_MAX_DEPTH);
454 }
455
456 #[test]
457 fn tree_builder_rejects_cycles_without_roots() {
458 let cycle = Tables::build_tree(
459 vec![
460 Record::new().set("id", 1).set("parent_id", 2),
461 Record::new().set("id", 2).set("parent_id", 1),
462 ],
463 "id",
464 "parent_id",
465 )
466 .expect_err("无根循环必须失败");
467 assert!(matches!(cycle, BaseError::ConfigError(_)));
468 }
469}