Skip to main content

yang_base/action/
action_trait.rs

1//! Action 权限类型定义
2//!
3//! 本模块保留 [`Permission`] 权限类型。Action 行为契约已迁移到类型化的
4//! [`TypedHandler`](crate::action::TypedHandler) / [`TypedAction`](crate::action::TypedAction) /
5//! [`DynAction`](crate::action::DynAction) 三层 trait(见 `action/typed.rs`),
6//! 旧的对象安全 `Action` trait 已随 H-1 类型化重构移除。
7//!
8//! # 主要组件
9//!
10//! - `Permission`:权限类型,表示 action 所需的权限
11//!
12//! # 示例
13//!
14//! ```rust,ignore
15//! use yang_base::action::Permission;
16//!
17//! let permission = Permission::from_static("user:create");
18//! assert_eq!(permission.name(), "user:create");
19//! ```
20
21use std::borrow::Cow;
22
23/// 权限匹配模式
24///
25/// 决定多个权限之间的逻辑关系:
26/// - `All`(AND):用户必须同时拥有全部权限(默认行为,向后兼容)
27/// - `Any`(OR):用户只需拥有其中任一权限
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
29pub enum PermissionMode {
30    /// AND 语义:用户必须拥有全部权限(默认)
31    #[default]
32    All,
33    /// OR 语义:用户只需拥有其中任一权限
34    Any,
35}
36
37/// 权限类型
38///
39/// 表示 action 所需的权限,用于权限检查。
40///
41/// # 字段
42///
43/// - `name`: 权限名称(如 "user:create", "order:read")
44///
45/// # 示例
46///
47/// ```rust,ignore
48/// use yang_base::action::Permission;
49///
50/// // 创建权限
51/// let permission = Permission::new("user:create");
52/// assert_eq!(permission.name(), "user:create");
53/// ```
54#[derive(Debug, Clone, PartialEq, Eq, Hash)]
55pub struct Permission {
56    /// 权限名称,使用 Cow 支持零拷贝静态字符串和动态字符串
57    name: Cow<'static, str>,
58}
59
60impl Permission {
61    /// 创建新权限
62    ///
63    /// # 参数
64    ///
65    /// - `name`: 权限名称
66    ///
67    /// # 返回
68    ///
69    /// - 新的 Permission 实例
70    ///
71    /// # 示例
72    ///
73    /// ```rust,ignore
74    /// use yang_base::action::Permission;
75    ///
76    /// let permission = Permission::new("user:create");
77    /// ```
78    pub fn new(name: impl Into<String>) -> Self {
79        // 动态字符串存储为 Cow::Owned(堆分配)
80        Self {
81            name: Cow::Owned(name.into()),
82        }
83    }
84
85    /// 从静态字符串创建权限(零拷贝,无堆分配)
86    ///
87    /// # 参数
88    ///
89    /// - `name`: 静态字符串字面量
90    ///
91    /// # 返回
92    ///
93    /// - 新的 Permission 实例(内部使用 Cow::Borrowed,无堆分配)
94    ///
95    /// # 示例
96    ///
97    /// ```rust,ignore
98    /// use yang_base::action::Permission;
99    ///
100    /// let permission = Permission::from_static("user:create");
101    /// assert_eq!(permission.name(), "user:create");
102    /// ```
103    pub fn from_static(name: &'static str) -> Self {
104        // 静态字符串存储为 Cow::Borrowed(零拷贝)
105        Self {
106            name: Cow::Borrowed(name),
107        }
108    }
109
110    /// 获取权限名称
111    ///
112    /// # 返回
113    ///
114    /// - 权限名称字符串引用
115    ///
116    /// # 示例
117    ///
118    /// ```rust,ignore
119    /// use yang_base::action::Permission;
120    ///
121    /// let permission = Permission::new("user:create");
122    /// assert_eq!(permission.name(), "user:create");
123    /// ```
124    pub fn name(&self) -> &str {
125        // Cow<'static, str> 自动解引用为 &str
126        &self.name
127    }
128}
129
130impl std::fmt::Display for Permission {
131    /// 输出权限名称,等同于 [`Permission::name()`]
132    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
133        f.write_str(&self.name)
134    }
135}
136
137impl From<&'static str> for Permission {
138    /// 从静态字符串创建权限(零拷贝,等同于 [`Permission::from_static`])
139    fn from(value: &'static str) -> Self {
140        Self::from_static(value)
141    }
142}
143
144impl From<String> for Permission {
145    /// 从动态字符串创建权限(等同于 [`Permission::new`])
146    fn from(value: String) -> Self {
147        Self::new(value)
148    }
149}