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}