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::router::Middleware;
10use std::collections::BTreeMap;
11use std::fmt;
12use std::sync::Arc;
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
16#[non_exhaustive]
17pub enum FieldKind {
18 Key,
20 Str,
22 Text,
24 Int,
26 Decimal,
28 Switch,
30 Radio,
32 Table,
34 Tree,
36 Timestamp,
38}
39
40#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
42#[non_exhaustive]
43pub enum ParamSource {
44 Body,
46 Query,
48 Path,
50 Header,
52}
53
54#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct ParamSpec {
57 pub name: FieldName,
59 pub source: ParamSource,
61 pub required: bool,
63 pub field: Option<FieldRef>,
65 pub kind: Option<FieldKind>,
67 pub validation: ValidationSpec,
69 pub presentation: PresentationSpec,
71}
72
73impl ParamSpec {
74 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 pub fn required(mut self, required: bool) -> Self {
89 self.required = required;
90 self
91 }
92
93 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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
114#[non_exhaustive]
115pub enum HttpMethod {
116 Get,
118 Post,
120 Put,
122 Patch,
124 Delete,
126 Options,
128 Head,
130}
131
132impl HttpMethod {
133 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#[derive(Debug, Clone, PartialEq, Eq)]
149pub struct RouteSpec {
150 pub method: HttpMethod,
152 pub path: String,
154 pub operation_id: String,
156}
157
158impl RouteSpec {
159 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#[derive(Debug, Clone, PartialEq, Eq)]
175pub struct ActionSpec {
176 pub name: ActionName,
178 pub route: RouteSpec,
180 pub params: Vec<ParamSpec>,
182 pub calls: Vec<ActionRef>,
184 pub display_name: String,
186 pub description: String,
188 pub permissions: Vec<String>,
190 pub permission_mode: PermissionMode,
192 pub is_public: bool,
194 pub request_media_type: super::ActionMediaType,
196 pub multipart: Option<super::MultipartSpec>,
198 pub response_kind: super::ActionResponseKind,
200 pub success_status: u16,
202 pub tags: Vec<String>,
204 pub input_schema: serde_json::Value,
206 pub output_schema: serde_json::Value,
208 pub(crate) contract_error: Option<String>,
209}
210
211impl ActionSpec {
212 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 #[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 #[must_use]
245 pub fn description(mut self, description: impl Into<String>) -> Self {
246 self.description = description.into();
247 self
248 }
249
250 #[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 #[must_use]
264 pub fn public(mut self, is_public: bool) -> Self {
265 self.is_public = is_public;
266 self
267 }
268
269 #[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 #[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 #[must_use]
286 pub fn success_status(mut self, success_status: u16) -> Self {
287 self.success_status = success_status;
288 self
289 }
290
291 #[must_use]
293 pub fn tag(mut self, tag: impl Into<String>) -> Self {
294 self.tags.push(tag.into());
295 self
296 }
297
298 #[must_use]
300 pub fn param(mut self, param: ParamSpec) -> Self {
301 self.params.push(param);
302 self
303 }
304
305 #[must_use]
307 pub fn params(mut self, params: Params) -> Self {
308 self.params = params.into_vec();
309 self
310 }
311
312 #[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#[derive(Debug, Clone, PartialEq, Eq)]
358pub struct TreeViewSpec {
359 pub id_field: FieldRef,
361 pub parent_field: FieldRef,
363 pub label_field: FieldRef,
365 pub max_nodes: Option<usize>,
368}
369
370impl TreeViewSpec {
371 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 #[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#[derive(Debug, Clone, PartialEq, Eq)]
391pub struct ViewSpec {
392 pub name: ViewName,
394 pub title: String,
396 pub fields: Vec<FieldRef>,
398 pub actions: Vec<ActionRef>,
400 pub data_action: Option<ActionRef>,
402 pub action_presentations: BTreeMap<ActionRef, ActionPresentationSpec>,
404 pub tree: Option<TreeViewSpec>,
406 pub default_sort: Vec<TableSortSpec>,
408}
409
410impl ViewSpec {
411 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 #[must_use]
428 pub fn field(mut self, field: FieldRef) -> Self {
429 self.fields.push(field);
430 self
431 }
432
433 #[must_use]
435 pub fn action(mut self, action: ActionRef) -> Self {
436 self.actions.push(action);
437 self
438 }
439
440 #[must_use]
442 pub fn title(mut self, title: impl Into<String>) -> Self {
443 self.title = title.into();
444 self
445 }
446
447 #[must_use]
452 pub fn data_action(mut self, action: ActionRef) -> Self {
453 self.data_action = Some(action);
454 self
455 }
456
457 #[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 #[must_use]
473 pub fn tree(mut self, tree: TreeViewSpec) -> Self {
474 self.tree = Some(tree);
475 self
476 }
477
478 #[must_use]
480 pub fn default_sort(mut self, sort: TableSortSpec) -> Self {
481 self.default_sort.push(sort);
482 self
483 }
484}
485
486#[derive(Clone)]
488pub struct ModuleSpec {
489 pub name: ModuleName,
491 pub table: Option<TableSpec>,
493 actions: Vec<ActionSpec>,
495 handlers: Vec<Arc<dyn DynAction>>,
497 middlewares: Vec<Arc<dyn Middleware>>,
499 pub default_permissions: Vec<String>,
501 pub default_permission_mode: PermissionMode,
503 pub views: Vec<ViewSpec>,
505 pub presentation: Option<super::ModulePresentationSpec>,
507}
508
509impl ModuleSpec {
510 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 #[must_use]
527 pub fn table(mut self, table: TableSpec) -> Self {
528 self.table = Some(table);
529 self
530 }
531
532 #[must_use]
534 pub fn presentation(mut self, presentation: super::ModulePresentationSpec) -> Self {
535 self.presentation = Some(presentation);
536 self
537 }
538
539 #[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 #[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 #[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 #[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 #[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 #[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 #[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 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 #[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#[derive(Debug, Clone, PartialEq, Eq)]
795pub struct AddonSpec {
796 pub name: AddonName,
798 pub dependencies: Vec<AddonName>,
800 pub modules: Vec<ModuleSpec>,
802}
803
804impl AddonSpec {
805 pub fn new(name: AddonName) -> Self {
807 Self {
808 name,
809 dependencies: Vec::new(),
810 modules: Vec::new(),
811 }
812 }
813
814 #[must_use]
816 pub fn depends_on(mut self, dependency: AddonName) -> Self {
817 self.dependencies.push(dependency);
818 self
819 }
820
821 #[must_use]
823 pub fn module(mut self, module: ModuleSpec) -> Self {
824 self.modules.push(module);
825 self
826 }
827
828 #[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}