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