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}