pub const BUILTIN_ACTION_NAMES: &[&str] = &["add", "put", "del", "get", "select", "table"];
use crate::action::{ActionContext, ApiResponse, DynAction, PermissionMode, User};
use crate::error::BaseError;
use crate::router::catalog::{ActionDescriptor, ModuleDescriptor, RouteDescriptor};
use crate::router::middleware::{Middleware, Next};
use crate::table::TableConfig;
use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use tracing::Instrument;
#[must_use = "builder 返回新实例,忽略将丢失配置"]
pub struct ModuleRouter {
module_name: String,
display_name: String,
table_config: Option<Arc<TableConfig>>,
actions: HashMap<String, Arc<dyn DynAction>>,
routes: HashMap<String, RouteDescriptor>,
default_permissions: Vec<String>,
default_permission_mode: PermissionMode,
middlewares: Vec<Arc<dyn Middleware>>,
}
impl ModuleRouter {
pub fn new(module_name: impl Into<String>, display_name: impl Into<String>) -> Self {
Self {
module_name: module_name.into(),
display_name: display_name.into(),
table_config: None,
actions: HashMap::new(),
routes: HashMap::new(),
default_permissions: Vec::new(),
default_permission_mode: PermissionMode::default(),
middlewares: Vec::new(),
}
}
pub fn with_table_config(mut self, config: Arc<TableConfig>) -> Self {
self.table_config = Some(config);
self
}
#[deprecated(note = "请用 with_table_config")]
pub fn table_config(self, config: Arc<TableConfig>) -> Self {
self.with_table_config(config)
}
pub fn default_permissions(mut self, permissions: Vec<String>) -> Result<Self, BaseError> {
if permissions
.iter()
.any(|permission| permission.trim().is_empty())
{
return Err(BaseError::ConfigError("默认权限名称不能为空".to_string()));
}
let mut seen = HashSet::with_capacity(permissions.len());
for permission in &permissions {
if !seen.insert(permission.as_str()) {
return Err(BaseError::ConfigError(format!(
"默认权限重复: {}",
permission
)));
}
}
self.default_permissions = permissions;
Ok(self)
}
pub fn default_permission_mode(mut self, mode: PermissionMode) -> Self {
self.default_permission_mode = mode;
self
}
pub fn register_action<A>(mut self, action: A) -> Result<Self, BaseError>
where
A: crate::action::TypedAction,
{
let action: Arc<dyn DynAction> = Arc::new(action);
let meta = action.meta();
let name = meta.name.to_string();
if name.trim().is_empty() {
return Err(BaseError::ConfigError("Action 名称不能为空".to_string()));
}
if meta
.permissions
.iter()
.any(|permission| permission.name().trim().is_empty())
{
return Err(BaseError::ConfigError(
"Action 权限名称不能为空".to_string(),
));
}
if self.actions.contains_key(&name) {
return Err(BaseError::ConfigError(format!("Action 已注册: {}", name)));
}
self.actions.insert(name, action);
Ok(self)
}
pub fn register_route(
mut self,
action_name: impl Into<String>,
route: RouteDescriptor,
) -> Result<Self, BaseError> {
route.validate()?;
let action_name = action_name.into();
if !self.actions.contains_key(&action_name) {
return Err(BaseError::ConfigError(format!(
"route 对应的 Action 未注册: {action_name}"
)));
}
if self.routes.contains_key(&action_name) {
return Err(BaseError::ConfigError(format!(
"Action route 已注册: {action_name}"
)));
}
if self
.routes
.values()
.any(|existing| existing.method == route.method && existing.path == route.path)
{
return Err(BaseError::ConfigError(format!(
"route 冲突: {} {}",
route.method, route.path
)));
}
if self
.routes
.values()
.any(|existing| existing.operation_id == route.operation_id)
{
return Err(BaseError::ConfigError(format!(
"operation_id 冲突: {}",
route.operation_id
)));
}
self.routes.insert(action_name, route);
Ok(self)
}
pub fn descriptor(&self) -> Result<ModuleDescriptor, BaseError> {
let mut action_names: Vec<&String> = self.actions.keys().collect();
action_names.sort();
let mut actions = Vec::with_capacity(action_names.len());
for name in action_names {
let action = &self.actions[name];
let meta = action.meta();
let route = self
.routes
.get(name)
.ok_or_else(|| BaseError::ConfigError(format!("Action 缺少 route: {name}")))?;
actions.push(ActionDescriptor {
name: meta.name.to_string(),
display_name: meta.display_name.to_string(),
description: meta.description.to_string(),
permissions: meta
.permissions
.iter()
.map(|permission| permission.name().to_string())
.collect(),
permission_mode: meta.permission_mode,
is_public: meta.is_public,
input_schema: meta.input_schema.clone(),
output_schema: meta.output_schema.clone(),
route: route.clone(),
});
}
Ok(ModuleDescriptor {
name: self.module_name.clone(),
display_name: self.display_name.clone(),
default_permissions: self.default_permissions.clone(),
default_permission_mode: self.default_permission_mode,
actions,
})
}
pub fn middleware<M>(mut self, middleware: M) -> Self
where
M: Middleware,
{
self.middlewares.push(Arc::new(middleware));
self
}
#[cfg(feature = "mysql")]
pub fn table_typed<T>(self) -> Result<Self, BaseError>
where
T: crate::table::TableEntity,
{
use crate::action::builtin::{
AddAction, DelAction, GetAction, PutAction, SelectAction, TableAction,
};
if self.table_config.is_none() {
return Err(BaseError::TableConfigNotSet);
}
self.register_action(AddAction::<T>::new())?
.register_action(PutAction::<T>::new())?
.register_action(DelAction::<T>::new())?
.register_action(GetAction::<T>::new())?
.register_action(SelectAction::<T>::new())?
.register_action(TableAction::<T>::new())
}
pub async fn dispatch(
&self,
action_name: &str,
mut context: ActionContext,
) -> Result<ApiResponse, BaseError> {
if self.middlewares.is_empty() && self.actions.values().any(|a| !a.meta().is_public) {
tracing::warn!(
module = %self.module_name,
"模块 '{}' 包含非公开 Action 但未注册认证中间件(如 TokenAuthMiddleware)",
self.module_name,
);
}
let action = self
.actions
.get(action_name)
.ok_or_else(|| BaseError::ActionNotFound(action_name.to_string()))?
.clone();
if let Some(table_config) = &self.table_config {
context = context.with_table_config(table_config.clone());
}
if context.module.is_none() {
context = context.with_module(self.module_name.clone());
}
let next = Next {
remaining: &self.middlewares,
router: self,
action,
};
let span = tracing::info_span!(
"dispatch",
module = %self.module_name,
action = %action_name,
request_id = tracing::field::Empty,
);
span.record("request_id", tracing::field::display(context.request_id));
next.run(context).instrument(span).await
}
pub(crate) async fn authorize_and_dispatch(
&self,
action: Arc<dyn DynAction>,
context: ActionContext,
) -> Result<ApiResponse, BaseError> {
let meta = action.meta();
let span = tracing::info_span!(
"authorize",
is_public = meta.is_public,
granted = tracing::field::Empty,
);
let _enter = span.enter();
if !meta.is_public {
let user = context.user.as_ref().ok_or_else(|| {
span.record("granted", false);
BaseError::Unauthorized("需要登录".to_string())
})?;
if !self.default_permissions.is_empty()
&& !self.check_permissions(
user,
&self.default_permissions,
self.default_permission_mode,
)
{
span.record("granted", false);
return Err(BaseError::PermissionDenied(format!(
"缺少模块权限: {:?}",
self.default_permissions
)));
}
let action_perm_ok = match meta.permission_mode {
PermissionMode::All => meta
.permissions
.iter()
.all(|p| user.has_permission(p.name())),
PermissionMode::Any => meta
.permissions
.iter()
.any(|p| user.has_permission(p.name())),
};
if !meta.permissions.is_empty() && !action_perm_ok {
span.record("granted", false);
let permission_names: Vec<&str> =
meta.permissions.iter().map(|p| p.name()).collect();
return Err(BaseError::PermissionDenied(format!(
"缺少 Action 权限: {:?}",
permission_names
)));
}
}
span.record("granted", true);
drop(_enter);
action.dispatch(context).await
}
pub async fn dispatch_with_global(
&self,
action_name: &str,
request: crate::action::Request,
) -> Result<ApiResponse, BaseError> {
let context = ActionContext::new_with_global_tools(request)?;
self.dispatch(action_name, context).await
}
fn check_permissions(
&self,
user: &User,
required_permissions: &[String],
mode: PermissionMode,
) -> bool {
match mode {
PermissionMode::All => required_permissions
.iter()
.all(|perm| user.has_permission(perm)),
PermissionMode::Any => required_permissions
.iter()
.any(|perm| user.has_permission(perm)),
}
}
pub fn module_name(&self) -> &str {
&self.module_name
}
pub fn display_name(&self) -> &str {
&self.display_name
}
pub fn action_names(&self) -> Vec<String> {
let mut names: Vec<String> = self.actions.keys().cloned().collect();
names.sort();
names
}
pub fn get_table_config(&self) -> Option<&Arc<TableConfig>> {
self.table_config.as_ref()
}
}