Skip to main content

yang_base/definition/builder/
app.rs

1//! BuiltApp 冻结定义与 AppBuilder 构建编排。
2
3use crate::action::{ActionContext, ApiResponse, Request};
4use crate::definition::{AddonSpec, BuildError};
5use crate::error::BaseError;
6use crate::table::TableDefinition;
7use crate::tools::Tools;
8use std::fmt;
9use std::sync::Arc;
10
11use super::catalog::DefinitionCatalog;
12use super::compile::{
13    build_registry, compile_runtime_modules, compile_runtime_table_views,
14    compile_table_definitions, compile_views,
15};
16use super::handle::ActionHandle;
17use super::registry::Registry;
18use super::validate::{
19    collect_actions, collect_fields, collect_views, resolve_param_fields, sort_definitions,
20    validate_dependencies, validate_middleware_order, validate_module_contents,
21    validate_module_ownership, validate_references, validate_routes, validate_unique_addons,
22    validate_unique_modules,
23};
24
25/// 构建完成且运行期不可变的 App 定义。
26#[derive(Clone)]
27pub struct BuiltApp {
28    catalog: DefinitionCatalog,
29    registry: Arc<Registry>,
30    tools: Arc<Tools>,
31    table_definitions: Vec<TableDefinition>,
32    compiled_views: Vec<crate::definition::CompiledTableView>,
33}
34
35impl fmt::Debug for BuiltApp {
36    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
37        formatter
38            .debug_struct("BuiltApp")
39            .field("catalog", &self.catalog)
40            .field("registry", &self.registry)
41            .field("tools", &self.tools)
42            .field("table_definition_count", &self.table_definitions.len())
43            .field("compiled_view_count", &self.compiled_views.len())
44            .finish()
45    }
46}
47
48impl BuiltApp {
49    /// 返回只读定义 Catalog。
50    pub fn catalog(&self) -> &DefinitionCatalog {
51        &self.catalog
52    }
53
54    /// 返回预解析 Registry。
55    pub fn registry(&self) -> &Registry {
56        &self.registry
57    }
58
59    /// 返回当前应用实例显式拥有的冻结资源。
60    pub fn tools(&self) -> &Tools {
61        &self.tools
62    }
63
64    /// 返回从 Catalog 唯一字段事实预编译的数据库 schema 定义。
65    pub fn table_definitions(&self) -> &[TableDefinition] {
66        &self.table_definitions
67    }
68
69    /// 返回启动期解析完成的默认/显式 Table Views。
70    pub fn compiled_views(&self) -> &[crate::definition::CompiledTableView] {
71        &self.compiled_views
72    }
73
74    /// 按当前请求的认证身份投影有权访问的版本化 UI 目录。
75    ///
76    /// Action 和 View 均复用 dispatch 的构建期冻结授权策略;TableView 列同时按
77    /// 字段读取角色过滤,secret 字段始终 fail-closed。租户数据范围仍由实际
78    /// TableQuery 独立强制执行,前端目录不能替代服务端数据隔离。
79    pub fn ui_catalog(
80        &self,
81        context: &ActionContext,
82    ) -> Result<crate::definition::UiCatalog, BaseError> {
83        self.registry.ui_catalog(context)
84    }
85
86    /// 为一次请求创建绑定当前应用资源的 ActionContext。
87    pub fn context(&self, request: Request) -> ActionContext {
88        ActionContext::new(request, Arc::clone(&self.tools))
89            .with_registry(Arc::clone(&self.registry))
90    }
91
92    /// 通过启动期解析的 handle 执行请求。
93    pub async fn dispatch(
94        &self,
95        handle: ActionHandle,
96        request: Request,
97    ) -> Result<ApiResponse, BaseError> {
98        self.registry.dispatch(handle, self.context(request)).await
99    }
100
101    /// 执行已由传输层补全元数据的上下文。
102    pub async fn dispatch_context(
103        &self,
104        handle: ActionHandle,
105        context: ActionContext,
106    ) -> Result<ApiResponse, BaseError> {
107        self.registry.dispatch(handle, context).await
108    }
109}
110
111/// 仅在启动期可变的 App 定义构建器。
112#[derive(Debug, Clone, Default)]
113#[must_use = "AppBuilder 必须调用 build() 才会执行交叉校验并冻结定义"]
114pub struct AppBuilder {
115    addons: Vec<AddonSpec>,
116}
117
118impl AppBuilder {
119    /// 创建空构建器。
120    pub fn new() -> Self {
121        Self::default()
122    }
123
124    /// 注册一个原生 Addon 定义。
125    pub fn addon(mut self, addon: impl Into<AddonSpec>) -> Self {
126        self.addons.push(addon.into());
127        self
128    }
129
130    /// 校验全部定义、解析引用并冻结 Catalog/Registry。
131    pub fn build(mut self, tools: impl Into<Arc<Tools>>) -> Result<BuiltApp, BuildError> {
132        let tools: Arc<Tools> = tools.into();
133        // 兼容直接给 AddonSpec.datasource 赋值的调用方:构建期统一下派到模块与表。
134        for addon in &mut self.addons {
135            if let Some(source) = addon.datasource.clone() {
136                for module in &mut addon.modules {
137                    if module.datasource.is_none() {
138                        module.datasource = Some(source.clone());
139                    }
140                    if let Some(table) = &mut module.table {
141                        if table.datasource.is_none() {
142                            table.datasource = Some(source.clone());
143                        }
144                    }
145                }
146            }
147        }
148        validate_unique_addons(&self.addons)?;
149        validate_dependencies(&self.addons)?;
150        validate_module_ownership(&self.addons)?;
151        validate_unique_modules(&self.addons)?;
152        validate_module_contents(&self.addons)?;
153        validate_middleware_order(&self.addons)?;
154        resolve_param_fields(&mut self.addons)?;
155
156        let fields = collect_fields(&self.addons)?;
157        let actions = collect_actions(&self.addons)?;
158        let views = collect_views(&self.addons)?;
159        validate_references(&self.addons, &fields, &actions, &views)?;
160        validate_routes(&self.addons)?;
161
162        sort_definitions(&mut self.addons);
163        let mut registry = build_registry(&self.addons)?;
164        let compiled_views = compile_views(&self.addons, &registry)?;
165        registry.table_views = compile_runtime_table_views(&self.addons, &registry)?;
166        registry.modules = compile_runtime_modules(&self.addons, &registry)?;
167        registry.reindex_views_by_module();
168        for runtime in &registry.handlers {
169            runtime.handler.bind_registry(&registry).map_err(|error| {
170                BuildError::InvalidReference {
171                    kind: "ActionLink",
172                    reference: error.to_string(),
173                }
174            })?;
175        }
176        let registry = Arc::new(registry);
177        let table_definitions = compile_table_definitions(&self.addons)?;
178        // 配置了数据库注册表时,表声明的逻辑源必须在注册表中存在;未配置数据库
179        // 的纯元数据构建保持既有行为。
180        #[cfg(any(feature = "mysql", feature = "postgres"))]
181        if let Ok(datasources) = tools.datasources() {
182            for definition in &table_definitions {
183                datasources
184                    .resolve_id(definition.datasource())
185                    .map_err(|error| BuildError::InvalidReference {
186                        kind: "Datasource",
187                        reference: error.to_string(),
188                    })?;
189            }
190            for module in self.addons.iter().flat_map(|addon| &addon.modules) {
191                if let Some(source) = &module.datasource {
192                    datasources.resolve_id(source).map_err(|error| {
193                        BuildError::InvalidReference {
194                            kind: "Datasource",
195                            reference: error.to_string(),
196                        }
197                    })?;
198                }
199            }
200        }
201        for module in self.addons.iter_mut().flat_map(|addon| &mut addon.modules) {
202            module.clear_handlers();
203        }
204        Ok(BuiltApp {
205            catalog: DefinitionCatalog {
206                addons: self.addons,
207            },
208            registry,
209            tools,
210            table_definitions,
211            compiled_views,
212        })
213    }
214}