Skip to main content

yang_base/plugin/
traits.rs

1//! 插件接口(`Plugin` trait)与生命周期类型定义。
2
3use async_trait::async_trait;
4use serde_json::Value as JsonValue;
5use std::fmt;
6
7/// 插件生命周期回调的结构化错误类型。
8pub type PluginError = Box<dyn std::error::Error + Send + Sync + 'static>;
9
10/// 插件生命周期阶段。
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12#[non_exhaustive]
13pub enum PluginLifecycleStage {
14    /// 注册回调。
15    Register,
16    /// 初始化 SQL 或初始化回调。
17    Initialize,
18    /// 关闭回调。
19    Shutdown,
20}
21
22impl fmt::Display for PluginLifecycleStage {
23    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
24        formatter.write_str(match self {
25            Self::Register => "register",
26            Self::Initialize => "initialize",
27            Self::Shutdown => "shutdown",
28        })
29    }
30}
31
32/// 插件接口
33///
34/// 所有插件必须实现此 trait
35///
36/// # 示例
37///
38/// ```rust,ignore
39/// use yang_base::plugin::Plugin;
40/// use async_trait::async_trait;
41///
42/// struct MyPlugin;
43///
44/// #[async_trait]
45/// impl Plugin for MyPlugin {
46///     fn name(&self) -> &str {
47///         "my_plugin"
48///     }
49///     
50///     fn version(&self) -> &str {
51///         "1.0.0"
52///     }
53///     
54/// }
55/// ```
56#[async_trait]
57pub trait Plugin: Send + Sync {
58    /// 获取插件名称
59    ///
60    /// 插件名称必须唯一,用于标识和查找插件
61    ///
62    /// # 返回
63    /// - 插件名称字符串
64    fn name(&self) -> &str;
65
66    /// 获取插件版本
67    ///
68    /// 使用语义化版本号,格式:major.minor.patch
69    ///
70    /// # 返回
71    /// - 版本号字符串,默认为 "0.1.0"
72    fn version(&self) -> &str {
73        "0.1.0"
74    }
75
76    /// 获取插件依赖列表
77    ///
78    /// 返回当前插件依赖的其他插件名称列表
79    /// 系统会确保依赖插件先于当前插件初始化
80    ///
81    /// # 返回
82    /// - 依赖插件名称列表,默认为空
83    fn dependencies(&self) -> &[&str] {
84        &[]
85    }
86
87    /// 获取插件配置 Schema
88    ///
89    /// 返回 JSON Schema 格式的配置定义
90    ///
91    /// # 返回
92    /// - Some(JsonValue): 配置 Schema
93    /// - None: 无配置要求(默认)
94    fn config_schema(&self) -> Option<JsonValue> {
95        None
96    }
97
98    /// 插件注册时的回调
99    ///
100    /// 在插件被注册到 PluginManager 时调用
101    ///
102    /// # 返回
103    /// - Ok(()): 注册成功
104    /// - Err: 注册失败
105    async fn on_register(&self) -> Result<(), PluginError> {
106        Ok(())
107    }
108
109    /// 数据库初始化后的回调
110    ///
111    /// 在插件的数据库表创建完成后调用
112    /// 可用于插入初始数据或执行其他初始化逻辑
113    ///
114    /// # 返回
115    /// - Ok(()): 初始化成功
116    /// - Err: 初始化失败
117    async fn on_init(&self) -> Result<(), PluginError> {
118        Ok(())
119    }
120
121    /// 系统关闭时的回调
122    ///
123    /// 在系统关闭时调用,用于清理资源
124    ///
125    /// # 返回
126    /// - Ok(()): 关闭成功
127    /// - Err: 关闭失败
128    async fn on_shutdown(&self) -> Result<(), PluginError> {
129        Ok(())
130    }
131}