1#[cfg(feature = "mysql")]
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;
19
20#[cfg(any(feature = "mysql", test))]
22fn ensure_tree_node_cap(count: usize, max_nodes: usize) -> Result<(), BaseError> {
23 if count > max_nodes {
24 return Err(BaseError::ParamInvalid(
25 "tree".to_string(),
26 format!("树节点数 {count} 超过上限 {max_nodes},请先收窄查询范围"),
27 ));
28 }
29 Ok(())
30}
31
32#[derive(Debug, Clone, serde::Serialize)]
34pub struct TableListResult {
35 pub page: PaginatedResult<Record>,
37 pub relations: RelationData,
39}
40
41#[derive(Debug, Clone, serde::Serialize)]
43pub struct TableTreeNode {
44 #[serde(flatten)]
46 pub record: Record,
47 pub children: Vec<TableTreeNode>,
49}
50
51#[derive(Debug, Clone)]
53pub struct Tables {
54 query: TableQuery,
55 relation_loader: RelationLoader,
56}
57
58impl Tables {
59 pub fn new(query: TableQuery) -> Self {
61 Self {
62 query,
63 relation_loader: RelationLoader::default(),
64 }
65 }
66
67 pub fn view(mut self, view: &CompiledTableView) -> Result<Self, BaseError> {
69 let fields = view
70 .fields()
71 .iter()
72 .map(|field| {
73 field
74 .as_str()
75 .rsplit_once('.')
76 .map_or(field.as_str(), |(_, name)| name)
77 })
78 .collect::<Vec<_>>();
79 self.query = self.query.select_fields(&fields)?;
80 Ok(self)
81 }
82
83 pub fn relations(mut self, loader: RelationLoader) -> Self {
85 self.relation_loader = loader;
86 self
87 }
88
89 pub fn where_from(mut self, conditions: &[WhereCondition]) -> Result<Self, BaseError> {
91 if conditions.is_empty() {
92 return Ok(self);
93 }
94 self.query = self.query.where_and(conditions.to_vec())?;
95 Ok(self)
96 }
97
98 pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
100 self.query = self.query.search(keyword)?;
101 Ok(self)
102 }
103
104 pub fn order(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
106 self.query = self.query.order_by(field, order)?;
107 Ok(self)
108 }
109
110 pub fn page(mut self, page: usize, limit: usize) -> Result<Self, BaseError> {
112 self.query = self.query.page(page, limit)?;
113 Ok(self)
114 }
115
116 pub fn params(mut self, params: QueryParams) -> Result<Self, BaseError> {
118 self.query = self.query.apply_params(params)?;
119 Ok(self)
120 }
121
122 pub fn params_table() -> QueryParams {
124 QueryParams::new().with_pagination(1, DEFAULT_QUERY_PAGE_SIZE)
125 }
126
127 #[cfg(feature = "mysql")]
129 pub async fn table_list(self) -> Result<PaginatedResult<Record>, BaseError> {
130 self.query.paginate_records().await
131 }
132
133 #[cfg(feature = "mysql")]
138 pub async fn table_select(self) -> Result<Vec<Record>, BaseError> {
139 self.query.all().await
140 }
141
142 #[cfg(feature = "mysql")]
147 pub async fn table_tree(self) -> Result<Vec<TableTreeNode>, BaseError> {
148 let read_limit = DEFAULT_TREE_MAX_NODES
149 .checked_add(1)
150 .ok_or_else(|| BaseError::ConfigError("默认树节点上限无法计算截断探针".to_string()))?;
151 let rows = self.query.prefetch_limit(read_limit)?.all().await?;
152 ensure_tree_node_cap(rows.len(), DEFAULT_TREE_MAX_NODES)?;
153 Self::build_tree(rows, "id", "parent_id")
154 }
155
156 #[cfg(feature = "mysql")]
161 pub async fn table_tree_view(
162 self,
163 view: &CompiledTableView,
164 ) -> Result<Vec<TableTreeNode>, BaseError> {
165 let tree = view
166 .tree()
167 .ok_or_else(|| BaseError::ConfigError(format!("View {} 未声明树拓扑", view.name())))?;
168 let max_nodes = tree.max_nodes();
169 let read_limit = max_nodes.checked_add(1).ok_or_else(|| {
170 BaseError::ConfigError(format!("View {} 的树节点上限过大", view.name()))
171 })?;
172 let rows = self
173 .view(view)?
174 .query
175 .prefetch_limit(read_limit)?
176 .all()
177 .await?;
178 ensure_tree_node_cap(rows.len(), max_nodes)?;
179 Self::build_tree(rows, tree.id_field_name(), tree.parent_field_name())
180 }
181
182 pub fn build_tree(
184 rows: Vec<Record>,
185 id_field: &str,
186 parent_field: &str,
187 ) -> Result<Vec<TableTreeNode>, BaseError> {
188 let mut ids = HashMap::with_capacity(rows.len());
189 for (index, row) in rows.iter().enumerate() {
190 let id = row.get(id_field).ok_or_else(|| {
191 BaseError::ParamInvalid(id_field.to_string(), "树节点缺少主键".to_string())
192 })?;
193 if id.is_null() {
194 return Err(BaseError::ParamInvalid(
195 id_field.to_string(),
196 "树节点主键不能为 null".to_string(),
197 ));
198 }
199 if ids.insert(value_key(id), index).is_some() {
200 return Err(BaseError::ConfigError(format!(
201 "树节点主键重复: {id_field}={id}"
202 )));
203 }
204 }
205
206 let mut children = vec![Vec::new(); rows.len()];
207 let mut roots = Vec::new();
208 for (index, row) in rows.iter().enumerate() {
209 let parent = row.get(parent_field).unwrap_or(&Value::Null);
210 if parent.is_null() {
211 roots.push(index);
212 } else if let Some(parent_index) = ids.get(&value_key(parent)).copied() {
213 children[parent_index].push(index);
214 } else {
215 roots.push(index);
216 }
217 }
218
219 let mut rows = rows.into_iter().map(Some).collect::<Vec<_>>();
220 let mut visiting = HashSet::new();
221 let nodes = roots
222 .into_iter()
223 .map(|index| build_node(index, &mut rows, &children, &mut visiting))
224 .collect::<Result<Vec<_>, _>>()?;
225 if rows.iter().any(Option::is_some) {
226 return Err(BaseError::ConfigError("树关系包含循环".to_string()));
227 }
228 Ok(nodes)
229 }
230
231 #[cfg(feature = "mysql")]
233 pub async fn table_list_with_relations<E>(
234 self,
235 executor: &E,
236 ) -> Result<TableListResult, BaseError>
237 where
238 E: RelationBatchExecutor,
239 {
240 let page = self.query.paginate_records().await?;
241 let relations = self.relation_loader.load(&page.data, executor).await?;
242 Ok(TableListResult { page, relations })
243 }
244}
245
246fn value_key(value: &Value) -> String {
247 serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
248}
249
250fn build_node(
251 index: usize,
252 rows: &mut [Option<Record>],
253 children: &[Vec<usize>],
254 visiting: &mut HashSet<usize>,
255) -> Result<TableTreeNode, BaseError> {
256 if !visiting.insert(index) {
257 return Err(BaseError::ConfigError("树关系包含循环".to_string()));
258 }
259 let record = rows[index]
260 .take()
261 .ok_or_else(|| BaseError::ConfigError("树节点被重复引用".to_string()))?;
262 let nodes = children[index]
263 .iter()
264 .copied()
265 .map(|child| build_node(child, rows, children, visiting))
266 .collect::<Result<Vec<_>, _>>()?;
267 visiting.remove(&index);
268 Ok(TableTreeNode {
269 record,
270 children: nodes,
271 })
272}
273
274#[cfg(test)]
275mod tests {
276 use super::*;
277
278 #[test]
279 fn tree_node_cap_rejects_overflow() {
280 ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES, DEFAULT_TREE_MAX_NODES)
282 .expect("节点数等于上限应放行");
283 ensure_tree_node_cap(3, 10).expect("节点数低于上限应放行");
284
285 let error = ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES + 1, DEFAULT_TREE_MAX_NODES)
286 .expect_err("节点数超过上限必须报错");
287 assert!(
288 matches!(error, BaseError::ParamInvalid(_, _)),
289 "树节点超限应返回 ParamInvalid: {error:?}"
290 );
291
292 let error = ensure_tree_node_cap(11, 10).expect_err("自定义上限超限必须报错");
294 assert!(matches!(error, BaseError::ParamInvalid(_, _)));
295 }
296
297 #[test]
298 fn tree_builder_keeps_order_and_nests_children() {
299 let rows = vec![
300 Record::new().set("id", 1).set("parent_id", Value::Null),
301 Record::new().set("id", 2).set("parent_id", 1),
302 ];
303 let tree = Tables::build_tree(rows, "id", "parent_id").expect("树关系应有效");
304 assert_eq!(tree.len(), 1);
305 assert_eq!(tree[0].children.len(), 1);
306 assert_eq!(
307 tree[0].children[0].record.get("id"),
308 Some(&serde_json::json!(2))
309 );
310 }
311
312 #[test]
313 fn tree_builder_rejects_null_and_duplicate_ids() {
314 let null_id = Tables::build_tree(
315 vec![Record::new()
316 .set("id", Value::Null)
317 .set("parent_id", Value::Null)],
318 "id",
319 "parent_id",
320 )
321 .expect_err("null 主键必须失败");
322 assert!(matches!(null_id, BaseError::ParamInvalid(_, _)));
323
324 let duplicate = Tables::build_tree(
325 vec![
326 Record::new().set("id", 1).set("parent_id", Value::Null),
327 Record::new().set("id", 1).set("parent_id", Value::Null),
328 ],
329 "id",
330 "parent_id",
331 )
332 .expect_err("重复主键必须失败");
333 assert!(matches!(duplicate, BaseError::ConfigError(_)));
334 }
335
336 #[test]
337 fn tree_builder_rejects_cycles_without_roots() {
338 let cycle = Tables::build_tree(
339 vec![
340 Record::new().set("id", 1).set("parent_id", 2),
341 Record::new().set("id", 2).set("parent_id", 1),
342 ],
343 "id",
344 "parent_id",
345 )
346 .expect_err("无根循环必须失败");
347 assert!(matches!(cycle, BaseError::ConfigError(_)));
348 }
349}