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(|(_, °ree)| 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(|(_, °ree)| 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}