Skip to main content

yang_base/action/
context.rs

1//! Action 执行上下文
2//!
3//! 提供 Action 执行所需的上下文环境,包含请求信息、用户信息、全局工具和表配置。
4//!
5//! # 主要组件
6//!
7//! - `ActionContext`:Action 执行上下文结构
8//! - `User`:用户信息(占位符,后续实现)
9//! - `GlobalTools`:全局工具集合(占位符,后续实现)
10
11use crate::error::BaseError;
12use crate::table::{TableConfig, TableQuery};
13#[cfg(feature = "token")]
14use crate::token::TokenManager;
15use serde::de::DeserializeOwned;
16use std::any::Any;
17use std::collections::{HashMap, HashSet};
18use std::sync::{Arc, OnceLock, RwLock};
19
20use super::Request;
21use super::RequestId;
22use super::RequestMeta;
23
24/// 全局 GlobalTools 单例
25/// 使用 OnceLock 保证线程安全的一次性初始化
26/// 内部存储 Arc<GlobalTools> 以支持废弃克隆
27/// 注意:返回的是静态引用,不需要克隆
28static GLOBAL_TOOLS: OnceLock<Arc<GlobalTools>> = OnceLock::new();
29
30/// 用户信息
31///
32/// 标注 `#[non_exhaustive]`:未来新增字段不构成破坏性变更。
33/// 请使用 [`User::new`] 构造,再通过字段赋值设置可选属性。
34#[derive(Debug, Clone)]
35#[non_exhaustive]
36pub struct User {
37    /// 用户 ID
38    pub id: i64,
39    /// 用户名
40    pub username: String,
41    /// 昵称
42    pub nickname: String,
43    /// 邮箱
44    pub email: String,
45    /// 角色集合(HashSet 保证 O(1) 查找)
46    pub roles: HashSet<String>,
47    /// 权限集合(HashSet 保证 O(1) 查找)
48    pub permissions: HashSet<String>,
49}
50
51impl User {
52    /// 创建新用户(空角色/权限)
53    pub fn new(id: i64, username: impl Into<String>) -> Self {
54        Self {
55            id,
56            username: username.into(),
57            nickname: String::new(),
58            email: String::new(),
59            roles: HashSet::new(),
60            permissions: HashSet::new(),
61        }
62    }
63
64    /// 设置角色集合(替换现有角色)
65    pub fn with_roles(mut self, roles: impl IntoIterator<Item = impl Into<String>>) -> Self {
66        self.roles = roles.into_iter().map(Into::into).collect();
67        self
68    }
69
70    /// 设置权限集合(替换现有权限)
71    pub fn with_permissions(
72        mut self,
73        permissions: impl IntoIterator<Item = impl Into<String>>,
74    ) -> Self {
75        self.permissions = permissions.into_iter().map(Into::into).collect();
76        self
77    }
78
79    /// 检查是否有指定权限(O(1) HashSet 查找)
80    pub fn has_permission(&self, permission: &str) -> bool {
81        self.permissions.contains(permission)
82    }
83
84    /// 检查是否有指定角色(O(1) HashSet 查找)
85    pub fn has_role(&self, role: &str) -> bool {
86        self.roles.contains(role)
87    }
88
89    /// 检查是否有任一角色(O(1) 每角色)
90    pub fn has_any_role(&self, roles: &[String]) -> bool {
91        roles.iter().any(|r| self.has_role(r))
92    }
93}
94
95/// 全局工具集合
96#[derive(Debug)]
97pub struct GlobalTools {
98    /// Token 管理器
99    #[cfg(feature = "token")]
100    token_manager: Arc<TokenManager>,
101    /// 自定义工具注册表
102    tools: Arc<RwLock<HashMap<String, Arc<dyn Any + Send + Sync>>>>,
103}
104
105impl GlobalTools {
106    /// 创建新的全局工具集合(启用 token feature)
107    #[cfg(feature = "token")]
108    pub fn new(token_manager: TokenManager) -> Self {
109        Self {
110            token_manager: Arc::new(token_manager),
111            tools: Arc::new(RwLock::new(HashMap::new())),
112        }
113    }
114
115    /// 创建新的全局工具集合(未启用 token feature)
116    #[cfg(not(feature = "token"))]
117    #[allow(clippy::new_without_default)]
118    pub fn new() -> Self {
119        Self {
120            tools: Arc::new(RwLock::new(HashMap::new())),
121        }
122    }
123
124    /// 注册自定义工具
125    pub fn register_tool<T: Any + Send + Sync>(
126        &self,
127        name: &str,
128        tool: Arc<T>,
129    ) -> Result<(), BaseError> {
130        let name = name.trim();
131        if name.is_empty() {
132            return Err(BaseError::ConfigError("工具名称不能为空".to_string()));
133        }
134
135        // 使用 unwrap_or_else 处理锁中毒:即使锁中毒也能恢复数据并继续注册
136        let mut tools = self.tools.write().unwrap_or_else(|p| p.into_inner());
137        if tools.contains_key(name) {
138            return Err(BaseError::ConfigError(format!("工具已注册: {}", name)));
139        }
140        tools.insert(name.to_string(), tool);
141        Ok(())
142    }
143
144    /// 获取已注册的工具
145    pub fn get_tool<T: Any + Send + Sync>(&self, name: &str) -> Option<Arc<T>> {
146        let name = name.trim();
147        if name.is_empty() {
148            return None;
149        }
150
151        // 使用 unwrap_or_else 处理锁中毒:即使锁中毒也能恢复数据并继续读取
152        let tools = self.tools.read().unwrap_or_else(|p| p.into_inner());
153        tools
154            .get(name)
155            .and_then(|tool| tool.clone().downcast::<T>().ok())
156    }
157
158    /// 获取 Token 管理器
159    #[cfg(feature = "token")]
160    pub fn token_manager(&self) -> &TokenManager {
161        &self.token_manager
162    }
163
164    /// 初始化全局 GlobalTools 单例(启用 token feature)
165    ///
166    /// 使用 `OnceLock` 保证只能初始化一次,线程安全。
167    ///
168    /// # 参数
169    ///
170    /// - `token_manager`: JWT 令牌管理器
171    ///
172    /// # 返回
173    ///
174    /// - `Ok(())`: 初始化成功
175    /// - `Err(BaseError::ConfigError)`: 已经初始化过,重复调用
176    ///
177    /// # 错误
178    ///
179    /// - `BaseError::ConfigError("GlobalTools 已初始化")`: 重复初始化时返回
180    #[cfg(feature = "token")]
181    pub fn init(token_manager: TokenManager) -> Result<(), BaseError> {
182        // 尝试设置全局单例,若已初始化则返回错误
183        GLOBAL_TOOLS
184            .set(Arc::new(GlobalTools::new(token_manager)))
185            .map_err(|_| BaseError::ConfigError("GlobalTools 已初始化".to_string()))
186    }
187
188    /// 初始化全局 GlobalTools 单例(未启用 token feature)
189    ///
190    /// 使用 `OnceLock` 保证只能初始化一次,线程安全。
191    ///
192    /// # 返回
193    ///
194    /// - `Ok(())`: 初始化成功
195    /// - `Err(BaseError::ConfigError)`: 已经初始化过,重复调用
196    ///
197    /// # 错误
198    ///
199    /// - `BaseError::ConfigError("GlobalTools 已初始化")`: 重复初始化时返回
200    #[cfg(not(feature = "token"))]
201    pub fn init() -> Result<(), BaseError> {
202        // 尝试设置全局单例,若已初始化则返回错误
203        GLOBAL_TOOLS
204            .set(Arc::new(GlobalTools::new()))
205            .map_err(|_| BaseError::ConfigError("GlobalTools 已初始化".to_string()))
206    }
207
208    /// 获取全局 GlobalTools 单例引用
209    ///
210    /// # 返回
211    ///
212    /// - `Ok(&'static GlobalTools)`: 全局实例的静态引用
213    /// - `Err(BaseError::ConfigError)`: 尚未初始化
214    ///
215    /// # 错误
216    ///
217    /// - `BaseError::ConfigError("GlobalTools 未初始化")`: 在调用 `init` 之前调用此方法时返回
218    pub fn get() -> Result<&'static GlobalTools, BaseError> {
219        // 获取全局单例,若未初始化则返回错误
220        GLOBAL_TOOLS
221            .get()
222            .map(|arc| arc.as_ref())
223            .ok_or_else(|| BaseError::ConfigError("GlobalTools 未初始化".to_string()))
224    }
225
226    /// 获取全局 GlobalTools 的 Arc 引用(内部使用)
227    ///
228    /// 返回 Arc 克隆,允许将全局单例嵌入到 ActionContext 中
229    pub(crate) fn get_arc() -> Result<Arc<GlobalTools>, BaseError> {
230        // 获取全局单例的 Arc 克隆(廉价操作)
231        GLOBAL_TOOLS
232            .get()
233            .cloned()
234            .ok_or_else(|| BaseError::ConfigError("GlobalTools 未初始化".to_string()))
235    }
236}
237
238/// Action 执行上下文
239///
240/// 包含 Action 执行所需的所有信息,包括请求数据、传输元数据、用户信息、全局工具和表配置。
241///
242/// 标注 `#[non_exhaustive]`:未来新增运行期字段(如 trace_id)不构成破坏性变更,
243/// 调用方请用 [`ActionContext::new`] / [`ActionContext::new_with_global_tools`]
244/// 构造,而非结构体字面量。
245#[derive(Debug)]
246#[non_exhaustive]
247pub struct ActionContext {
248    /// 请求数据
249    pub request: Request,
250    /// 与具体 Web 框架无关的传输元数据。
251    pub request_meta: RequestMeta,
252    /// 当前用户(已认证)
253    // SAFETY: 此字段为 pub(crate),仅 crate 内中间件(如 TokenAuthMiddleware)可注入。
254    // 外部 crate 无法直接设置此字段,防止绕过认证。
255    pub(crate) user: Option<User>,
256    /// 全局工具
257    pub tools: Arc<GlobalTools>,
258    /// 表配置(如果 action 关联表)
259    pub table_config: Option<Arc<TableConfig>>,
260    /// 本次派发的运行期标识,用于串联日志/span/metrics/审计。
261    ///
262    /// 由 `new`/`new_with_global_tools` 默认生成;`RequestIdMiddleware` 在洋葱链
263    /// 最外层会按上游 `X-Request-Id` 透传或重新生成并 `span.record`。
264    pub request_id: RequestId,
265    /// 本次派发所属模块名(由 `ModuleRouter::dispatch` 注入)。
266    ///
267    /// 仅用于可观测性标注(metrics `module` 标签、日志)。模块数量有界,作为 metrics
268    /// 标签不构成高基数问题。未经路由直接构造的上下文为 `None`。
269    pub module: Option<String>,
270    /// PERF-13: 缓存用户角色的 Arc 副本,避免 table_query() 每次重新 Arc 化。
271    /// 在 `with_user()` 时一次性构建,后续 `table_query()` 仅需 `Arc::clone`(O(1))。
272    #[allow(dead_code)]
273    cached_roles: Arc<[String]>,
274}
275
276impl ActionContext {
277    /// 创建新的上下文
278    pub fn new(request: Request, tools: Arc<GlobalTools>) -> Self {
279        Self {
280            request,
281            request_meta: RequestMeta::default(),
282            user: None,
283            tools,
284            table_config: None,
285            request_id: RequestId::generate(),
286            module: None,
287            cached_roles: Arc::from(Vec::new()),
288        }
289    }
290
291    /// 使用全局单例创建新的上下文
292    ///
293    /// 自动从全局单例获取 `GlobalTools`,无需手动传入。
294    ///
295    /// # 参数
296    ///
297    /// - `request`: 请求数据
298    ///
299    /// # 返回
300    ///
301    /// - `Ok(ActionContext)`: 创建成功
302    /// - `Err(BaseError::ConfigError)`: 全局单例未初始化
303    ///
304    /// # 错误
305    ///
306    /// - `BaseError::ConfigError("GlobalTools 未初始化")`: 在调用 `GlobalTools::init` 之前调用此方法时返回
307    pub fn new_with_global_tools(request: Request) -> Result<Self, BaseError> {
308        // 从全局单例获取 GlobalTools 的 Arc 克隆(廉价操作)
309        let tools = GlobalTools::get_arc()?;
310        Ok(Self {
311            request,
312            request_meta: RequestMeta::default(),
313            user: None,
314            tools,
315            table_config: None,
316            request_id: RequestId::generate(),
317            module: None,
318            cached_roles: Arc::from(Vec::new()),
319        })
320    }
321
322    /// 设置用户(链式调用)
323    ///
324    /// 仅供 crate 内中间件/内部使用。调用方有责任确保 user 已经过认证(如 TokenAuthMiddleware),
325    /// 直接注入未验证的 User 将绕过所有鉴权。
326    #[allow(dead_code)]
327    pub(crate) fn with_user(mut self, user: User) -> Self {
328        self.user = Some(user);
329        self
330    }
331
332    /// 获取已认证用户的只读引用。
333    ///
334    /// 外部调用方只能读取认证结果,不能手动注入用户;用户注入仅由 crate 内受信任
335    /// 中间件(如 `TokenAuthMiddleware`)完成。
336    pub fn authenticated_user(&self) -> Option<&User> {
337        self.user.as_ref()
338    }
339
340    /// 设置本次派发的 request_id(链式调用)
341    ///
342    /// 通常由 `RequestIdMiddleware` 在洋葱链最外层调用以透传上游标识;
343    /// 业务侧一般无需手动设置。
344    pub fn with_request_id(mut self, request_id: RequestId) -> Self {
345        self.request_id = request_id;
346        self
347    }
348
349    /// 注入由传输适配器构造的请求元数据(链式调用)。
350    pub fn with_request_meta(mut self, request_meta: RequestMeta) -> Self {
351        self.request_meta = request_meta;
352        self
353    }
354
355    /// 设置所属模块名(链式调用)。
356    ///
357    /// 由 `ModuleRouter::dispatch` 注入,用于 metrics `module` 标签等可观测性标注。
358    pub fn with_module(mut self, module: impl Into<String>) -> Self {
359        self.module = Some(module.into());
360        self
361    }
362
363    /// 设置表配置(链式调用)
364    pub fn with_table_config(mut self, config: Arc<TableConfig>) -> Self {
365        self.table_config = Some(config);
366        self
367    }
368
369    /// 把整个请求体反序列化为 `I`。新类型化 Action 系统的统一参数提取入口。
370    ///
371    /// # 错误
372    ///
373    /// - `BaseError::ParamInvalid("body", ...)`: 反序列化失败(缺字段/类型错/未知字段等)
374    pub fn extract_input<I: DeserializeOwned>(&self) -> Result<I, BaseError> {
375        serde_json::from_value(self.request.body.clone())
376            .map_err(|e| BaseError::ParamInvalid("body".to_string(), e.to_string()))
377    }
378
379    /// 零拷贝版本:用 `std::mem::take` 替代 clone 请求体。
380    ///
381    /// 调用后 `self.request.body` 变为 `Value::Null`,仅在不再需要 body 时使用。
382    /// 仅限 crate 内部使用(`DynAction::dispatch` blanket impl 中 ctx 仅需传给 handle)。
383    pub(crate) fn extract_input_owned<I: DeserializeOwned>(&mut self) -> Result<I, BaseError> {
384        let body = std::mem::take(&mut self.request.body);
385        serde_json::from_value(body)
386            .map_err(|e| BaseError::ParamInvalid("body".to_string(), e.to_string()))
387    }
388
389    /// 获取请求体参数(可选,严格模式)
390    ///
391    /// 从请求体中获取指定参数:
392    /// - 参数不存在:返回 `Ok(None)`
393    /// - 参数存在且类型匹配:返回 `Ok(Some(T))`
394    /// - 参数存在但类型不匹配:返回 `Err(BaseError::ParamInvalid)`
395    ///
396    /// > **H-1 迁移说明**:此方法是 H-1 重构期间保留的旧式严格可选提取变体。
397    /// > 新代码请使用 [`ActionContext::extract_input`],它通过强类型输入结构体统一处理所有参数提取。
398    /// > 本方法将在 Task 6/7 完成后移除。
399    ///
400    /// # 参数
401    ///
402    /// - `key`: 参数名
403    ///
404    /// # 返回
405    ///
406    /// - `Ok(Some(T))`: 参数存在且类型匹配
407    /// - `Ok(None)`: 参数不存在
408    /// - `Err(BaseError::ParamInvalid)`: 参数存在但类型不匹配
409    #[deprecated(note = "H-1 重构期间停用,将在 Task 6/7 后移除;请改用 extract_input")]
410    #[allow(dead_code)]
411    pub(crate) fn param_optional_strict<T: DeserializeOwned>(
412        &self,
413        key: &str,
414    ) -> Result<Option<T>, BaseError> {
415        if key.trim().is_empty() {
416            return Err(BaseError::ParamInvalid(
417                key.to_string(),
418                "参数名不能为空".to_string(),
419            ));
420        }
421
422        match self.request.body.get(key) {
423            // 参数不存在,返回 None
424            None => Ok(None),
425            // 参数存在,尝试反序列化
426            Some(value) => serde_json::from_value::<T>(value.clone())
427                .map(Some)
428                .map_err(|_| {
429                    BaseError::ParamInvalid(
430                        key.to_string(),
431                        format!("参数 '{}' 存在但无法转换为目标类型", key),
432                    )
433                }),
434        }
435    }
436
437    /// 获取路径参数(必填)
438    ///
439    /// 从 `request.path_params` 中获取指定路径参数,并尝试反序列化为目标类型。
440    ///
441    /// # 参数
442    ///
443    /// - `key`: 路径参数名
444    ///
445    /// # 返回
446    ///
447    /// - `Ok(T)`: 参数值
448    /// - `Err(BaseError::ParamMissing)`: 路径参数不存在
449    /// - `Err(BaseError::ParamInvalid)`: 参数值无法转换为目标类型
450    pub fn path_param<T: DeserializeOwned>(&self, key: &str) -> Result<T, BaseError> {
451        let key = key.trim();
452        if key.is_empty() {
453            return Err(BaseError::ParamInvalid(
454                key.to_string(),
455                "路径参数名不能为空".to_string(),
456            ));
457        }
458
459        // 从路径参数中获取字符串值
460        let raw = self
461            .request
462            .path_params
463            .get(key)
464            .ok_or_else(|| BaseError::ParamMissing(key.to_string()))?;
465
466        // 先尝试将原始字符串直接反序列化为目标类型(支持数字、布尔等 JSON 字面量)。
467        // 若失败,则包裹为 JSON 字符串再尝试(数字形式的值如 "123" 在 String 目标下仍应可用)。
468        serde_json::from_str::<T>(raw)
469            .or_else(|_| serde_json::from_value(serde_json::Value::String(raw.clone())))
470            .map_err(|_| {
471                BaseError::ParamInvalid(
472                    key.to_string(),
473                    format!("路径参数 '{}' 无法转换为目标类型,原始值: {}", key, raw),
474                )
475            })
476    }
477
478    /// 创建表查询构建器
479    ///
480    /// 基于当前上下文的表配置和用户角色创建 TableQuery 实例。启用 `mysql`
481    /// feature 时,自动从 [`GlobalDatabase`](crate::database::GlobalDatabase)
482    /// 注入共享连接池,使内置 CRUD Action 能直接执行数据库操作;若全局数据库
483    /// 尚未初始化,则连接池为 `None`,相关执行方法会在调用时返回
484    /// `BaseError::DatabaseNotInitialized`。
485    ///
486    /// # 返回
487    ///
488    /// - `Ok(TableQuery)`: 查询构建器
489    /// - `Err(BaseError::TableConfigNotSet)`: 表配置未设置
490    pub fn table_query(&self) -> Result<TableQuery, BaseError> {
491        let config = self
492            .table_config
493            .as_ref()
494            .ok_or(BaseError::TableConfigNotSet)?;
495
496        // 将用户角色 HashSet 转为 Vec 再打包为 Arc(table_query 需要 Vec)
497        let roles_set = self.user_roles_set();
498        let user_roles: Arc<[String]> = Arc::from(
499            roles_set
500                .map(|s| s.iter().cloned().collect::<Vec<_>>())
501                .unwrap_or_default(),
502        );
503
504        // 启用 mysql feature 时,从全局数据库注入连接池(未初始化则为 None)。
505        #[cfg(feature = "mysql")]
506        let pool = crate::database::GlobalDatabase::get()
507            .ok()
508            .map(|db| Arc::new(db.pool().clone()));
509        #[cfg(not(feature = "mysql"))]
510        let pool = None;
511
512        // 注入可观测性:慢查询阈值(全局配置)+ 本次派发 request_id,
513        // 使受保护层执行边界能在超阈值时 warn 并串联 request_id。
514        let slow_threshold = crate::observability::ObservabilityConfig::get().slow_query_threshold;
515        Ok(TableQuery::new(config.clone(), user_roles, pool)
516            .with_slow_threshold(slow_threshold)
517            .with_request_id(self.request_id))
518    }
519
520    /// 开启一个数据库事务(受保护层多步写的原子作用域)
521    ///
522    /// 返回 [`yang_db::Transaction`],可传入 `TableQuery` 的 `*_in_tx` 系列方法
523    /// (`insert_in_tx`/`update_in_tx`/`delete_in_tx`/`select_in_tx` 等),使受
524    /// 权限/校验/软删保护的多步写在同一事务内原子提交或整体回滚。调用方负责
525    /// 显式 `commit()`;若 `Transaction` 在未提交时被 drop,sqlx 会尽力回滚。
526    ///
527    /// 仅在启用 `mysql` feature 时可用。
528    ///
529    /// # 返回
530    ///
531    /// - `Ok(Transaction)`:活动事务
532    /// - `Err(BaseError::DatabaseNotInitialized)`:全局数据库未初始化
533    /// - `Err(BaseError::DatabaseTransactionFailed)`:开启事务失败
534    ///
535    /// # 示例
536    ///
537    /// ```rust,ignore
538    /// let mut tx = ctx.begin_transaction().await?;
539    /// let id = ctx.table_query()?.insert_returning_id_in_tx(&mut tx, parent).await?.1;
540    /// ctx.table_query()?.insert_in_tx(&mut tx, child_with(id)).await?;
541    /// tx.commit().await?;
542    /// ```
543    #[cfg(feature = "mysql")]
544    pub async fn begin_transaction(&self) -> Result<yang_db::Transaction, BaseError> {
545        crate::database::GlobalDatabase::transaction().await
546    }
547
548    /// 获取用户角色列表(克隆为 Vec)
549    ///
550    /// # 返回
551    ///
552    /// - 用户角色列表(如果用户未登录则返回空列表)
553    pub fn user_roles(&self) -> Vec<String> {
554        self.user
555            .as_ref()
556            .map(|u| u.roles.iter().cloned().collect())
557            .unwrap_or_default()
558    }
559
560    /// 获取用户角色集合引用
561    ///
562    /// 返回用户角色的 HashSet 引用,支持 O(1) 包含检查。
563    /// 如果用户未登录则返回 `None`。
564    ///
565    /// # 返回
566    ///
567    /// - `Some(&HashSet<String>)`: 用户角色集合引用
568    /// - `None`: 用户未登录
569    pub fn user_roles_set(&self) -> Option<&HashSet<String>> {
570        self.user.as_ref().map(|u| &u.roles)
571    }
572}