Skip to main content

yang_base/table/
relation_loader.rs

1//! 关系字段批量加载:查询次数只与关系种类有关,不随结果行数增长。
2
3use super::Record;
4use crate::definition::FieldRef;
5use crate::error::BaseError;
6use async_trait::async_trait;
7use serde_json::Value;
8use std::collections::{BTreeMap, HashMap};
9
10/// 启动期校验完成的关系加载定义。
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct RelationSpec {
13    source: FieldRef,
14    target: FieldRef,
15    display: Vec<FieldRef>,
16    #[cfg(feature = "mysql")]
17    target_table_ref: yang_db::TableRef,
18    #[cfg(feature = "mysql")]
19    target_field_ref: yang_db::FieldRef,
20    #[cfg(feature = "mysql")]
21    display_field_refs: Vec<yang_db::FieldRef>,
22}
23
24impl RelationSpec {
25    /// 创建关系加载定义。
26    pub fn new(source: FieldRef, target: FieldRef) -> Self {
27        #[cfg(feature = "mysql")]
28        let target_table_ref =
29            yang_db::TableRef::__from_validated_owned(target.table().as_str().to_string());
30        #[cfg(feature = "mysql")]
31        let target_field_ref =
32            yang_db::FieldRef::__from_validated_owned(target.field().as_str().to_string());
33        Self {
34            source,
35            target,
36            display: Vec::new(),
37            #[cfg(feature = "mysql")]
38            target_table_ref,
39            #[cfg(feature = "mysql")]
40            target_field_ref,
41            #[cfg(feature = "mysql")]
42            display_field_refs: Vec::new(),
43        }
44    }
45
46    /// 设置目标展示字段。
47    pub fn display<I>(mut self, fields: I) -> Self
48    where
49        I: IntoIterator<Item = FieldRef>,
50    {
51        self.display = fields.into_iter().collect();
52        #[cfg(feature = "mysql")]
53        {
54            self.display_field_refs = self
55                .display
56                .iter()
57                .map(|field| {
58                    yang_db::FieldRef::__from_validated_owned(field.field().as_str().to_string())
59                })
60                .collect();
61        }
62        self
63    }
64
65    /// 返回源字段。
66    pub fn source(&self) -> &FieldRef {
67        &self.source
68    }
69
70    /// 返回目标关联键。
71    pub fn target(&self) -> &FieldRef {
72        &self.target
73    }
74
75    /// 返回目标展示字段。
76    pub fn display_fields(&self) -> &[FieldRef] {
77        &self.display
78    }
79}
80
81/// 基于当前 App Database 的默认 MySQL 批量关系执行器。
82#[cfg(feature = "mysql")]
83pub struct DatabaseRelationExecutor<'a> {
84    database: &'a yang_db::Database,
85}
86
87#[cfg(feature = "mysql")]
88impl<'a> DatabaseRelationExecutor<'a> {
89    /// 创建执行器。
90    pub const fn new(database: &'a yang_db::Database) -> Self {
91        Self { database }
92    }
93}
94
95#[cfg(feature = "mysql")]
96#[async_trait]
97impl RelationBatchExecutor for DatabaseRelationExecutor<'_> {
98    async fn load_batch(&self, batch: &RelationBatch) -> Result<Vec<Record>, BaseError> {
99        let spec = batch.spec();
100        let mut query = self
101            .database
102            .table(&spec.target_table_ref)
103            .field(&spec.target_field_ref);
104        for field in &spec.display_field_refs {
105            query = query.field(field);
106        }
107        query
108            .where_in(&spec.target_field_ref, batch.keys().to_vec())
109            .select::<Record>()
110            .await
111            .map_err(BaseError::DatabaseQueryFailed)
112    }
113}
114
115/// 单种关系的一次批量查询请求。
116#[derive(Debug, Clone)]
117pub struct RelationBatch {
118    spec: RelationSpec,
119    keys: Vec<Value>,
120}
121
122impl RelationBatch {
123    /// 返回关系定义。
124    pub fn spec(&self) -> &RelationSpec {
125        &self.spec
126    }
127
128    /// 返回去重后的关联键。
129    pub fn keys(&self) -> &[Value] {
130        &self.keys
131    }
132}
133
134/// 关系批次执行边界;数据库 Adapter 必须对一个 batch 只发起一次 IN 查询。
135#[async_trait]
136pub trait RelationBatchExecutor: Send + Sync {
137    /// 加载当前关系的全部目标记录。
138    async fn load_batch(&self, batch: &RelationBatch) -> Result<Vec<Record>, BaseError>;
139}
140
141/// 每个源字段对应的已批量加载记录。
142pub type RelationData = HashMap<String, Vec<Record>>;
143
144/// 预编译关系集合的批量加载器。
145#[derive(Debug, Clone, Default)]
146pub struct RelationLoader {
147    relations: Vec<RelationSpec>,
148}
149
150impl RelationLoader {
151    /// 创建批量加载器。
152    pub fn new(relations: Vec<RelationSpec>) -> Self {
153        Self { relations }
154    }
155
156    /// 从结果行收集并去重外键,每种关系最多形成一个 batch。
157    pub fn plan(&self, rows: &[Record]) -> Vec<RelationBatch> {
158        self.relations
159            .iter()
160            .filter_map(|relation| {
161                let mut values = BTreeMap::new();
162                for row in rows {
163                    let Some(value) = row.get(relation.source.field().as_str()) else {
164                        continue;
165                    };
166                    if value.is_null() {
167                        continue;
168                    }
169                    if let Ok(key) = serde_json::to_string(value) {
170                        values.entry(key).or_insert_with(|| value.clone());
171                    }
172                }
173                (!values.is_empty()).then(|| RelationBatch {
174                    spec: relation.clone(),
175                    keys: values.into_values().collect(),
176                })
177            })
178            .collect()
179    }
180
181    /// 执行批量加载;调用次数等于非空关系批次数,与输入行数无关。
182    pub async fn load<E>(&self, rows: &[Record], executor: &E) -> Result<RelationData, BaseError>
183    where
184        E: RelationBatchExecutor,
185    {
186        let mut data = HashMap::new();
187        for batch in self.plan(rows) {
188            let source = batch.spec.source().to_string();
189            data.insert(source, executor.load_batch(&batch).await?);
190        }
191        Ok(data)
192    }
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198    use crate::definition::{FieldName, TableName};
199    use std::sync::atomic::{AtomicUsize, Ordering};
200
201    fn field(table: &str, field: &str) -> FieldRef {
202        FieldRef::new(
203            TableName::new(table).expect("合法表名"),
204            FieldName::new(field).expect("合法字段名"),
205        )
206    }
207
208    struct CountingExecutor(AtomicUsize);
209
210    #[async_trait]
211    impl RelationBatchExecutor for CountingExecutor {
212        async fn load_batch(&self, _batch: &RelationBatch) -> Result<Vec<Record>, BaseError> {
213            self.0.fetch_add(1, Ordering::Relaxed);
214            Ok(Vec::new())
215        }
216    }
217
218    #[tokio::test]
219    async fn query_count_depends_on_relation_kinds_not_row_count() {
220        let loader = RelationLoader::new(vec![RelationSpec::new(
221            field("orders", "user_id"),
222            field("users", "id"),
223        )]);
224        let rows = (0..1_000)
225            .map(|index| Record::new().set("user_id", index % 10))
226            .collect::<Vec<_>>();
227        let executor = CountingExecutor(AtomicUsize::new(0));
228        let batches = loader.plan(&rows);
229        assert_eq!(batches.len(), 1);
230        assert_eq!(batches[0].keys().len(), 10);
231        loader
232            .load(&rows, &executor)
233            .await
234            .expect("批量关系加载应成功");
235        assert_eq!(executor.0.load(Ordering::Relaxed), 1);
236    }
237}