Skip to main content

yang_base/table/
tables.rs

1//! BR 心智连续的 Tables 深模块。
2
3#[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
14/// 树查询的默认节点上限,同时是 `TreeViewSpec::max_nodes` 的硬天花板(I-7/H7)。
15///
16/// 树查询需要把全部匹配行读入内存组装,无分页保护;该常量限制单次树查询
17/// 可处理的节点数,超出即报错。View 只能在此上限之内下调,不能把查询
18/// LIMIT 抬成无界。
19pub const DEFAULT_TREE_MAX_NODES: usize = 10_000;
20
21/// 树的最大嵌套深度(H7)。
22///
23/// 节点数上限约束总量,深度上限约束单棵子树的规模。[`Tables::build_tree`] 用显式
24/// 工作栈而非递归组装,栈占用由节点数决定,因此本上限是纯防御性上界(拒绝病态输入)
25/// 而不是防栈溢出的唯一依赖。
26pub const DEFAULT_TREE_MAX_DEPTH: usize = 1_024;
27
28/// 校验树查询节点数未超过上限;超限返回 `ParamInvalid`,提示调用方先收窄筛选。
29#[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
40/// 校验树嵌套深度未超过上限;超限返回 `ParamInvalid`,提示调用方先收窄筛选。
41///
42/// `build_tree` 是公开 API,守卫必须落在组装过程内部(逐层校验),否则外部调用者
43/// 仍会暴露在风险中。
44fn 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/// 带批量关系数据的稳定列表响应。
55#[derive(Debug, Clone, serde::Serialize)]
56pub struct TableListResult {
57    /// 分页主数据。
58    pub page: PaginatedResult<Record>,
59    /// 按源字段分组的批量关系记录。
60    pub relations: RelationData,
61}
62
63/// `table_tree` 的稳定树节点响应。
64#[derive(Debug, Clone, serde::Serialize)]
65pub struct TableTreeNode {
66    /// 当前节点原始列。
67    #[serde(flatten)]
68    pub record: Record,
69    /// 子节点,保持数据库结果中的相对顺序。
70    pub children: Vec<TableTreeNode>,
71}
72
73/// 统一封装列表参数、View 字段、分页与关系批量加载。
74#[derive(Debug, Clone)]
75pub struct Tables {
76    query: TableQuery,
77    relation_loader: RelationLoader,
78}
79
80impl Tables {
81    /// 从已经绑定权限和租户范围的 TableQuery 创建。
82    pub fn new(query: TableQuery) -> Self {
83        Self {
84            query,
85            relation_loader: RelationLoader::default(),
86        }
87    }
88
89    /// 应用启动期预编译的 View 字段。
90    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    /// 配置启动期预编译的关系批量加载器。
106    pub fn relations(mut self, loader: RelationLoader) -> Self {
107        self.relation_loader = loader;
108        self
109    }
110
111    /// 应用通用筛选条件;空集合是恒真条件,不改变现有查询范围。
112    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    /// 在定义允许搜索的文本字段上应用关键词。
121    pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
122        self.query = self.query.search(keyword)?;
123        Ok(self)
124    }
125
126    /// 应用受权限保护的排序。
127    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    /// 应用分页。
133    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    /// 一次性应用标准 QueryParams。
139    pub fn params(mut self, params: QueryParams) -> Result<Self, BaseError> {
140        self.query = self.query.apply_params(params)?;
141        Ok(self)
142    }
143
144    /// 返回标准列表参数默认值。
145    pub fn params_table() -> QueryParams {
146        QueryParams::new().with_pagination(1, DEFAULT_QUERY_PAGE_SIZE)
147    }
148
149    /// 执行标准分页列表。
150    #[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    /// 执行选择器数据查询。
156    ///
157    /// 底层 `all()` 一次性读取全部匹配行,**不受** TableQuery 最大分页限制保护;
158    /// 调用方必须先通过 where/search 条件把结果规模约束在内存可承载范围内。
159    #[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    /// 查询全量选择结果并按默认 `id` / `parent_id` 组装树。
165    ///
166    /// 节点数受 [`DEFAULT_TREE_MAX_NODES`] 限制,超出即报错;需要自定义上限的
167    /// 树 View 应使用 [`Tables::table_tree_view`] 并在 `TreeViewSpec` 中配置。
168    #[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    /// 按启动期已校验的 View 树拓扑查询并组装节点。
179    ///
180    /// 节点数上限取 `TreeViewSpec::max_nodes`(缺省 [`DEFAULT_TREE_MAX_NODES`]),
181    /// 超出即报错,避免全表无界读入内存。
182    #[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    /// 将已查询记录组装为树;关系键只用于内存索引,不进入 SQL。
205    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        // 显式工作栈后序遍历(H7):调用栈占用恒为常数,结果缓冲放在堆上,
244        // 因此任意输入(含 N 层线性链)都不会爆栈——树深不再是栈占用的量纲。
245        let mut stack: Vec<TreeBuildFrame> = roots
246            .iter()
247            .rev()
248            .map(|&index| TreeBuildFrame::Enter { index, depth: 1 })
249            .collect();
250        // 展开中的节点:自身索引、已取走的记录、按顺序累积的已完成子树。
251        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                    // 逆序压栈,保证子节点按数据库结果顺序展开。
266                    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                    // 栈顶仍是父节点时收拢到它,否则本节点即根节点。
285                    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    /// 执行分页列表并按关系种类批量加载展示数据。
299    #[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
317/// [`Tables::build_tree`] 后序遍历的工作栈帧。
318enum TreeBuildFrame {
319    /// 进入节点:校验深度与环、取走记录,并把子节点与 `Leave` 压栈。
320    Enter { index: usize, depth: usize },
321    /// 离开节点:子树已按顺序收拢完成,组装自身并挂到父节点。
322    Leave { index: usize },
323}
324
325/// 工作栈与结果缓冲失衡的错误构造(内部不变量被破坏,属配置/实现错误)。
326fn work_stack_error() -> BaseError {
327    BaseError::ConfigError("树构建工作栈与结果不符".to_string())
328}
329
330#[cfg(test)]
331mod tests {
332    use super::*;
333
334    /// 构造 `len` 个节点的线性链:`id = i`、`parent_id = i - 1`,仅 0 号为根。
335    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    /// 逐层下探线性链的实际深度。
351    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        // 边界:恰好等于上限放行。
364        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        // 显式配置的小上限同样生效。
376        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        // 边界:恰好等于上限放行。
422        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    /// H7 回归:线性链在节点数上限之内就能把递归调用栈耗尽。修复前该输入会
435    /// 直接 abort(栈溢出),而不是返回可处理的错误。
436    #[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    /// H7 边界:深度恰好等于上限的线性链必须组装成功——组装走显式工作栈,
447    /// 调用栈占用不随树深增长,因此这种输入在默认线程栈上也能安全完成。
448    #[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}