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        // 验证配置(插件未定义 config_schema 时跳过验证)
349        if let Some(schema) = plugin.config_schema() {
350            self.validate_config(name, &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    /// 使用 jsonschema crate 对配置进行 JSON Schema 验证。
444    /// 未启用 `plugin-schema` feature 时跳过验证。
445    ///
446    /// # 参数
447    /// - `plugin_name`: 插件名称(用于错误信息)
448    /// - `config`: 配置 JSON
449    /// - `schema`: JSON Schema
450    ///
451    /// # 返回
452    /// - `Ok(())`: 验证通过
453    /// - `Err(BaseError::PluginConfigInvalid)`: 配置不符合 Schema
454    fn validate_config(
455        &self,
456        plugin_name: &str,
457        config: &JsonValue,
458        schema: &JsonValue,
459    ) -> Result<(), BaseError> {
460        // 使用 jsonschema crate 进行 JSON Schema 验证
461        #[cfg(feature = "plugin-schema")]
462        {
463            // 构建可复用的验证器
464            let validator = jsonschema::validator_for(schema).map_err(|e| {
465                BaseError::PluginConfigInvalid(
466                    plugin_name.to_string(),
467                    format!("Schema 编译失败: {}", e),
468                )
469            })?;
470
471            // 收集所有验证错误信息
472            let error_msgs: Vec<String> = validator
473                .iter_errors(config)
474                .map(|e| e.to_string())
475                .collect();
476
477            if !error_msgs.is_empty() {
478                return Err(BaseError::PluginConfigInvalid(
479                    plugin_name.to_string(),
480                    error_msgs.join("; "),
481                ));
482            }
483        }
484
485        // 未启用 plugin-schema feature 时,跳过验证直接返回成功
486        #[cfg(not(feature = "plugin-schema"))]
487        {
488            let _ = (plugin_name, config, schema);
489        }
490
491        Ok(())
492    }
493
494    /// 关闭所有插件
495    ///
496    /// 按照依赖关系的逆序调用插件的 on_shutdown 方法
497    ///
498    /// # 返回
499    /// - Ok(()): 关闭成功
500    /// - Err(BaseError): 关闭失败
501    ///
502    /// # 示例
503    ///
504    /// ```rust,ignore
505    /// use yang_base::plugin::PluginManager;
506    ///
507    /// let manager = PluginManager::new();
508    /// // ... 注册插件 ...
509    /// manager.shutdown().await?;
510    /// ```
511    pub async fn shutdown(&self) -> Result<(), BaseError> {
512        let mut plugins = self.get_all().await;
513        plugins.reverse(); // 逆序关闭
514
515        for plugin in plugins {
516            let name = plugin.name();
517            if let Err(e) = plugin.on_shutdown().await {
518                log::error!("插件 {} 关闭失败: {}", name, e);
519                return Err(BaseError::PluginShutdownFailed(
520                    name.to_string(),
521                    e.to_string(),
522                ));
523            }
524            log::info!("插件已关闭: {}", name);
525        }
526
527        Ok(())
528    }
529}
530
531impl Default for PluginManager {
532    fn default() -> Self {
533        Self::new()
534    }
535}
536
537/// 插件管理器构建器(构建阶段使用)
538///
539/// 在构建阶段负责插件的注册,构建完成后生成不可变的 `PluginRegistry`。
540/// 构建阶段可以进行可变操作,运行阶段通过 `PluginRegistry` 进行无锁查找。
541///
542/// # 示例
543///
544/// ```rust,ignore
545/// use yang_base::plugin::{Plugin, PluginManagerBuilder};
546///
547/// #[tokio::main]
548/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
549///     let mut builder = PluginManagerBuilder::new();
550///
551///     // 注册插件
552///     builder.register(MyPlugin).await?;
553///
554///     // 构建不可变的 PluginRegistry
555///     let registry = builder.build();
556///
557///     // 无锁查找插件
558///     if let Some(plugin) = registry.get("my_plugin") {
559///         println!("找到插件: {}", plugin.name());
560///     }
561///
562///     Ok(())
563/// }
564/// ```
565pub struct PluginManagerBuilder {
566    /// 已注册的插件(构建阶段可变)
567    /// Key: 插件名称, Value: 插件实例
568    plugins: HashMap<String, Arc<dyn Plugin>>,
569
570    /// 插件配置
571    /// Key: 插件名称, Value: 配置 JSON
572    configs: HashMap<String, JsonValue>,
573}
574
575impl PluginManagerBuilder {
576    /// 创建新的插件管理器构建器
577    ///
578    /// # 返回
579    /// - 新的 PluginManagerBuilder 实例
580    ///
581    /// # 示例
582    ///
583    /// ```rust
584    /// use yang_base::plugin::PluginManagerBuilder;
585    ///
586    /// let builder = PluginManagerBuilder::new();
587    /// ```
588    pub fn new() -> Self {
589        Self {
590            plugins: HashMap::new(),
591            configs: HashMap::new(),
592        }
593    }
594
595    /// 注册插件(构建阶段使用)
596    ///
597    /// 检查插件名称是否重复,调用 `on_register()` 回调,然后插入 HashMap。
598    ///
599    /// # 参数
600    /// - `plugin`: 插件实例
601    ///
602    /// # 返回
603    /// - `Ok(())`: 注册成功
604    /// - `Err(BaseError)`: 注册失败(如插件名称重复或注册回调失败)
605    ///
606    /// # 示例
607    ///
608    /// ```rust,ignore
609    /// use yang_base::plugin::{Plugin, PluginManagerBuilder};
610    ///
611    /// let mut builder = PluginManagerBuilder::new();
612    /// builder.register(MyPlugin).await?;
613    /// ```
614    pub async fn register<P: Plugin + 'static>(&mut self, plugin: P) -> Result<(), BaseError> {
615        let name = plugin.name().to_string();
616
617        // 检查插件是否已注册(构建阶段直接访问 HashMap,无需加锁)
618        if self.plugins.contains_key(&name) {
619            return Err(BaseError::PluginAlreadyRegistered(name));
620        }
621
622        let plugin = Arc::new(plugin);
623
624        // 调用注册回调
625        plugin
626            .on_register()
627            .await
628            .map_err(|e| BaseError::PluginRegisterFailed(name.clone(), e.to_string()))?;
629
630        // 插入 HashMap
631        self.plugins.insert(name.clone(), plugin);
632
633        log::info!("插件已注册(构建阶段): {}", name);
634        Ok(())
635    }
636
637    /// 消费构建器,生成不可变的 PluginRegistry
638    ///
639    /// 调用此方法后,构建器被消费,返回运行阶段使用的 `PluginRegistry`。
640    /// `PluginRegistry` 在构建时执行一次拓扑排序并缓存结果。
641    ///
642    /// # 返回
643    /// - `Ok(PluginRegistry)`: 构建成功
644    /// - `Err(BaseError::PluginDependencyMissing)`: 某插件的依赖未注册
645    /// - `Err(BaseError::PluginCircularDependency)`: 插件之间存在循环依赖
646    ///
647    /// # 示例
648    ///
649    /// ```rust,ignore
650    /// use yang_base::plugin::PluginManagerBuilder;
651    ///
652    /// let mut builder = PluginManagerBuilder::new();
653    /// // ... 注册插件 ...
654    /// let registry = builder.build()?;
655    /// ```
656    pub fn build(self) -> Result<PluginRegistry, BaseError> {
657        // 检查每个插件的依赖是否都已注册
658        for plugin in self.plugins.values() {
659            let plugin_name = plugin.name().to_string();
660            for dep in plugin.dependencies() {
661                if !self.plugins.contains_key(dep) {
662                    // 依赖未注册,返回错误
663                    return Err(BaseError::PluginDependencyMissing(
664                        plugin_name,
665                        dep.to_string(),
666                    ));
667                }
668            }
669        }
670        // 依赖完整性检查通过,构建注册表(内部会检测循环依赖)
671        PluginRegistry::new(self.plugins, self.configs)
672    }
673}
674
675impl Default for PluginManagerBuilder {
676    fn default() -> Self {
677        Self::new()
678    }
679}
680
681/// 插件注册表(运行阶段使用,无锁)
682///
683/// 由 `PluginManagerBuilder::build()` 生成,存储不可变的插件集合。
684/// 运行阶段通过 HashMap 直接查找,无需获取任何锁,实现 O(1) 无锁查找。
685/// 拓扑排序结果在构建时计算一次并缓存,多次调用 `get_all()` 无需重新计算。
686///
687/// # 示例
688///
689/// ```rust,ignore
690/// use yang_base::plugin::{Plugin, PluginManagerBuilder};
691///
692/// #[tokio::main]
693/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
694///     let mut builder = PluginManagerBuilder::new();
695///     builder.register(MyPlugin).await?;
696///     let registry = builder.build();
697///
698///     // 无锁 O(1) 查找
699///     if let Some(plugin) = registry.get("my_plugin") {
700///         println!("找到插件: {}", plugin.name());
701///     }
702///
703///     // 获取缓存的排序结果(无需重新计算)
704///     let all_plugins = registry.get_all();
705///
706///     // 关闭所有插件
707///     registry.shutdown().await?;
708///
709///     Ok(())
710/// }
711/// ```
712pub struct PluginRegistry {
713    /// 不可变插件映射(无 RwLock 包装,运行阶段无锁访问)
714    /// Key: 插件名称, Value: 插件实例
715    plugins: HashMap<String, Arc<dyn Plugin>>,
716
717    /// 拓扑排序缓存(构建时计算一次,运行阶段直接返回引用)
718    sorted_plugins: Vec<Arc<dyn Plugin>>,
719
720    /// 插件配置
721    /// Key: 插件名称, Value: 配置 JSON
722    configs: HashMap<String, JsonValue>,
723}
724
725impl PluginRegistry {
726    /// 创建新的插件注册表(私有构造方法)
727    ///
728    /// 接收 plugins 和 configs,调用 `compute_topological_sort` 并缓存排序结果。
729    /// 此方法仅由 `PluginManagerBuilder::build()` 调用。
730    ///
731    /// # 参数
732    /// - `plugins`: 插件 HashMap
733    /// - `configs`: 配置 HashMap
734    ///
735    /// # 返回
736    /// - `Ok(PluginRegistry)`: 构建成功
737    /// - `Err(BaseError::PluginCircularDependency)`: 存在循环依赖
738    fn new(
739        plugins: HashMap<String, Arc<dyn Plugin>>,
740        configs: HashMap<String, JsonValue>,
741    ) -> Result<Self, BaseError> {
742        // 构建时执行一次拓扑排序并缓存结果(内部检测循环依赖)
743        let sorted_plugins = Self::compute_topological_sort(&plugins)?;
744        Ok(Self {
745            plugins,
746            sorted_plugins,
747            configs,
748        })
749    }
750
751    /// 查找插件(无锁,O(1) HashMap 查找)
752    ///
753    /// 直接通过 HashMap 查找,无需获取任何锁。
754    ///
755    /// # 参数
756    /// - `name`: 插件名称
757    ///
758    /// # 返回
759    /// - `Some(&Arc<dyn Plugin>)`: 找到插件
760    /// - `None`: 插件不存在
761    ///
762    /// # 示例
763    ///
764    /// ```rust,ignore
765    /// use yang_base::plugin::PluginManagerBuilder;
766    ///
767    /// let registry = PluginManagerBuilder::new().build();
768    /// if let Some(plugin) = registry.get("my_plugin") {
769    ///     println!("找到插件: {}", plugin.name());
770    /// }
771    /// ```
772    pub fn get(&self, name: &str) -> Option<&Arc<dyn Plugin>> {
773        self.plugins.get(name)
774    }
775
776    /// 获取所有已注册插件(返回缓存的排序结果引用)
777    ///
778    /// 直接返回构建时缓存的拓扑排序结果,无需重新计算。
779    ///
780    /// # 返回
781    /// - 按依赖关系排序的插件切片引用
782    ///
783    /// # 示例
784    ///
785    /// ```rust,ignore
786    /// use yang_base::plugin::PluginManagerBuilder;
787    ///
788    /// let registry = PluginManagerBuilder::new().build();
789    /// let plugins = registry.get_all();
790    /// for plugin in plugins {
791    ///     println!("插件: {} v{}", plugin.name(), plugin.version());
792    /// }
793    /// ```
794    pub fn get_all(&self) -> &[Arc<dyn Plugin>] {
795        &self.sorted_plugins
796    }
797
798    /// 获取插件配置
799    ///
800    /// # 参数
801    /// - `name`: 插件名称
802    ///
803    /// # 返回
804    /// - `Some(&JsonValue)`: 插件配置
805    /// - `None`: 配置不存在
806    pub fn get_config(&self, name: &str) -> Option<&JsonValue> {
807        self.configs.get(name)
808    }
809
810    /// 关闭所有插件(逆序关闭)
811    ///
812    /// 按照拓扑排序的逆序调用每个插件的 `on_shutdown` 方法,
813    /// 确保依赖其他插件的插件先被关闭。
814    ///
815    /// # 返回
816    /// - `Ok(())`: 所有插件关闭成功
817    /// - `Err(BaseError)`: 某个插件关闭失败
818    ///
819    /// # 示例
820    ///
821    /// ```rust,ignore
822    /// use yang_base::plugin::PluginManagerBuilder;
823    ///
824    /// let registry = PluginManagerBuilder::new().build();
825    /// // ... 使用插件 ...
826    /// registry.shutdown().await?;
827    /// ```
828    pub async fn shutdown(&self) -> Result<(), BaseError> {
829        // 逆序遍历缓存的排序结果,确保依赖插件最后关闭
830        for plugin in self.sorted_plugins.iter().rev() {
831            let name = plugin.name();
832            if let Err(e) = plugin.on_shutdown().await {
833                log::error!("插件 {} 关闭失败: {}", name, e);
834                return Err(BaseError::PluginShutdownFailed(
835                    name.to_string(),
836                    e.to_string(),
837                ));
838            }
839            log::info!("插件已关闭: {}", name);
840        }
841        Ok(())
842    }
843
844    /// 计算拓扑排序(私有方法,构建时调用一次)
845    ///
846    /// 使用 Kahn 算法对插件进行拓扑排序,确保依赖插件先于当前插件出现。
847    /// 当排序后的节点数小于插件总数时,说明存在循环依赖。
848    ///
849    /// # 参数
850    /// - `plugins`: 插件 HashMap 引用
851    ///
852    /// # 返回
853    /// - `Ok(Vec<Arc<dyn Plugin>>)`: 按依赖关系排序的插件列表
854    /// - `Err(BaseError::PluginCircularDependency)`: 存在循环依赖,错误信息含未排序节点
855    fn compute_topological_sort(
856        plugins: &HashMap<String, Arc<dyn Plugin>>,
857    ) -> Result<Vec<Arc<dyn Plugin>>, BaseError> {
858        // 构建入度表和邻接图
859        let mut in_degree: HashMap<String, usize> = HashMap::new();
860        let mut graph: HashMap<String, Vec<String>> = HashMap::new();
861
862        for plugin in plugins.values() {
863            let name = plugin.name().to_string();
864            in_degree.entry(name.clone()).or_insert(0);
865
866            for dep in plugin.dependencies() {
867                // dep -> name 的边:dep 是 name 的依赖,dep 先执行
868                graph
869                    .entry(dep.to_string())
870                    .or_default()
871                    .push(name.clone());
872                *in_degree.entry(name.clone()).or_insert(0) += 1;
873            }
874        }
875
876        // Kahn 算法:从入度为 0 的节点开始
877        let mut queue: Vec<String> = in_degree
878            .iter()
879            .filter(|(_, &degree)| degree == 0)
880            .map(|(name, _)| name.clone())
881            .collect();
882
883        let mut sorted_names: Vec<String> = Vec::new();
884
885        while let Some(node) = queue.pop() {
886            sorted_names.push(node.clone());
887
888            if let Some(neighbors) = graph.get(&node) {
889                for neighbor in neighbors {
890                    if let Some(degree) = in_degree.get_mut(neighbor) {
891                        *degree -= 1;
892                        if *degree == 0 {
893                            queue.push(neighbor.clone());
894                        }
895                    }
896                }
897            }
898        }
899
900        // 检测循环依赖:若排序后的节点数小于插件总数,说明存在循环
901        if sorted_names.len() < plugins.len() {
902            // 找出未被排序的节点(即循环中的插件)
903            let unsorted: Vec<String> = plugins
904                .keys()
905                .filter(|name| !sorted_names.contains(name))
906                .cloned()
907                .collect();
908            let unsorted_str = unsorted.join(", ");
909            return Err(BaseError::PluginCircularDependency(format!(
910                "循环依赖涉及的插件: {}",
911                unsorted_str
912            )));
913        }
914
915        // 按排序顺序构建插件列表
916        let mut sorted_plugins: Vec<Arc<dyn Plugin>> = plugins.values().cloned().collect();
917        sorted_plugins.sort_by_key(|p| {
918            sorted_names
919                .iter()
920                .position(|n| n == p.name())
921                .unwrap_or(usize::MAX)
922        });
923
924        Ok(sorted_plugins)
925    }
926}
927
928#[cfg(test)]
929mod tests {
930    use super::*;
931
932    /// 测试用插件:无依赖
933    struct PluginA;
934
935    #[async_trait]
936    impl Plugin for PluginA {
937        fn name(&self) -> &str {
938            "plugin_a"
939        }
940    }
941
942    /// 测试用插件:依赖 plugin_a
943    struct PluginB;
944
945    #[async_trait]
946    impl Plugin for PluginB {
947        fn name(&self) -> &str {
948            "plugin_b"
949        }
950
951        fn dependencies(&self) -> Vec<&str> {
952            vec!["plugin_a"]
953        }
954    }
955
956    /// 测试用插件:依赖 plugin_b
957    struct PluginC;
958
959    #[async_trait]
960    impl Plugin for PluginC {
961        fn name(&self) -> &str {
962            "plugin_c"
963        }
964
965        fn dependencies(&self) -> Vec<&str> {
966            vec!["plugin_b"]
967        }
968    }
969
970    /// 测试用插件:注册时返回错误
971    struct PluginFailing;
972
973    #[async_trait]
974    impl Plugin for PluginFailing {
975        fn name(&self) -> &str {
976            "plugin_failing"
977        }
978
979        async fn on_register(&self) -> Result<(), Box<dyn std::error::Error>> {
980            Err("注册失败".into())
981        }
982    }
983
984    /// 验证需求: P4 - PluginRegistry::get(name) 的结果与构建前注册的插件一一对应
985    #[tokio::test]
986    async fn test_registry_get_matches_registered_plugins() {
987        let mut builder = PluginManagerBuilder::new();
988        builder.register(PluginA).await.unwrap();
989        builder.register(PluginB).await.unwrap();
990        builder.register(PluginC).await.unwrap();
991
992        let registry = builder.build().expect("构建注册表应成功");
993
994        // 验证每个注册的插件都能通过 get 找到,且名称一致
995        let plugin_a = registry.get("plugin_a");
996        assert!(plugin_a.is_some(), "应能找到 plugin_a");
997        assert_eq!(plugin_a.unwrap().name(), "plugin_a");
998
999        let plugin_b = registry.get("plugin_b");
1000        assert!(plugin_b.is_some(), "应能找到 plugin_b");
1001        assert_eq!(plugin_b.unwrap().name(), "plugin_b");
1002
1003        let plugin_c = registry.get("plugin_c");
1004        assert!(plugin_c.is_some(), "应能找到 plugin_c");
1005        assert_eq!(plugin_c.unwrap().name(), "plugin_c");
1006
1007        // 验证不存在的插件返回 None
1008        assert!(registry.get("nonexistent").is_none(), "不存在的插件应返回 None");
1009    }
1010
1011    /// 验证需求: P4 - get_all() 返回缓存结果,多次调用结果一致
1012    #[tokio::test]
1013    async fn test_registry_get_all_returns_cached_result() {
1014        let mut builder = PluginManagerBuilder::new();
1015        builder.register(PluginA).await.unwrap();
1016        builder.register(PluginB).await.unwrap();
1017        builder.register(PluginC).await.unwrap();
1018
1019        let registry = builder.build().expect("构建注册表应成功");
1020
1021        // 多次调用 get_all() 应返回相同的结果(缓存)
1022        let all_first = registry.get_all();
1023        let all_second = registry.get_all();
1024
1025        // 验证两次调用返回相同数量的插件
1026        assert_eq!(all_first.len(), all_second.len(), "多次调用 get_all() 应返回相同数量的插件");
1027        assert_eq!(all_first.len(), 3, "应有 3 个插件");
1028
1029        // 验证两次调用返回相同的插件名称(顺序一致)
1030        let names_first: Vec<&str> = all_first.iter().map(|p| p.name()).collect();
1031        let names_second: Vec<&str> = all_second.iter().map(|p| p.name()).collect();
1032        assert_eq!(names_first, names_second, "多次调用 get_all() 应返回相同顺序的插件");
1033    }
1034
1035    /// 验证需求: P4 - get_all() 返回的插件按拓扑顺序排列(依赖先于被依赖者)
1036    #[tokio::test]
1037    async fn test_registry_get_all_topological_order() {
1038        let mut builder = PluginManagerBuilder::new();
1039        // 故意以非依赖顺序注册
1040        builder.register(PluginC).await.unwrap();
1041        builder.register(PluginA).await.unwrap();
1042        builder.register(PluginB).await.unwrap();
1043
1044        let registry = builder.build().expect("构建注册表应成功");
1045        let all_plugins = registry.get_all();
1046
1047        // 找到各插件在排序结果中的位置
1048        let pos_a = all_plugins.iter().position(|p| p.name() == "plugin_a");
1049        let pos_b = all_plugins.iter().position(|p| p.name() == "plugin_b");
1050        let pos_c = all_plugins.iter().position(|p| p.name() == "plugin_c");
1051
1052        assert!(pos_a.is_some() && pos_b.is_some() && pos_c.is_some(), "所有插件应在排序结果中");
1053
1054        // 验证拓扑顺序:plugin_a 在 plugin_b 之前,plugin_b 在 plugin_c 之前
1055        assert!(
1056            pos_a.unwrap() < pos_b.unwrap(),
1057            "plugin_a(被依赖)应在 plugin_b 之前"
1058        );
1059        assert!(
1060            pos_b.unwrap() < pos_c.unwrap(),
1061            "plugin_b(被依赖)应在 plugin_c 之前"
1062        );
1063    }
1064
1065    /// 验证需求: 9.3 - 注册重名插件应返回错误
1066    #[tokio::test]
1067    async fn test_builder_register_duplicate_returns_error() {
1068        let mut builder = PluginManagerBuilder::new();
1069        builder.register(PluginA).await.unwrap();
1070
1071        // 再次注册同名插件应返回错误
1072        struct PluginADuplicate;
1073        #[async_trait]
1074        impl Plugin for PluginADuplicate {
1075            fn name(&self) -> &str {
1076                "plugin_a"
1077            }
1078        }
1079
1080        let result = builder.register(PluginADuplicate).await;
1081        assert!(
1082            matches!(result, Err(BaseError::PluginAlreadyRegistered(_))),
1083            "注册重名插件应返回 PluginAlreadyRegistered 错误"
1084        );
1085    }
1086
1087    /// 验证需求: 9.3 - 注册回调失败时应返回错误
1088    #[tokio::test]
1089    async fn test_builder_register_callback_failure_returns_error() {
1090        let mut builder = PluginManagerBuilder::new();
1091        let result = builder.register(PluginFailing).await;
1092        assert!(
1093            matches!(result, Err(BaseError::PluginRegisterFailed(_, _))),
1094            "注册回调失败应返回 PluginRegisterFailed 错误"
1095        );
1096    }
1097
1098    /// 验证需求: 9.4 - build() 消费构建器并返回 PluginRegistry
1099    #[tokio::test]
1100    async fn test_builder_build_produces_registry() {
1101        let mut builder = PluginManagerBuilder::new();
1102        builder.register(PluginA).await.unwrap();
1103
1104        let registry = builder.build().expect("构建注册表应成功");
1105
1106        // 验证 registry 包含注册的插件
1107        assert!(registry.get("plugin_a").is_some(), "registry 应包含已注册的插件");
1108        assert_eq!(registry.get_all().len(), 1, "registry 应有 1 个插件");
1109    }
1110
1111    /// 验证需求: 9.7 - get() 返回正确的插件引用
1112    #[tokio::test]
1113    async fn test_registry_get_returns_correct_plugin() {
1114        let mut builder = PluginManagerBuilder::new();
1115        builder.register(PluginA).await.unwrap();
1116        builder.register(PluginB).await.unwrap();
1117
1118        let registry = builder.build().expect("构建注册表应成功");
1119
1120        // 验证 get() 返回正确的插件
1121        let plugin = registry.get("plugin_a").unwrap();
1122        assert_eq!(plugin.name(), "plugin_a", "get() 应返回正确名称的插件");
1123        assert_eq!(plugin.version(), "0.1.0", "get() 应返回正确版本的插件");
1124    }
1125
1126    /// 验证需求: 9.9 - shutdown() 逆序关闭所有插件
1127    #[tokio::test]
1128    async fn test_registry_shutdown_succeeds() {
1129        let mut builder = PluginManagerBuilder::new();
1130        builder.register(PluginA).await.unwrap();
1131        builder.register(PluginB).await.unwrap();
1132
1133        let registry = builder.build().expect("构建注册表应成功");
1134
1135        // 验证 shutdown() 成功执行
1136        let result = registry.shutdown().await;
1137        assert!(result.is_ok(), "shutdown() 应成功执行");
1138    }
1139
1140    /// 验证需求: 9.1/9.2 - PluginManagerBuilder::new() 创建空构建器
1141    #[tokio::test]
1142    async fn test_builder_new_creates_empty_builder() {
1143        let builder = PluginManagerBuilder::new();
1144        let registry = builder.build().expect("空构建器构建应成功");
1145
1146        // 空构建器构建的 registry 应为空
1147        assert_eq!(registry.get_all().len(), 0, "空构建器应生成空 registry");
1148        assert!(registry.get("any").is_none(), "空 registry 不应包含任何插件");
1149    }
1150
1151    /// 验证需求: 20.1, 20.2, 20.3 - build() 检查依赖完整性
1152    #[tokio::test]
1153    async fn test_build_detects_missing_dependency() {
1154        let mut builder = PluginManagerBuilder::new();
1155        // 只注册 plugin_b,但 plugin_b 依赖 plugin_a(未注册)
1156        builder.register(PluginB).await.expect("注册 plugin_b 应成功");
1157
1158        let result = builder.build();
1159        assert!(
1160            matches!(result, Err(BaseError::PluginDependencyMissing(_, _))),
1161            "依赖未注册时应返回 PluginDependencyMissing 错误"
1162        );
1163
1164        // 验证错误信息包含插件名和依赖名
1165        if let Err(BaseError::PluginDependencyMissing(plugin, dep)) = result {
1166            assert_eq!(plugin, "plugin_b", "错误应指向 plugin_b");
1167            assert_eq!(dep, "plugin_a", "缺失的依赖应是 plugin_a");
1168        }
1169    }
1170
1171    /// 验证需求: 19.1, 19.2, 19.3, 19.4 - build() 检测循环依赖
1172    #[tokio::test]
1173    async fn test_build_detects_circular_dependency() {
1174        // 定义循环依赖的插件:X 依赖 Y,Y 依赖 X
1175        struct PluginX;
1176        #[async_trait]
1177        impl Plugin for PluginX {
1178            fn name(&self) -> &str {
1179                "plugin_x"
1180            }
1181            fn dependencies(&self) -> Vec<&str> {
1182                vec!["plugin_y"]
1183            }
1184        }
1185
1186        struct PluginY;
1187        #[async_trait]
1188        impl Plugin for PluginY {
1189            fn name(&self) -> &str {
1190                "plugin_y"
1191            }
1192            fn dependencies(&self) -> Vec<&str> {
1193                vec!["plugin_x"]
1194            }
1195        }
1196
1197        let mut builder = PluginManagerBuilder::new();
1198        builder.register(PluginX).await.expect("注册 plugin_x 应成功");
1199        builder.register(PluginY).await.expect("注册 plugin_y 应成功");
1200
1201        let result = builder.build();
1202        assert!(
1203            matches!(result, Err(BaseError::PluginCircularDependency(_))),
1204            "循环依赖时应返回 PluginCircularDependency 错误"
1205        );
1206
1207        // 验证错误信息包含未排序节点
1208        if let Err(BaseError::PluginCircularDependency(msg)) = result {
1209            assert!(
1210                msg.contains("plugin_x") || msg.contains("plugin_y"),
1211                "错误信息应包含循环中的插件名称"
1212            );
1213        }
1214    }
1215
1216    /// 验证需求: 7.1, 7.2, 7.3, 7.4 - validate_config 集成 jsonschema
1217    #[cfg(feature = "plugin-schema")]
1218    #[tokio::test]
1219    async fn test_validate_config_with_schema() {
1220        use serde_json::json;
1221
1222        // 定义带 Schema 的插件
1223        struct SchemaPlugin;
1224        #[async_trait]
1225        impl Plugin for SchemaPlugin {
1226            fn name(&self) -> &str {
1227                "schema_plugin"
1228            }
1229            fn config_schema(&self) -> Option<JsonValue> {
1230                Some(json!({
1231                    "type": "object",
1232                    "properties": {
1233                        "host": {"type": "string"},
1234                        "port": {"type": "integer"}
1235                    },
1236                    "required": ["host", "port"]
1237                }))
1238            }
1239        }
1240
1241        let manager = PluginManager::new();
1242        manager.register(SchemaPlugin).await.expect("注册应成功");
1243
1244        // 合法配置应通过验证
1245        let valid_config = json!({"host": "localhost", "port": 3306});
1246        let result = manager.load_config("schema_plugin", valid_config).await;
1247        assert!(result.is_ok(), "合法配置应通过验证");
1248    }
1249
1250    /// 验证需求: 7.1, 7.2 - 配置不符合 Schema 时返回错误
1251    #[cfg(feature = "plugin-schema")]
1252    #[tokio::test]
1253    async fn test_validate_config_invalid_returns_error() {
1254        use serde_json::json;
1255
1256        // 定义带 Schema 的插件
1257        struct StrictPlugin;
1258        #[async_trait]
1259        impl Plugin for StrictPlugin {
1260            fn name(&self) -> &str {
1261                "strict_plugin"
1262            }
1263            fn config_schema(&self) -> Option<JsonValue> {
1264                Some(json!({
1265                    "type": "object",
1266                    "properties": {
1267                        "port": {"type": "integer"}
1268                    },
1269                    "required": ["port"]
1270                }))
1271            }
1272        }
1273
1274        let manager = PluginManager::new();
1275        manager.register(StrictPlugin).await.expect("注册应成功");
1276
1277        // 配置缺少必填字段应返回错误
1278        let invalid_config = json!({"host": "localhost"});
1279        let result = manager.load_config("strict_plugin", invalid_config).await;
1280        assert!(
1281            matches!(result, Err(BaseError::PluginConfigInvalid(_, _))),
1282            "配置不符合 Schema 应返回 PluginConfigInvalid 错误"
1283        );
1284    }
1285}