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        validate_unique_addons(&self.addons)?;
133        validate_dependencies(&self.addons)?;
134        validate_module_ownership(&self.addons)?;
135        validate_unique_modules(&self.addons)?;
136        validate_module_contents(&self.addons)?;
137        validate_middleware_order(&self.addons)?;
138        resolve_param_fields(&mut self.addons)?;
139
140        let fields = collect_fields(&self.addons)?;
141        let actions = collect_actions(&self.addons)?;
142        let views = collect_views(&self.addons)?;
143        validate_references(&self.addons, &fields, &actions, &views)?;
144        validate_routes(&self.addons)?;
145
146        sort_definitions(&mut self.addons);
147        let mut registry = build_registry(&self.addons)?;
148        let compiled_views = compile_views(&self.addons, &registry)?;
149        registry.table_views = compile_runtime_table_views(&self.addons, &registry)?;
150        registry.modules = compile_runtime_modules(&self.addons, &registry)?;
151        for runtime in &registry.handlers {
152            runtime.handler.bind_registry(&registry).map_err(|error| {
153                BuildError::InvalidReference {
154                    kind: "ActionLink",
155                    reference: error.to_string(),
156                }
157            })?;
158        }
159        let registry = Arc::new(registry);
160        let table_definitions = compile_table_definitions(&self.addons)?;
161        for module in self.addons.iter_mut().flat_map(|addon| &mut addon.modules) {
162            module.clear_handlers();
163        }
164        Ok(BuiltApp {
165            catalog: DefinitionCatalog {
166                addons: self.addons,
167            },
168            registry,
169            tools: tools.into(),
170            table_definitions,
171            compiled_views,
172        })
173    }
174}