Skip to main content

yang_base/plugin/
mod.rs

1//! 插件管理模块
2//!
3//! 提供插件注册、管理和生命周期控制功能。
4//!
5//! # 主要组件
6//!
7//! - `Plugin` trait:插件接口定义
8//! - `PluginManager`:插件管理器,负责插件的注册和查找
9//!
10//! # 示例
11//!
12//! ```rust,ignore
13//! use yang_base::plugin::{Plugin, PluginManager};
14//!
15//! // 定义插件
16//! struct MyPlugin;
17//!
18//! #[async_trait::async_trait]
19//! impl Plugin for MyPlugin {
20//!     fn name(&self) -> &str {
21//!         "my_plugin"
22//!     }
23//! }
24//!
25//! // 注册插件
26//! let manager = PluginManager::new();
27//! manager.register(MyPlugin).await?;
28//! ```
29
30use async_trait::async_trait;
31use serde_json::Value as JsonValue;
32use std::collections::HashMap;
33use std::sync::Arc;
34use tokio::sync::RwLock;
35
36use crate::error::BaseError;
37
38/// 插件接口
39///
40/// 所有插件必须实现此 trait
41///
42/// # 示例
43///
44/// ```rust,ignore
45/// use yang_base::plugin::Plugin;
46/// use async_trait::async_trait;
47///
48/// struct MyPlugin;
49///
50/// #[async_trait]
51/// impl Plugin for MyPlugin {
52///     fn name(&self) -> &str {
53///         "my_plugin"
54///     }
55///     
56///     fn version(&self) -> &str {
57///         "1.0.0"
58///     }
59///     
60///     fn init_sql(&self) -> Vec<String> {
61///         vec![
62///             "CREATE TABLE IF NOT EXISTS my_table (id INT PRIMARY KEY)".to_string()
63///         ]
64///     }
65/// }
66/// ```
67#[async_trait]
68pub trait Plugin: Send + Sync {
69    /// 获取插件名称
70    ///
71    /// 插件名称必须唯一,用于标识和查找插件
72    ///
73    /// # 返回
74    /// - 插件名称字符串
75    fn name(&self) -> &str;
76
77    /// 获取插件版本
78    ///
79    /// 使用语义化版本号,格式:major.minor.patch
80    ///
81    /// # 返回
82    /// - 版本号字符串,默认为 "0.1.0"
83    fn version(&self) -> &str {
84        "0.1.0"
85    }
86
87    /// 获取插件依赖列表
88    ///
89    /// 返回当前插件依赖的其他插件名称列表
90    /// 系统会确保依赖插件先于当前插件初始化
91    ///
92    /// # 返回
93    /// - 依赖插件名称列表,默认为空
94    fn dependencies(&self) -> Vec<&str> {
95        Vec::new()
96    }
97
98    /// 获取数据库初始化 SQL 脚本
99    ///
100    /// 返回创建表的 SQL 语句列表
101    /// 建议使用 IF NOT EXISTS 确保幂等性
102    ///
103    /// # 返回
104    /// - SQL 语句列表,默认为空
105    fn init_sql(&self) -> Vec<String> {
106        Vec::new()
107    }
108
109    /// 获取数据库迁移脚本
110    ///
111    /// 返回 (版本号, SQL 脚本) 的列表
112    /// 版本号格式:YYYYMMDDHHMMSS
113    ///
114    /// # 返回
115    /// - (版本号, SQL 脚本) 元组列表,默认为空
116    fn migration_sql(&self) -> Vec<(String, String)> {
117        Vec::new()
118    }
119
120    /// 获取插件配置 Schema
121    ///
122    /// 返回 JSON Schema 格式的配置定义
123    ///
124    /// # 返回
125    /// - Some(JsonValue): 配置 Schema
126    /// - None: 无配置要求(默认)
127    fn config_schema(&self) -> Option<JsonValue> {
128        None
129    }
130
131    /// 插件注册时的回调
132    ///
133    /// 在插件被注册到 PluginManager 时调用
134    ///
135    /// # 返回
136    /// - Ok(()): 注册成功
137    /// - Err: 注册失败
138    async fn on_register(&self) -> Result<(), Box<dyn std::error::Error>> {
139        Ok(())
140    }
141
142    /// 数据库初始化后的回调
143    ///
144    /// 在插件的数据库表创建完成后调用
145    /// 可用于插入初始数据或执行其他初始化逻辑
146    ///
147    /// # 返回
148    /// - Ok(()): 初始化成功
149    /// - Err: 初始化失败
150    async fn on_init(&self) -> Result<(), Box<dyn std::error::Error>> {
151        Ok(())
152    }
153
154    /// 系统关闭时的回调
155    ///
156    /// 在系统关闭时调用,用于清理资源
157    ///
158    /// # 返回
159    /// - Ok(()): 关闭成功
160    /// - Err: 关闭失败
161    async fn on_shutdown(&self) -> Result<(), Box<dyn std::error::Error>> {
162        Ok(())
163    }
164}
165
166/// 插件管理器
167///
168/// 负责插件的注册、查找和生命周期管理
169///
170/// # 示例
171///
172/// ```rust,ignore
173/// use yang_base::plugin::{Plugin, PluginManager};
174///
175/// #[tokio::main]
176/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
177///     let manager = PluginManager::new();
178///     
179///     // 注册插件
180///     manager.register(MyPlugin).await?;
181///     
182///     // 查找插件
183///     if let Some(plugin) = manager.get("my_plugin").await {
184///         println!("找到插件: {}", plugin.name());
185///     }
186///     
187///     // 获取所有插件(按依赖顺序)
188///     let plugins = manager.get_all().await;
189///     
190///     // 关闭所有插件
191///     manager.shutdown().await?;
192///     
193///     Ok(())
194/// }
195/// ```
196pub struct PluginManager {
197    /// 已注册的插件
198    /// Key: 插件名称, Value: 插件实例
199    plugins: Arc<RwLock<HashMap<String, Arc<dyn Plugin>>>>,
200
201    /// 插件配置
202    /// Key: 插件名称, Value: 配置 JSON
203    configs: Arc<RwLock<HashMap<String, JsonValue>>>,
204}
205
206impl PluginManager {
207    /// 创建新的插件管理器
208    ///
209    /// # 返回
210    /// - 新的 PluginManager 实例
211    ///
212    /// # 示例
213    ///
214    /// ```rust
215    /// use yang_base::plugin::PluginManager;
216    ///
217    /// let manager = PluginManager::new();
218    /// ```
219    pub fn new() -> Self {
220        Self {
221            plugins: Arc::new(RwLock::new(HashMap::new())),
222            configs: Arc::new(RwLock::new(HashMap::new())),
223        }
224    }
225
226    /// 注册插件
227    ///
228    /// # 参数
229    /// - plugin: 插件实例
230    ///
231    /// # 返回
232    /// - Ok(()): 注册成功
233    /// - Err(BaseError): 注册失败(如插件名称重复)
234    ///
235    /// # 示例
236    ///
237    /// ```rust,ignore
238    /// use yang_base::plugin::{Plugin, PluginManager};
239    ///
240    /// let manager = PluginManager::new();
241    /// manager.register(MyPlugin).await?;
242    /// ```
243    pub async fn register<P: Plugin + 'static>(&self, plugin: P) -> Result<(), BaseError> {
244        let name = plugin.name().to_string();
245        let plugin = Arc::new(plugin);
246
247        // 检查插件是否已注册
248        {
249            let plugins = self.plugins.read().await;
250            if plugins.contains_key(&name) {
251                return Err(BaseError::PluginAlreadyRegistered(name));
252            }
253        }
254
255        // 调用注册回调
256        plugin
257            .on_register()
258            .await
259            .map_err(|e| BaseError::PluginRegisterFailed(name.clone(), e.to_string()))?;
260
261        // 注册插件
262        {
263            let mut plugins = self.plugins.write().await;
264            plugins.insert(name.clone(), plugin);
265        }
266
267        log::info!("插件已注册: {}", name);
268        Ok(())
269    }
270
271    /// 查找插件
272    ///
273    /// # 参数
274    /// - name: 插件名称
275    ///
276    /// # 返回
277    /// - `Some(Arc<dyn Plugin>)`: 找到插件
278    /// - None: 插件不存在
279    ///
280    /// # 示例
281    ///
282    /// ```rust,ignore
283    /// use yang_base::plugin::PluginManager;
284    ///
285    /// let manager = PluginManager::new();
286    /// if let Some(plugin) = manager.get("my_plugin").await {
287    ///     println!("找到插件: {}", plugin.name());
288    /// }
289    /// ```
290    pub async fn get(&self, name: &str) -> Option<Arc<dyn Plugin>> {
291        let plugins = self.plugins.read().await;
292        plugins.get(name).cloned()
293    }
294
295    /// 获取所有已注册插件
296    ///
297    /// # 返回
298    /// - 插件列表(按依赖关系排序)
299    ///
300    /// # 示例
301    ///
302    /// ```rust,ignore
303    /// use yang_base::plugin::PluginManager;
304    ///
305    /// let manager = PluginManager::new();
306    /// let plugins = manager.get_all().await;
307    /// for plugin in plugins {
308    ///     println!("插件: {} v{}", plugin.name(), plugin.version());
309    /// }
310    /// ```
311    pub async fn get_all(&self) -> Vec<Arc<dyn Plugin>> {
312        let plugins = self.plugins.read().await;
313        let mut plugin_list: Vec<_> = plugins.values().cloned().collect();
314
315        // 按依赖关系排序
316        self.topological_sort(&mut plugin_list);
317
318        plugin_list
319    }
320
321    /// 加载插件配置
322    ///
323    /// # 参数
324    /// - name: 插件名称
325    /// - config: 配置 JSON
326    ///
327    /// # 返回
328    /// - Ok(()): 加载成功
329    /// - Err(BaseError): 加载失败(如配置验证失败)
330    ///
331    /// # 示例
332    ///
333    /// ```rust,ignore
334    /// use yang_base::plugin::PluginManager;
335    /// use serde_json::json;
336    ///
337    /// let manager = PluginManager::new();
338    /// let config = json!({"key": "value"});
339    /// manager.load_config("my_plugin", config).await?;
340    /// ```
341    pub async fn load_config(&self, name: &str, config: JsonValue) -> Result<(), BaseError> {
342        // 获取插件
343        let plugin = self
344            .get(name)
345            .await
346            .ok_or_else(|| BaseError::PluginNotFound(name.to_string()))?;
347
348        // 验证配置
349        if let Some(schema) = plugin.config_schema() {
350            self.validate_config(&config, &schema)?;
351        }
352
353        // 存储配置
354        {
355            let mut configs = self.configs.write().await;
356            configs.insert(name.to_string(), config);
357        }
358
359        Ok(())
360    }
361
362    /// 获取插件配置
363    ///
364    /// # 参数
365    /// - name: 插件名称
366    ///
367    /// # 返回
368    /// - Some(JsonValue): 插件配置
369    /// - None: 配置不存在
370    ///
371    /// # 示例
372    ///
373    /// ```rust,ignore
374    /// use yang_base::plugin::PluginManager;
375    ///
376    /// let manager = PluginManager::new();
377    /// if let Some(config) = manager.get_config("my_plugin").await {
378    ///     println!("配置: {:?}", config);
379    /// }
380    /// ```
381    pub async fn get_config(&self, name: &str) -> Option<JsonValue> {
382        let configs = self.configs.read().await;
383        configs.get(name).cloned()
384    }
385
386    /// 拓扑排序(按依赖关系排序)
387    ///
388    /// # 参数
389    /// - plugins: 插件列表
390    ///
391    /// # 说明
392    /// 使用 Kahn 算法进行拓扑排序,确保依赖插件先于当前插件
393    fn topological_sort(&self, plugins: &mut Vec<Arc<dyn Plugin>>) {
394        // 构建依赖图
395        let mut in_degree: HashMap<String, usize> = HashMap::new();
396        let mut graph: HashMap<String, Vec<String>> = HashMap::new();
397
398        for plugin in plugins.iter() {
399            let name = plugin.name().to_string();
400            in_degree.entry(name.clone()).or_insert(0);
401
402            for dep in plugin.dependencies() {
403                graph.entry(dep.to_string()).or_default().push(name.clone());
404                *in_degree.entry(name.clone()).or_insert(0) += 1;
405            }
406        }
407
408        // Kahn 算法
409        let mut queue: Vec<String> = in_degree
410            .iter()
411            .filter(|(_, &degree)| degree == 0)
412            .map(|(name, _)| name.clone())
413            .collect();
414
415        let mut sorted = Vec::new();
416
417        while let Some(node) = queue.pop() {
418            sorted.push(node.clone());
419
420            if let Some(neighbors) = graph.get(&node) {
421                for neighbor in neighbors {
422                    if let Some(degree) = in_degree.get_mut(neighbor) {
423                        *degree -= 1;
424                        if *degree == 0 {
425                            queue.push(neighbor.clone());
426                        }
427                    }
428                }
429            }
430        }
431
432        // 重新排序插件列表
433        plugins.sort_by_key(|p| {
434            sorted
435                .iter()
436                .position(|n| n == p.name())
437                .unwrap_or(usize::MAX)
438        });
439    }
440
441    /// 验证配置
442    ///
443    /// # 参数
444    /// - config: 配置 JSON
445    /// - schema: JSON Schema
446    ///
447    /// # 返回
448    /// - Ok(()): 验证通过
449    /// - Err(BaseError): 验证失败
450    fn validate_config(&self, _config: &JsonValue, _schema: &JsonValue) -> Result<(), BaseError> {
451        // TODO: 实现 JSON Schema 验证
452        // 可以使用 jsonschema crate
453        Ok(())
454    }
455
456    /// 关闭所有插件
457    ///
458    /// 按照依赖关系的逆序调用插件的 on_shutdown 方法
459    ///
460    /// # 返回
461    /// - Ok(()): 关闭成功
462    /// - Err(BaseError): 关闭失败
463    ///
464    /// # 示例
465    ///
466    /// ```rust,ignore
467    /// use yang_base::plugin::PluginManager;
468    ///
469    /// let manager = PluginManager::new();
470    /// // ... 注册插件 ...
471    /// manager.shutdown().await?;
472    /// ```
473    pub async fn shutdown(&self) -> Result<(), BaseError> {
474        let mut plugins = self.get_all().await;
475        plugins.reverse(); // 逆序关闭
476
477        for plugin in plugins {
478            let name = plugin.name();
479            if let Err(e) = plugin.on_shutdown().await {
480                log::error!("插件 {} 关闭失败: {}", name, e);
481                return Err(BaseError::PluginShutdownFailed(
482                    name.to_string(),
483                    e.to_string(),
484                ));
485            }
486            log::info!("插件已关闭: {}", name);
487        }
488
489        Ok(())
490    }
491}
492
493impl Default for PluginManager {
494    fn default() -> Self {
495        Self::new()
496    }
497}