Skip to main content

yang_base/definition/
spec.rs

1//! 不可变定义的构建期输入模型。
2
3use super::{
4    ActionName, ActionPresentationSpec, ActionRef, AddonName, FieldName, FieldRef, FieldSpec,
5    ModuleName, Params, PresentationSpec, TableSortSpec, TableSpec, ValidationSpec, ViewName,
6};
7use crate::action::DynAction;
8use crate::action::PermissionMode;
9use crate::datasource::DatasourceId;
10use crate::router::Middleware;
11use std::collections::BTreeMap;
12use std::fmt;
13use std::sync::Arc;
14
15/// 业务字段的语义种类。
16#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
17#[non_exhaustive]
18pub enum FieldKind {
19    /// 主键。
20    Key,
21    /// 有长度上限的字符串。
22    Str,
23    /// 长文本。
24    Text,
25    /// 整数。
26    Int,
27    /// 定点小数。
28    Decimal,
29    /// 布尔开关。
30    Switch,
31    /// 单选枚举。
32    Radio,
33    /// 表关系。
34    Table,
35    /// 树关系。
36    Tree,
37    /// 时间戳。
38    Timestamp,
39}
40
41/// HTTP 参数来源。
42#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
43#[non_exhaustive]
44pub enum ParamSource {
45    /// JSON body。
46    Body,
47    /// Query string。
48    Query,
49    /// Path 参数。
50    Path,
51    /// Header。
52    Header,
53}
54
55/// Action 的单个强类型参数定义。
56#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct ParamSpec {
58    /// 参数名。
59    pub name: FieldName,
60    /// 参数来源。
61    pub source: ParamSource,
62    /// 是否必填。
63    pub required: bool,
64    /// 可选的复用字段。
65    pub field: Option<FieldRef>,
66    /// Action 专属参数的语义类型;复用字段时由引用目标提供。
67    pub kind: Option<FieldKind>,
68    /// Action 级验证覆盖。
69    pub validation: ValidationSpec,
70    /// Action 级展示覆盖。
71    pub presentation: PresentationSpec,
72}
73
74impl ParamSpec {
75    /// 创建参数定义。
76    pub fn new(name: FieldName, source: ParamSource) -> Self {
77        Self {
78            name,
79            source,
80            required: false,
81            field: None,
82            kind: None,
83            validation: ValidationSpec::default(),
84            presentation: PresentationSpec::default(),
85        }
86    }
87
88    /// 设置必填语义。
89    pub fn required(mut self, required: bool) -> Self {
90        self.required = required;
91        self
92    }
93
94    /// 复用一个已声明字段的共享语义。
95    pub fn from_field(mut self, field: FieldRef) -> Self {
96        self.field = Some(field);
97        self
98    }
99
100    pub(crate) fn from_spec(name: FieldName, source: ParamSource, field: FieldSpec) -> Self {
101        Self {
102            name,
103            source,
104            required: field.is_required(),
105            field: None,
106            kind: Some(field.kind),
107            validation: field.validation,
108            presentation: field.presentation,
109        }
110    }
111}
112
113/// 支持的 HTTP method。
114#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
115#[non_exhaustive]
116pub enum HttpMethod {
117    /// GET。
118    Get,
119    /// POST。
120    Post,
121    /// PUT。
122    Put,
123    /// PATCH。
124    Patch,
125    /// DELETE。
126    Delete,
127    /// OPTIONS。
128    Options,
129    /// HEAD。
130    Head,
131}
132
133impl HttpMethod {
134    /// 返回标准大写 method 名。
135    pub const fn as_str(self) -> &'static str {
136        match self {
137            Self::Get => "GET",
138            Self::Post => "POST",
139            Self::Put => "PUT",
140            Self::Patch => "PATCH",
141            Self::Delete => "DELETE",
142            Self::Options => "OPTIONS",
143            Self::Head => "HEAD",
144        }
145    }
146}
147
148/// Action 的传输路由定义。
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct RouteSpec {
151    /// HTTP method。
152    pub method: HttpMethod,
153    /// Axum 0.8 路由模板。
154    pub path: String,
155    /// OpenAPI operation id。
156    pub operation_id: String,
157}
158
159impl RouteSpec {
160    /// 创建路由定义。
161    pub fn new(
162        method: HttpMethod,
163        path: impl Into<String>,
164        operation_id: impl Into<String>,
165    ) -> Self {
166        Self {
167            method,
168            path: path.into(),
169            operation_id: operation_id.into(),
170        }
171    }
172}
173
174/// Action 的定义期契约。
175#[derive(Debug, Clone, PartialEq, Eq)]
176pub struct ActionSpec {
177    /// Action 局部名称。
178    pub name: ActionName,
179    /// 唯一传输路由。
180    pub route: RouteSpec,
181    /// 强类型参数定义。
182    pub params: Vec<ParamSpec>,
183    /// 内部调用依赖。
184    pub calls: Vec<ActionRef>,
185    /// 用户可见名称。
186    pub display_name: String,
187    /// 业务说明。
188    pub description: String,
189    /// Action 所需权限。
190    pub permissions: Vec<String>,
191    /// 权限集合的匹配方式。
192    pub permission_mode: PermissionMode,
193    /// 是否允许匿名访问。
194    pub is_public: bool,
195    /// 请求媒体类型。
196    pub request_media_type: super::ActionMediaType,
197    /// multipart 资源与类型限制;仅 multipart Action 可用。
198    pub multipart: Option<super::MultipartSpec>,
199    /// 成功响应的静态类别,供调用方选择安全的展示方式。
200    pub response_kind: super::ActionResponseKind,
201    /// 成功响应状态码。
202    pub success_status: u16,
203    /// OpenAPI/后台元数据标签。
204    pub tags: Vec<String>,
205    /// Handler Input 的构建期 JSON Schema。
206    pub input_schema: serde_json::Value,
207    /// Handler Output 的构建期 JSON Schema。
208    pub output_schema: serde_json::Value,
209    pub(crate) contract_error: Option<String>,
210}
211
212impl ActionSpec {
213    /// 创建最小 Action 定义。
214    pub fn new(name: ActionName, route: RouteSpec) -> Self {
215        let display_name = name.to_string();
216        Self {
217            name,
218            route,
219            params: Vec::new(),
220            calls: Vec::new(),
221            display_name,
222            description: String::new(),
223            permissions: Vec::new(),
224            permission_mode: PermissionMode::All,
225            is_public: false,
226            request_media_type: super::ActionMediaType::Json,
227            multipart: None,
228            response_kind: super::ActionResponseKind::Json,
229            success_status: 200,
230            tags: Vec::new(),
231            input_schema: serde_json::Value::Null,
232            output_schema: serde_json::Value::Null,
233            contract_error: None,
234        }
235    }
236
237    /// 设置用户可见名称。
238    #[must_use]
239    pub fn display_name(mut self, display_name: impl Into<String>) -> Self {
240        self.display_name = display_name.into();
241        self
242    }
243
244    /// 设置业务说明。
245    #[must_use]
246    pub fn description(mut self, description: impl Into<String>) -> Self {
247        self.description = description.into();
248        self
249    }
250
251    /// 设置所需权限及匹配方式。
252    #[must_use]
253    pub fn permissions<I, S>(mut self, permissions: I, mode: PermissionMode) -> Self
254    where
255        I: IntoIterator<Item = S>,
256        S: Into<String>,
257    {
258        self.permissions = permissions.into_iter().map(Into::into).collect();
259        self.permission_mode = mode;
260        self
261    }
262
263    /// 设置是否允许匿名访问。
264    #[must_use]
265    pub fn public(mut self, is_public: bool) -> Self {
266        self.is_public = is_public;
267        self
268    }
269
270    /// 声明 Action 接受受限的 `multipart/form-data` 请求。
271    #[must_use]
272    pub fn multipart(mut self, multipart: super::MultipartSpec) -> Self {
273        self.request_media_type = super::ActionMediaType::Multipart;
274        self.multipart = Some(multipart);
275        self
276    }
277
278    /// 声明成功响应的静态类别。
279    #[must_use]
280    pub fn response_kind(mut self, response_kind: super::ActionResponseKind) -> Self {
281        self.response_kind = response_kind;
282        self
283    }
284
285    /// 设置成功响应 HTTP 状态码。
286    #[must_use]
287    pub fn success_status(mut self, success_status: u16) -> Self {
288        self.success_status = success_status;
289        self
290    }
291
292    /// 增加元数据标签。
293    #[must_use]
294    pub fn tag(mut self, tag: impl Into<String>) -> Self {
295        self.tags.push(tag.into());
296        self
297    }
298
299    /// 增加一个参数定义。
300    #[must_use]
301    pub fn param(mut self, param: ParamSpec) -> Self {
302        self.params.push(param);
303        self
304    }
305
306    /// 使用一个 Params 集合替换当前参数定义。
307    #[must_use]
308    pub fn params(mut self, params: Params) -> Self {
309        self.params = params.into_vec();
310        self
311    }
312
313    /// 声明一个内部 Action 调用引用。
314    #[must_use]
315    pub fn calls(mut self, action: ActionRef) -> Self {
316        self.calls.push(action);
317        self
318    }
319
320    fn bind_handler_contract(mut self, handler: &dyn DynAction) -> Self {
321        if !self.input_schema.is_null() && !self.output_schema.is_null() {
322            return self;
323        }
324        let meta = handler.meta();
325        let input = serde_json::to_value(meta.input_schema);
326        let output = serde_json::to_value(meta.output_schema);
327        match (input, output) {
328            (Ok(input_schema), Ok(output_schema)) => {
329                self.input_schema = input_schema;
330                self.output_schema = output_schema;
331            }
332            (Err(error), _) | (_, Err(error)) => {
333                self.contract_error = Some(error.to_string());
334            }
335        }
336        self
337    }
338
339    #[cfg(any(feature = "mysql", feature = "postgres"))]
340    fn bind_builtin_contract(
341        mut self,
342        contract: crate::action::builtin::BuiltinActionContract,
343    ) -> Result<Self, crate::error::BaseError> {
344        self.input_schema = serde_json::to_value(contract.input_schema)
345            .map_err(|error| crate::error::BaseError::JsonSerializeFailed(error.to_string()))?;
346        self.output_schema = serde_json::to_value(contract.output_schema)
347            .map_err(|error| crate::error::BaseError::JsonSerializeFailed(error.to_string()))?;
348        self.permissions = contract.permissions;
349        self.permission_mode = contract.permission_mode;
350        Ok(self)
351    }
352}
353
354/// 通用树 View 的显式拓扑声明。
355///
356/// 树拓扑属于 View 语义,不能从字段存储类型或约定列名推断。三个字段都必须同时
357/// 出现在所属 [`ViewSpec`] 中,并在构建期解析到同一张主表。
358#[derive(Debug, Clone, PartialEq, Eq)]
359pub struct TreeViewSpec {
360    /// 节点唯一标识字段。
361    pub id_field: FieldRef,
362    /// 父节点标识字段;根节点应返回 null。
363    pub parent_field: FieldRef,
364    /// 节点用户可见标签字段。
365    pub label_field: FieldRef,
366    /// 单次树查询的节点上限;`None` 回退到服务端默认值
367    /// ([`crate::table::DEFAULT_TREE_MAX_NODES`])。
368    pub max_nodes: Option<usize>,
369}
370
371impl TreeViewSpec {
372    /// 创建显式树拓扑声明。
373    pub fn new(id_field: FieldRef, parent_field: FieldRef, label_field: FieldRef) -> Self {
374        Self {
375            id_field,
376            parent_field,
377            label_field,
378            max_nodes: None,
379        }
380    }
381
382    /// 设置单次树查询的节点上限;必须大于 0,否则构建期报错。
383    #[must_use]
384    pub fn max_nodes(mut self, max_nodes: usize) -> Self {
385        self.max_nodes = Some(max_nodes);
386        self
387    }
388}
389
390/// 后台 Table/Select 等展示定义。
391#[derive(Debug, Clone, PartialEq, Eq)]
392pub struct ViewSpec {
393    /// View 局部名称。
394    pub name: ViewName,
395    /// 用户可见标题;默认使用 View 局部名称。
396    pub title: String,
397    /// 有序字段引用。
398    pub fields: Vec<FieldRef>,
399    /// 有序按钮/操作引用。
400    pub actions: Vec<ActionRef>,
401    /// 为通用表格返回标准分页行数据的 Action。
402    pub data_action: Option<ActionRef>,
403    /// 显式 Action 展示声明;未声明的 Action 在构建期按静态契约安全推导。
404    pub action_presentations: BTreeMap<ActionRef, ActionPresentationSpec>,
405    /// 可选树拓扑;未声明时按普通表格投影。
406    pub tree: Option<TreeViewSpec>,
407    /// 有序默认排序声明。
408    pub default_sort: Vec<TableSortSpec>,
409}
410
411impl ViewSpec {
412    /// 创建空 View。
413    pub fn new(name: ViewName) -> Self {
414        let title = name.to_string();
415        Self {
416            name,
417            title,
418            fields: Vec::new(),
419            actions: Vec::new(),
420            data_action: None,
421            action_presentations: BTreeMap::new(),
422            tree: None,
423            default_sort: Vec::new(),
424        }
425    }
426
427    /// 增加一个展示字段。
428    #[must_use]
429    pub fn field(mut self, field: FieldRef) -> Self {
430        self.fields.push(field);
431        self
432    }
433
434    /// 增加一个按钮或操作引用。
435    #[must_use]
436    pub fn action(mut self, action: ActionRef) -> Self {
437        self.actions.push(action);
438        self
439    }
440
441    /// 设置用户可见标题。
442    #[must_use]
443    pub fn title(mut self, title: impl Into<String>) -> Self {
444        self.title = title.into();
445        self
446    }
447
448    /// 设置通用表格的数据查询 Action。
449    ///
450    /// 该 Action 必须返回 JSON,且业务数据应符合 `items/page/page_size/total`
451    /// 分页结构。它不会自动成为工具栏或行按钮。
452    #[must_use]
453    pub fn data_action(mut self, action: ActionRef) -> Self {
454        self.data_action = Some(action);
455        self
456    }
457
458    /// 增加一个带显式展示语义的按钮或操作引用。
459    #[must_use]
460    pub fn present_action(
461        mut self,
462        action: ActionRef,
463        presentation: ActionPresentationSpec,
464    ) -> Self {
465        if !self.actions.contains(&action) {
466            self.actions.push(action.clone());
467        }
468        self.action_presentations.insert(action, presentation);
469        self
470    }
471
472    /// 将当前 View 显式声明为树 View。
473    #[must_use]
474    pub fn tree(mut self, tree: TreeViewSpec) -> Self {
475        self.tree = Some(tree);
476        self
477    }
478
479    /// 增加一个默认排序字段。
480    #[must_use]
481    pub fn default_sort(mut self, sort: TableSortSpec) -> Self {
482        self.default_sort.push(sort);
483        self
484    }
485}
486
487/// Module 的聚合定义。
488#[derive(Clone)]
489pub struct ModuleSpec {
490    /// 全限定 Module 名称。
491    pub name: ModuleName,
492    /// 可选主表。
493    pub table: Option<TableSpec>,
494    /// Action 定义集合。
495    actions: Vec<ActionSpec>,
496    /// 与 Action 定义同索引的运行时 Handler。
497    handlers: Vec<Arc<dyn DynAction>>,
498    /// 模块级中间件链。
499    middlewares: Vec<Arc<dyn Middleware>>,
500    /// 模块默认权限。
501    pub default_permissions: Vec<String>,
502    /// 模块默认权限匹配方式。
503    pub default_permission_mode: PermissionMode,
504    /// View 集合。
505    pub views: Vec<ViewSpec>,
506    /// 可选的前端 Module 页面展示声明。
507    pub presentation: Option<super::ModulePresentationSpec>,
508    /// 模块所属逻辑数据源;`None` 表示使用 Addon/默认数据源。
509    pub datasource: Option<DatasourceId>,
510}
511
512impl ModuleSpec {
513    /// 创建空 Module。
514    pub fn new(name: ModuleName) -> Self {
515        Self {
516            name,
517            table: None,
518            actions: Vec::new(),
519            handlers: Vec::new(),
520            middlewares: Vec::new(),
521            default_permissions: Vec::new(),
522            default_permission_mode: PermissionMode::All,
523            views: Vec::new(),
524            presentation: None,
525            datasource: None,
526        }
527    }
528
529    /// 设置 Module 所属逻辑数据源;已声明主表会同步继承。
530    #[must_use]
531    pub fn datasource(mut self, id: DatasourceId) -> Self {
532        if let Some(table) = &mut self.table {
533            if table.datasource.is_none() {
534                table.datasource = Some(id.clone());
535            }
536        }
537        self.datasource = Some(id);
538        self
539    }
540
541    /// 设置 Module 主表。
542    #[must_use]
543    pub fn table(mut self, mut table: TableSpec) -> Self {
544        if table.datasource.is_none() {
545            table.datasource = self.datasource.clone();
546        }
547        self.table = Some(table);
548        self
549    }
550
551    /// 按模块数据源解析主表定义;表未显式声明源时继承模块源。
552    pub(crate) fn resolved_table_definition(
553        &self,
554    ) -> Result<Option<crate::table::TableDefinition>, crate::error::BaseError> {
555        let Some(table) = &self.table else {
556            return Ok(None);
557        };
558        let mut table = table.clone();
559        if table.datasource.is_none() {
560            table.datasource = self.datasource.clone();
561        }
562        table.table_definition().map(Some)
563    }
564
565    /// 设置前端 Module 页面展示声明。
566    #[must_use]
567    pub fn presentation(mut self, presentation: super::ModulePresentationSpec) -> Self {
568        self.presentation = Some(presentation);
569        self
570    }
571
572    /// 为模块主表注册标准 add/put/del/get/select/table Actions。
573    #[cfg(any(feature = "mysql", feature = "postgres"))]
574    pub fn crud(self) -> Result<Self, crate::error::BaseError> {
575        let prefix = format!("/api/{}", self.name.as_str().replace('.', "/"));
576        self.crud_at(prefix)
577    }
578
579    /// 在显式资源路径下注册标准 add/put/del/get/select/table Actions。
580    ///
581    /// 用于版本化或资源复数化路由;`operation_id` 仍始终使用
582    /// `<module>.<action>`,不与 HTTP 路径耦合。
583    #[cfg(any(feature = "mysql", feature = "postgres"))]
584    pub fn crud_at(self, prefix: impl Into<String>) -> Result<Self, crate::error::BaseError> {
585        use crate::action::builtin::{AddAction, DelAction, PutAction};
586
587        self.crud_at_with_mutations(prefix, AddAction::new(), PutAction::new(), DelAction::new())
588    }
589
590    /// 在显式资源路径下注册标准 CRUD 契约,并替换三个写 Action 的运行时 Handler。
591    ///
592    /// 路由、权限以及与表定义绑定的动态 JSON Schema 仍由框架统一生成;业务只负责
593    /// add/put/del 的事务语义。自定义 Handler 必须分别接受与内置 Action 相同的
594    /// [`Record`](crate::table::Record)、
595    /// [`PutInput`](crate::action::builtin::PutInput) 与
596    /// [`GetByPk`](crate::action::builtin::GetByPk) 输入,并返回对应的标准结果。
597    #[cfg(any(feature = "mysql", feature = "postgres"))]
598    pub fn crud_at_with_mutations<A, P, D>(
599        self,
600        prefix: impl Into<String>,
601        add: A,
602        put: P,
603        del: D,
604    ) -> Result<Self, crate::error::BaseError>
605    where
606        A: DynAction,
607        P: DynAction,
608        D: DynAction,
609    {
610        use crate::action::builtin::{crud_contracts, GetAction, SelectAction, TableAction};
611
612        let prefix = prefix.into();
613        if prefix.len() < 2
614            || !prefix.starts_with('/')
615            || prefix.ends_with('/')
616            || prefix.contains("//")
617            || prefix.contains(['?', '#'])
618        {
619            return Err(crate::error::BaseError::ConfigError(format!(
620                "CRUD 资源路径无效: {prefix}"
621            )));
622        }
623
624        let table = self
625            .resolved_table_definition()?
626            .ok_or(crate::error::BaseError::TableDefinitionNotSet)?;
627        if table.primary_keys().len() != 1 {
628            return Err(crate::error::BaseError::ConfigError(format!(
629                "内置 CRUD 仅支持单主键表;模块 {} 的主表 {} 主键为 {:?}",
630                self.name,
631                table.name(),
632                table.primary_keys()
633            )));
634        }
635        let mut contracts: std::collections::BTreeMap<_, _> =
636            crud_contracts(&table, self.name.as_str())?
637                .into_iter()
638                .collect();
639        let module_name = self.name.to_string();
640        let read_permission = format!("{}:read", self.name);
641        let write_permission = format!("{}:write", self.name);
642        let action_name = |value: &str| {
643            ActionName::new(value)
644                .map_err(|error| crate::error::BaseError::ConfigError(error.to_string()))
645        };
646        let action = |name: ActionName, method, path: String| {
647            let operation_id = format!("{module_name}.{name}");
648            ActionSpec::new(name, RouteSpec::new(method, path, operation_id))
649        };
650        let mut contract = |name: &str| {
651            contracts.remove(name).ok_or_else(|| {
652                crate::error::BaseError::ConfigError(format!(
653                    "内置 CRUD 契约缺失: {module_name}.{name}"
654                ))
655            })
656        };
657
658        Ok(self
659            .action(
660                action(action_name("add")?, HttpMethod::Post, prefix.clone())
661                    .display_name("新增")
662                    .permissions([write_permission.clone()], PermissionMode::All)
663                    .success_status(201)
664                    .bind_builtin_contract(contract("add")?)?,
665                add,
666            )
667            .action(
668                action(action_name("put")?, HttpMethod::Put, prefix.clone())
669                    .display_name("修改")
670                    .permissions([write_permission.clone()], PermissionMode::All)
671                    .bind_builtin_contract(contract("put")?)?,
672                put,
673            )
674            .action(
675                action(action_name("del")?, HttpMethod::Delete, prefix.clone())
676                    .display_name("删除")
677                    .permissions([write_permission], PermissionMode::All)
678                    .bind_builtin_contract(contract("del")?)?,
679                del,
680            )
681            .action(
682                action(action_name("get")?, HttpMethod::Get, prefix.clone())
683                    .display_name("详情")
684                    .permissions([read_permission.clone()], PermissionMode::All)
685                    .bind_builtin_contract(contract("get")?)?,
686                GetAction::new(),
687            )
688            .action(
689                action(
690                    action_name("select")?,
691                    HttpMethod::Post,
692                    format!("{prefix}/query"),
693                )
694                .display_name("列表")
695                .permissions([read_permission.clone()], PermissionMode::All)
696                .bind_builtin_contract(contract("select")?)?,
697                SelectAction::new(),
698            )
699            .action(
700                action(
701                    action_name("table")?,
702                    HttpMethod::Get,
703                    format!("{prefix}/schema"),
704                )
705                .display_name("表定义")
706                .permissions([read_permission], PermissionMode::All)
707                .bind_builtin_contract(contract("table")?)?,
708                TableAction::new(),
709            ))
710    }
711
712    /// 原子注册 Action 定义与其唯一运行时 Handler。
713    #[must_use]
714    pub fn action<A>(mut self, action: ActionSpec, handler: A) -> Self
715    where
716        A: DynAction,
717    {
718        self.actions.push(action.bind_handler_contract(&handler));
719        self.handlers.push(Arc::new(handler));
720        self
721    }
722
723    /// 原子注册已经类型擦除的 Action Handler。
724    #[must_use]
725    pub fn dyn_action(mut self, action: ActionSpec, handler: Arc<dyn DynAction>) -> Self {
726        self.actions
727            .push(action.bind_handler_contract(handler.as_ref()));
728        self.handlers.push(handler);
729        self
730    }
731
732    /// 增加一个模块级中间件。
733    ///
734    /// 多次调用按**注册顺序**构成洋葱链:先注册的中间件位于更外层,请求阶段
735    /// 先于后注册的中间件执行(响应阶段则相反)。因此依赖上游注入状态的中间件
736    /// 必须后注册——例如认证类中间件(如 `TokenAuthMiddleware`)必须先于
737    /// [`TenantResolverMiddleware`](crate::action::TenantResolverMiddleware)
738    /// 注册,租户 resolver 才能从 [`ActionContext`](crate::action::ActionContext)
739    /// 读到已认证用户。框架会在构建期拒绝这两个内置中间件的反向顺序;自定义
740    /// 中间件仍应通过 [`Middleware::role`](crate::router::Middleware::role) 声明已知角色。
741    #[must_use]
742    pub fn middleware<M>(mut self, middleware: M) -> Self
743    where
744        M: Middleware,
745    {
746        self.middlewares.push(Arc::new(middleware));
747        self
748    }
749
750    /// 设置模块默认权限。
751    #[must_use]
752    pub fn default_permissions<I, S>(mut self, permissions: I, mode: PermissionMode) -> Self
753    where
754        I: IntoIterator<Item = S>,
755        S: Into<String>,
756    {
757        self.default_permissions = permissions.into_iter().map(Into::into).collect();
758        self.default_permission_mode = mode;
759        self
760    }
761
762    /// 返回按局部名称稳定排序前的 Action 定义。
763    pub fn actions(&self) -> &[ActionSpec] {
764        &self.actions
765    }
766
767    pub(crate) fn action_pairs(&self) -> impl Iterator<Item = (&ActionSpec, &Arc<dyn DynAction>)> {
768        self.actions.iter().zip(&self.handlers)
769    }
770
771    pub(crate) fn middlewares(&self) -> &[Arc<dyn Middleware>] {
772        &self.middlewares
773    }
774
775    pub(crate) fn actions_mut(&mut self) -> &mut [ActionSpec] {
776        &mut self.actions
777    }
778
779    pub(crate) fn sort_actions(&mut self) {
780        let mut pairs: Vec<_> = self
781            .actions
782            .drain(..)
783            .zip(self.handlers.drain(..))
784            .collect();
785        pairs.sort_by(|left, right| left.0.name.cmp(&right.0.name));
786        for (action, handler) in pairs {
787            self.actions.push(action);
788            self.handlers.push(handler);
789        }
790    }
791
792    pub(crate) fn clear_handlers(&mut self) {
793        self.handlers.clear();
794        self.middlewares.clear();
795    }
796
797    /// 增加一个 View。
798    #[must_use]
799    pub fn view(mut self, view: ViewSpec) -> Self {
800        self.views.push(view);
801        self
802    }
803}
804
805impl fmt::Debug for ModuleSpec {
806    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
807        formatter
808            .debug_struct("ModuleSpec")
809            .field("name", &self.name)
810            .field("table", &self.table)
811            .field("actions", &self.actions)
812            .field("default_permissions", &self.default_permissions)
813            .field("default_permission_mode", &self.default_permission_mode)
814            .field("views", &self.views)
815            .finish()
816    }
817}
818
819impl PartialEq for ModuleSpec {
820    fn eq(&self, other: &Self) -> bool {
821        self.name == other.name
822            && self.table == other.table
823            && self.actions == other.actions
824            && self.default_permissions == other.default_permissions
825            && self.default_permission_mode == other.default_permission_mode
826            && self.views == other.views
827    }
828}
829
830impl Eq for ModuleSpec {}
831
832/// Addon 的产品能力定义。
833#[derive(Debug, Clone, PartialEq, Eq)]
834pub struct AddonSpec {
835    /// Addon 名称。
836    pub name: AddonName,
837    /// 依赖的其它 Addon。
838    pub dependencies: Vec<AddonName>,
839    /// Module 集合。
840    pub modules: Vec<ModuleSpec>,
841    /// Addon 默认逻辑数据源;模块未显式声明时继承。
842    pub datasource: Option<DatasourceId>,
843}
844
845impl AddonSpec {
846    /// 创建空 Addon。
847    pub fn new(name: AddonName) -> Self {
848        Self {
849            name,
850            dependencies: Vec::new(),
851            modules: Vec::new(),
852            datasource: None,
853        }
854    }
855
856    /// 设置 Addon 默认逻辑数据源;已加入的模块与其主表同步继承。
857    #[must_use]
858    pub fn datasource(mut self, id: DatasourceId) -> Self {
859        for module in &mut self.modules {
860            if module.datasource.is_none() {
861                module.datasource = Some(id.clone());
862            }
863            if let Some(table) = &mut module.table {
864                if table.datasource.is_none() {
865                    table.datasource = Some(id.clone());
866                }
867            }
868        }
869        self.datasource = Some(id);
870        self
871    }
872
873    /// 声明 Addon 依赖。
874    #[must_use]
875    pub fn depends_on(mut self, dependency: AddonName) -> Self {
876        self.dependencies.push(dependency);
877        self
878    }
879
880    /// 增加一个 Module。
881    #[must_use]
882    pub fn module(mut self, mut module: ModuleSpec) -> Self {
883        if module.datasource.is_none() {
884            module.datasource = self.datasource.clone();
885        }
886        if let Some(table) = &mut module.table {
887            if table.datasource.is_none() {
888                table.datasource = module.datasource.clone();
889            }
890        }
891        self.modules.push(module);
892        self
893    }
894
895    /// 向 Addon 的每个 Module 追加同一个跨切面中间件。
896    ///
897    /// 中间件位于各 Module 已声明中间件之前,适合让日志、trace 等跨切面观察包括认证
898    /// 与租户解析失败在内的完整派发结果。所有 Module 共享同一个线程安全实例,不建立
899    /// 第二条派发链。
900    #[must_use]
901    pub fn middleware<M>(mut self, middleware: M) -> Self
902    where
903        M: Middleware,
904    {
905        let middleware: Arc<dyn Middleware> = Arc::new(middleware);
906        for module in &mut self.modules {
907            module.middlewares.insert(0, Arc::clone(&middleware));
908        }
909        self
910    }
911}
912
913#[cfg(test)]
914mod addon_middleware_tests {
915    use super::*;
916    use crate::router::RequestIdMiddleware;
917
918    #[test]
919    fn addon_middleware_prepends_one_shared_instance_before_module_middleware() {
920        let addon = AddonSpec::new(crate::addon!("test"))
921            .module(ModuleSpec::new(crate::module!("test.first")).middleware(RequestIdMiddleware))
922            .module(ModuleSpec::new(crate::module!("test.second")))
923            .middleware(RequestIdMiddleware);
924
925        assert_eq!(addon.modules[0].middlewares().len(), 2);
926        assert_eq!(addon.modules[1].middlewares().len(), 1);
927        assert!(Arc::ptr_eq(
928            &addon.modules[0].middlewares()[0],
929            &addon.modules[1].middlewares()[0]
930        ));
931    }
932}