1use 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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
17#[non_exhaustive]
18pub enum FieldKind {
19 Key,
21 Str,
23 Text,
25 Int,
27 Decimal,
29 Switch,
31 Radio,
33 Table,
35 Tree,
37 Timestamp,
39}
40
41#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
43#[non_exhaustive]
44pub enum ParamSource {
45 Body,
47 Query,
49 Path,
51 Header,
53}
54
55#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct ParamSpec {
58 pub name: FieldName,
60 pub source: ParamSource,
62 pub required: bool,
64 pub field: Option<FieldRef>,
66 pub kind: Option<FieldKind>,
68 pub validation: ValidationSpec,
70 pub presentation: PresentationSpec,
72}
73
74impl ParamSpec {
75 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 pub fn required(mut self, required: bool) -> Self {
90 self.required = required;
91 self
92 }
93
94 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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
115#[non_exhaustive]
116pub enum HttpMethod {
117 Get,
119 Post,
121 Put,
123 Patch,
125 Delete,
127 Options,
129 Head,
131}
132
133impl HttpMethod {
134 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#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct RouteSpec {
151 pub method: HttpMethod,
153 pub path: String,
155 pub operation_id: String,
157}
158
159impl RouteSpec {
160 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#[derive(Debug, Clone, PartialEq, Eq)]
176pub struct ActionSpec {
177 pub name: ActionName,
179 pub route: RouteSpec,
181 pub params: Vec<ParamSpec>,
183 pub calls: Vec<ActionRef>,
185 pub display_name: String,
187 pub description: String,
189 pub permissions: Vec<String>,
191 pub permission_mode: PermissionMode,
193 pub is_public: bool,
195 pub request_media_type: super::ActionMediaType,
197 pub multipart: Option<super::MultipartSpec>,
199 pub response_kind: super::ActionResponseKind,
201 pub success_status: u16,
203 pub tags: Vec<String>,
205 pub input_schema: serde_json::Value,
207 pub output_schema: serde_json::Value,
209 pub(crate) contract_error: Option<String>,
210}
211
212impl ActionSpec {
213 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 #[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 #[must_use]
246 pub fn description(mut self, description: impl Into<String>) -> Self {
247 self.description = description.into();
248 self
249 }
250
251 #[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 #[must_use]
265 pub fn public(mut self, is_public: bool) -> Self {
266 self.is_public = is_public;
267 self
268 }
269
270 #[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 #[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 #[must_use]
287 pub fn success_status(mut self, success_status: u16) -> Self {
288 self.success_status = success_status;
289 self
290 }
291
292 #[must_use]
294 pub fn tag(mut self, tag: impl Into<String>) -> Self {
295 self.tags.push(tag.into());
296 self
297 }
298
299 #[must_use]
301 pub fn param(mut self, param: ParamSpec) -> Self {
302 self.params.push(param);
303 self
304 }
305
306 #[must_use]
308 pub fn params(mut self, params: Params) -> Self {
309 self.params = params.into_vec();
310 self
311 }
312
313 #[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#[derive(Debug, Clone, PartialEq, Eq)]
359pub struct TreeViewSpec {
360 pub id_field: FieldRef,
362 pub parent_field: FieldRef,
364 pub label_field: FieldRef,
366 pub max_nodes: Option<usize>,
369}
370
371impl TreeViewSpec {
372 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 #[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#[derive(Debug, Clone, PartialEq, Eq)]
392pub struct ViewSpec {
393 pub name: ViewName,
395 pub title: String,
397 pub fields: Vec<FieldRef>,
399 pub actions: Vec<ActionRef>,
401 pub data_action: Option<ActionRef>,
403 pub action_presentations: BTreeMap<ActionRef, ActionPresentationSpec>,
405 pub tree: Option<TreeViewSpec>,
407 pub default_sort: Vec<TableSortSpec>,
409}
410
411impl ViewSpec {
412 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 #[must_use]
429 pub fn field(mut self, field: FieldRef) -> Self {
430 self.fields.push(field);
431 self
432 }
433
434 #[must_use]
436 pub fn action(mut self, action: ActionRef) -> Self {
437 self.actions.push(action);
438 self
439 }
440
441 #[must_use]
443 pub fn title(mut self, title: impl Into<String>) -> Self {
444 self.title = title.into();
445 self
446 }
447
448 #[must_use]
453 pub fn data_action(mut self, action: ActionRef) -> Self {
454 self.data_action = Some(action);
455 self
456 }
457
458 #[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 #[must_use]
474 pub fn tree(mut self, tree: TreeViewSpec) -> Self {
475 self.tree = Some(tree);
476 self
477 }
478
479 #[must_use]
481 pub fn default_sort(mut self, sort: TableSortSpec) -> Self {
482 self.default_sort.push(sort);
483 self
484 }
485}
486
487#[derive(Clone)]
489pub struct ModuleSpec {
490 pub name: ModuleName,
492 pub table: Option<TableSpec>,
494 actions: Vec<ActionSpec>,
496 handlers: Vec<Arc<dyn DynAction>>,
498 middlewares: Vec<Arc<dyn Middleware>>,
500 pub default_permissions: Vec<String>,
502 pub default_permission_mode: PermissionMode,
504 pub views: Vec<ViewSpec>,
506 pub presentation: Option<super::ModulePresentationSpec>,
508 pub datasource: Option<DatasourceId>,
510}
511
512impl ModuleSpec {
513 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 #[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 #[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 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 #[must_use]
567 pub fn presentation(mut self, presentation: super::ModulePresentationSpec) -> Self {
568 self.presentation = Some(presentation);
569 self
570 }
571
572 #[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 #[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 #[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 #[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 #[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 #[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 #[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 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 #[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#[derive(Debug, Clone, PartialEq, Eq)]
834pub struct AddonSpec {
835 pub name: AddonName,
837 pub dependencies: Vec<AddonName>,
839 pub modules: Vec<ModuleSpec>,
841 pub datasource: Option<DatasourceId>,
843}
844
845impl AddonSpec {
846 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 #[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 #[must_use]
875 pub fn depends_on(mut self, dependency: AddonName) -> Self {
876 self.dependencies.push(dependency);
877 self
878 }
879
880 #[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 #[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}