use super::{
ActionName, ActionPresentationSpec, ActionRef, AddonName, FieldName, FieldRef, FieldSpec,
ModuleName, Params, PresentationSpec, TableSortSpec, TableSpec, ValidationSpec, ViewName,
};
use crate::action::DynAction;
use crate::action::PermissionMode;
use crate::datasource::DatasourceId;
use crate::router::Middleware;
use std::collections::BTreeMap;
use std::fmt;
use std::sync::Arc;
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum FieldKind {
Key,
Str,
Text,
Int,
Decimal,
Switch,
Radio,
Table,
Tree,
Timestamp,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum ParamSource {
Body,
Query,
Path,
Header,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParamSpec {
pub name: FieldName,
pub source: ParamSource,
pub required: bool,
pub field: Option<FieldRef>,
pub kind: Option<FieldKind>,
pub validation: ValidationSpec,
pub presentation: PresentationSpec,
}
impl ParamSpec {
pub fn new(name: FieldName, source: ParamSource) -> Self {
Self {
name,
source,
required: false,
field: None,
kind: None,
validation: ValidationSpec::default(),
presentation: PresentationSpec::default(),
}
}
pub fn required(mut self, required: bool) -> Self {
self.required = required;
self
}
pub fn from_field(mut self, field: FieldRef) -> Self {
self.field = Some(field);
self
}
pub(crate) fn from_spec(name: FieldName, source: ParamSource, field: FieldSpec) -> Self {
Self {
name,
source,
required: field.is_required(),
field: None,
kind: Some(field.kind),
validation: field.validation,
presentation: field.presentation,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum HttpMethod {
Get,
Post,
Put,
Patch,
Delete,
Options,
Head,
}
impl HttpMethod {
pub const fn as_str(self) -> &'static str {
match self {
Self::Get => "GET",
Self::Post => "POST",
Self::Put => "PUT",
Self::Patch => "PATCH",
Self::Delete => "DELETE",
Self::Options => "OPTIONS",
Self::Head => "HEAD",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RouteSpec {
pub method: HttpMethod,
pub path: String,
pub operation_id: String,
}
impl RouteSpec {
pub fn new(
method: HttpMethod,
path: impl Into<String>,
operation_id: impl Into<String>,
) -> Self {
Self {
method,
path: path.into(),
operation_id: operation_id.into(),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ActionSpec {
pub name: ActionName,
pub route: RouteSpec,
pub params: Vec<ParamSpec>,
pub calls: Vec<ActionRef>,
pub display_name: String,
pub description: String,
pub permissions: Vec<String>,
pub permission_mode: PermissionMode,
pub is_public: bool,
pub request_media_type: super::ActionMediaType,
pub multipart: Option<super::MultipartSpec>,
pub response_kind: super::ActionResponseKind,
pub success_status: u16,
pub tags: Vec<String>,
pub input_schema: serde_json::Value,
pub output_schema: serde_json::Value,
pub(crate) contract_error: Option<String>,
}
impl ActionSpec {
pub fn new(name: ActionName, route: RouteSpec) -> Self {
let display_name = name.to_string();
Self {
name,
route,
params: Vec::new(),
calls: Vec::new(),
display_name,
description: String::new(),
permissions: Vec::new(),
permission_mode: PermissionMode::All,
is_public: false,
request_media_type: super::ActionMediaType::Json,
multipart: None,
response_kind: super::ActionResponseKind::Json,
success_status: 200,
tags: Vec::new(),
input_schema: serde_json::Value::Null,
output_schema: serde_json::Value::Null,
contract_error: None,
}
}
#[must_use]
pub fn display_name(mut self, display_name: impl Into<String>) -> Self {
self.display_name = display_name.into();
self
}
#[must_use]
pub fn description(mut self, description: impl Into<String>) -> Self {
self.description = description.into();
self
}
#[must_use]
pub fn permissions<I, S>(mut self, permissions: I, mode: PermissionMode) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.permissions = permissions.into_iter().map(Into::into).collect();
self.permission_mode = mode;
self
}
#[must_use]
pub fn public(mut self, is_public: bool) -> Self {
self.is_public = is_public;
self
}
#[must_use]
pub fn multipart(mut self, multipart: super::MultipartSpec) -> Self {
self.request_media_type = super::ActionMediaType::Multipart;
self.multipart = Some(multipart);
self
}
#[must_use]
pub fn response_kind(mut self, response_kind: super::ActionResponseKind) -> Self {
self.response_kind = response_kind;
self
}
#[must_use]
pub fn success_status(mut self, success_status: u16) -> Self {
self.success_status = success_status;
self
}
#[must_use]
pub fn tag(mut self, tag: impl Into<String>) -> Self {
self.tags.push(tag.into());
self
}
#[must_use]
pub fn param(mut self, param: ParamSpec) -> Self {
self.params.push(param);
self
}
#[must_use]
pub fn params(mut self, params: Params) -> Self {
self.params = params.into_vec();
self
}
#[must_use]
pub fn calls(mut self, action: ActionRef) -> Self {
self.calls.push(action);
self
}
fn bind_handler_contract(mut self, handler: &dyn DynAction) -> Self {
if !self.input_schema.is_null() && !self.output_schema.is_null() {
return self;
}
let meta = handler.meta();
let input = serde_json::to_value(meta.input_schema);
let output = serde_json::to_value(meta.output_schema);
match (input, output) {
(Ok(input_schema), Ok(output_schema)) => {
self.input_schema = input_schema;
self.output_schema = output_schema;
}
(Err(error), _) | (_, Err(error)) => {
self.contract_error = Some(error.to_string());
}
}
self
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
fn bind_builtin_contract(
mut self,
contract: crate::action::builtin::BuiltinActionContract,
) -> Result<Self, crate::error::BaseError> {
self.input_schema = serde_json::to_value(contract.input_schema)
.map_err(|error| crate::error::BaseError::JsonSerializeFailed(error.to_string()))?;
self.output_schema = serde_json::to_value(contract.output_schema)
.map_err(|error| crate::error::BaseError::JsonSerializeFailed(error.to_string()))?;
self.permissions = contract.permissions;
self.permission_mode = contract.permission_mode;
Ok(self)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TreeViewSpec {
pub id_field: FieldRef,
pub parent_field: FieldRef,
pub label_field: FieldRef,
pub max_nodes: Option<usize>,
}
impl TreeViewSpec {
pub fn new(id_field: FieldRef, parent_field: FieldRef, label_field: FieldRef) -> Self {
Self {
id_field,
parent_field,
label_field,
max_nodes: None,
}
}
#[must_use]
pub fn max_nodes(mut self, max_nodes: usize) -> Self {
self.max_nodes = Some(max_nodes);
self
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ViewSpec {
pub name: ViewName,
pub title: String,
pub fields: Vec<FieldRef>,
pub actions: Vec<ActionRef>,
pub data_action: Option<ActionRef>,
pub action_presentations: BTreeMap<ActionRef, ActionPresentationSpec>,
pub tree: Option<TreeViewSpec>,
pub default_sort: Vec<TableSortSpec>,
}
impl ViewSpec {
pub fn new(name: ViewName) -> Self {
let title = name.to_string();
Self {
name,
title,
fields: Vec::new(),
actions: Vec::new(),
data_action: None,
action_presentations: BTreeMap::new(),
tree: None,
default_sort: Vec::new(),
}
}
#[must_use]
pub fn field(mut self, field: FieldRef) -> Self {
self.fields.push(field);
self
}
#[must_use]
pub fn action(mut self, action: ActionRef) -> Self {
self.actions.push(action);
self
}
#[must_use]
pub fn title(mut self, title: impl Into<String>) -> Self {
self.title = title.into();
self
}
#[must_use]
pub fn data_action(mut self, action: ActionRef) -> Self {
self.data_action = Some(action);
self
}
#[must_use]
pub fn present_action(
mut self,
action: ActionRef,
presentation: ActionPresentationSpec,
) -> Self {
if !self.actions.contains(&action) {
self.actions.push(action.clone());
}
self.action_presentations.insert(action, presentation);
self
}
#[must_use]
pub fn tree(mut self, tree: TreeViewSpec) -> Self {
self.tree = Some(tree);
self
}
#[must_use]
pub fn default_sort(mut self, sort: TableSortSpec) -> Self {
self.default_sort.push(sort);
self
}
}
#[derive(Clone)]
pub struct ModuleSpec {
pub name: ModuleName,
pub table: Option<TableSpec>,
actions: Vec<ActionSpec>,
handlers: Vec<Arc<dyn DynAction>>,
middlewares: Vec<Arc<dyn Middleware>>,
pub default_permissions: Vec<String>,
pub default_permission_mode: PermissionMode,
pub views: Vec<ViewSpec>,
pub presentation: Option<super::ModulePresentationSpec>,
pub datasource: Option<DatasourceId>,
}
impl ModuleSpec {
pub fn new(name: ModuleName) -> Self {
Self {
name,
table: None,
actions: Vec::new(),
handlers: Vec::new(),
middlewares: Vec::new(),
default_permissions: Vec::new(),
default_permission_mode: PermissionMode::All,
views: Vec::new(),
presentation: None,
datasource: None,
}
}
#[must_use]
pub fn datasource(mut self, id: DatasourceId) -> Self {
if let Some(table) = &mut self.table {
if table.datasource.is_none() {
table.datasource = Some(id.clone());
}
}
self.datasource = Some(id);
self
}
#[must_use]
pub fn table(mut self, mut table: TableSpec) -> Self {
if table.datasource.is_none() {
table.datasource = self.datasource.clone();
}
self.table = Some(table);
self
}
pub(crate) fn resolved_table_definition(
&self,
) -> Result<Option<crate::table::TableDefinition>, crate::error::BaseError> {
let Some(table) = &self.table else {
return Ok(None);
};
let mut table = table.clone();
if table.datasource.is_none() {
table.datasource = self.datasource.clone();
}
table.table_definition().map(Some)
}
#[must_use]
pub fn presentation(mut self, presentation: super::ModulePresentationSpec) -> Self {
self.presentation = Some(presentation);
self
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn crud(self) -> Result<Self, crate::error::BaseError> {
let prefix = format!("/api/{}", self.name.as_str().replace('.', "/"));
self.crud_at(prefix)
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn crud_at(self, prefix: impl Into<String>) -> Result<Self, crate::error::BaseError> {
use crate::action::builtin::{AddAction, DelAction, PutAction};
self.crud_at_with_mutations(prefix, AddAction::new(), PutAction::new(), DelAction::new())
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn crud_at_with_mutations<A, P, D>(
self,
prefix: impl Into<String>,
add: A,
put: P,
del: D,
) -> Result<Self, crate::error::BaseError>
where
A: DynAction,
P: DynAction,
D: DynAction,
{
use crate::action::builtin::{crud_contracts, GetAction, SelectAction, TableAction};
let prefix = prefix.into();
if prefix.len() < 2
|| !prefix.starts_with('/')
|| prefix.ends_with('/')
|| prefix.contains("//")
|| prefix.contains(['?', '#'])
{
return Err(crate::error::BaseError::ConfigError(format!(
"CRUD 资源路径无效: {prefix}"
)));
}
let table = self
.resolved_table_definition()?
.ok_or(crate::error::BaseError::TableDefinitionNotSet)?;
if table.primary_keys().len() != 1 {
return Err(crate::error::BaseError::ConfigError(format!(
"内置 CRUD 仅支持单主键表;模块 {} 的主表 {} 主键为 {:?}",
self.name,
table.name(),
table.primary_keys()
)));
}
let mut contracts: std::collections::BTreeMap<_, _> =
crud_contracts(&table, self.name.as_str())?
.into_iter()
.collect();
let module_name = self.name.to_string();
let read_permission = format!("{}:read", self.name);
let write_permission = format!("{}:write", self.name);
let action_name = |value: &str| {
ActionName::new(value)
.map_err(|error| crate::error::BaseError::ConfigError(error.to_string()))
};
let action = |name: ActionName, method, path: String| {
let operation_id = format!("{module_name}.{name}");
ActionSpec::new(name, RouteSpec::new(method, path, operation_id))
};
let mut contract = |name: &str| {
contracts.remove(name).ok_or_else(|| {
crate::error::BaseError::ConfigError(format!(
"内置 CRUD 契约缺失: {module_name}.{name}"
))
})
};
Ok(self
.action(
action(action_name("add")?, HttpMethod::Post, prefix.clone())
.display_name("新增")
.permissions([write_permission.clone()], PermissionMode::All)
.success_status(201)
.bind_builtin_contract(contract("add")?)?,
add,
)
.action(
action(action_name("put")?, HttpMethod::Put, prefix.clone())
.display_name("修改")
.permissions([write_permission.clone()], PermissionMode::All)
.bind_builtin_contract(contract("put")?)?,
put,
)
.action(
action(action_name("del")?, HttpMethod::Delete, prefix.clone())
.display_name("删除")
.permissions([write_permission], PermissionMode::All)
.bind_builtin_contract(contract("del")?)?,
del,
)
.action(
action(action_name("get")?, HttpMethod::Get, prefix.clone())
.display_name("详情")
.permissions([read_permission.clone()], PermissionMode::All)
.bind_builtin_contract(contract("get")?)?,
GetAction::new(),
)
.action(
action(
action_name("select")?,
HttpMethod::Post,
format!("{prefix}/query"),
)
.display_name("列表")
.permissions([read_permission.clone()], PermissionMode::All)
.bind_builtin_contract(contract("select")?)?,
SelectAction::new(),
)
.action(
action(
action_name("table")?,
HttpMethod::Get,
format!("{prefix}/schema"),
)
.display_name("表定义")
.permissions([read_permission], PermissionMode::All)
.bind_builtin_contract(contract("table")?)?,
TableAction::new(),
))
}
#[must_use]
pub fn action<A>(mut self, action: ActionSpec, handler: A) -> Self
where
A: DynAction,
{
self.actions.push(action.bind_handler_contract(&handler));
self.handlers.push(Arc::new(handler));
self
}
#[must_use]
pub fn dyn_action(mut self, action: ActionSpec, handler: Arc<dyn DynAction>) -> Self {
self.actions
.push(action.bind_handler_contract(handler.as_ref()));
self.handlers.push(handler);
self
}
#[must_use]
pub fn middleware<M>(mut self, middleware: M) -> Self
where
M: Middleware,
{
self.middlewares.push(Arc::new(middleware));
self
}
#[must_use]
pub fn default_permissions<I, S>(mut self, permissions: I, mode: PermissionMode) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.default_permissions = permissions.into_iter().map(Into::into).collect();
self.default_permission_mode = mode;
self
}
pub fn actions(&self) -> &[ActionSpec] {
&self.actions
}
pub(crate) fn action_pairs(&self) -> impl Iterator<Item = (&ActionSpec, &Arc<dyn DynAction>)> {
self.actions.iter().zip(&self.handlers)
}
pub(crate) fn middlewares(&self) -> &[Arc<dyn Middleware>] {
&self.middlewares
}
pub(crate) fn actions_mut(&mut self) -> &mut [ActionSpec] {
&mut self.actions
}
pub(crate) fn sort_actions(&mut self) {
let mut pairs: Vec<_> = self
.actions
.drain(..)
.zip(self.handlers.drain(..))
.collect();
pairs.sort_by(|left, right| left.0.name.cmp(&right.0.name));
for (action, handler) in pairs {
self.actions.push(action);
self.handlers.push(handler);
}
}
pub(crate) fn clear_handlers(&mut self) {
self.handlers.clear();
self.middlewares.clear();
}
#[must_use]
pub fn view(mut self, view: ViewSpec) -> Self {
self.views.push(view);
self
}
}
impl fmt::Debug for ModuleSpec {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ModuleSpec")
.field("name", &self.name)
.field("table", &self.table)
.field("actions", &self.actions)
.field("default_permissions", &self.default_permissions)
.field("default_permission_mode", &self.default_permission_mode)
.field("views", &self.views)
.finish()
}
}
impl PartialEq for ModuleSpec {
fn eq(&self, other: &Self) -> bool {
self.name == other.name
&& self.table == other.table
&& self.actions == other.actions
&& self.default_permissions == other.default_permissions
&& self.default_permission_mode == other.default_permission_mode
&& self.views == other.views
}
}
impl Eq for ModuleSpec {}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AddonSpec {
pub name: AddonName,
pub dependencies: Vec<AddonName>,
pub modules: Vec<ModuleSpec>,
pub datasource: Option<DatasourceId>,
}
impl AddonSpec {
pub fn new(name: AddonName) -> Self {
Self {
name,
dependencies: Vec::new(),
modules: Vec::new(),
datasource: None,
}
}
#[must_use]
pub fn datasource(mut self, id: DatasourceId) -> Self {
for module in &mut self.modules {
if module.datasource.is_none() {
module.datasource = Some(id.clone());
}
if let Some(table) = &mut module.table {
if table.datasource.is_none() {
table.datasource = Some(id.clone());
}
}
}
self.datasource = Some(id);
self
}
#[must_use]
pub fn depends_on(mut self, dependency: AddonName) -> Self {
self.dependencies.push(dependency);
self
}
#[must_use]
pub fn module(mut self, mut module: ModuleSpec) -> Self {
if module.datasource.is_none() {
module.datasource = self.datasource.clone();
}
if let Some(table) = &mut module.table {
if table.datasource.is_none() {
table.datasource = module.datasource.clone();
}
}
self.modules.push(module);
self
}
#[must_use]
pub fn middleware<M>(mut self, middleware: M) -> Self
where
M: Middleware,
{
let middleware: Arc<dyn Middleware> = Arc::new(middleware);
for module in &mut self.modules {
module.middlewares.insert(0, Arc::clone(&middleware));
}
self
}
}
#[cfg(test)]
mod addon_middleware_tests {
use super::*;
use crate::router::RequestIdMiddleware;
#[test]
fn addon_middleware_prepends_one_shared_instance_before_module_middleware() {
let addon = AddonSpec::new(crate::addon!("test"))
.module(ModuleSpec::new(crate::module!("test.first")).middleware(RequestIdMiddleware))
.module(ModuleSpec::new(crate::module!("test.second")))
.middleware(RequestIdMiddleware);
assert_eq!(addon.modules[0].middlewares().len(), 2);
assert_eq!(addon.modules[1].middlewares().len(), 1);
assert!(Arc::ptr_eq(
&addon.modules[0].middlewares()[0],
&addon.modules[1].middlewares()[0]
));
}
}