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}