yang_base/plugin/builder.rs
1//! 插件管理器构建器:构建阶段注册插件并生成不可变 `PluginRegistry`。
2
3use serde_json::Value as JsonValue;
4use std::collections::HashMap;
5use std::sync::Arc;
6
7use super::normalize_plugin_name;
8use super::registry::PluginRegistry;
9use super::traits::{Plugin, PluginLifecycleStage};
10use crate::error::BaseError;
11
12/// 插件管理器构建器(构建阶段使用)
13///
14/// 在构建阶段负责插件的注册,构建完成后生成不可变的 `PluginRegistry`。
15/// 构建阶段可以进行可变操作,运行阶段通过 `PluginRegistry` 进行无锁查找。
16///
17/// # 示例
18///
19/// ```rust,ignore
20/// use yang_base::plugin::{Plugin, PluginManagerBuilder};
21///
22/// #[tokio::main]
23/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
24/// let mut builder = PluginManagerBuilder::new();
25///
26/// // 注册插件
27/// builder.register(MyPlugin).await?;
28///
29/// // 构建不可变的 PluginRegistry
30/// let registry = builder.build();
31///
32/// // 无锁查找插件
33/// if let Some(plugin) = registry.get("my_plugin") {
34/// println!("找到插件: {}", plugin.name());
35/// }
36///
37/// Ok(())
38/// }
39/// ```
40pub struct PluginManagerBuilder {
41 /// 已注册的插件(构建阶段可变)
42 /// Key: 插件名称, Value: 插件实例
43 plugins: HashMap<String, Arc<dyn Plugin>>,
44
45 /// 插件配置
46 /// Key: 插件名称, Value: 配置 JSON
47 configs: HashMap<String, JsonValue>,
48}
49
50impl PluginManagerBuilder {
51 /// 创建新的插件管理器构建器
52 ///
53 /// # 返回
54 /// - 新的 PluginManagerBuilder 实例
55 ///
56 /// # 示例
57 ///
58 /// ```rust
59 /// use yang_base::plugin::PluginManagerBuilder;
60 ///
61 /// let builder = PluginManagerBuilder::new();
62 /// ```
63 pub fn new() -> Self {
64 Self {
65 plugins: HashMap::new(),
66 configs: HashMap::new(),
67 }
68 }
69
70 /// 注册插件(构建阶段使用)
71 ///
72 /// 检查插件名称是否重复,调用 `on_register()` 回调,然后插入 HashMap。
73 ///
74 /// # 参数
75 /// - `plugin`: 插件实例
76 ///
77 /// # 返回
78 /// - `Ok(())`: 注册成功
79 /// - `Err(BaseError)`: 注册失败(如插件名称重复或注册回调失败)
80 ///
81 /// # 示例
82 ///
83 /// ```rust,ignore
84 /// use yang_base::plugin::{Plugin, PluginManagerBuilder};
85 ///
86 /// let mut builder = PluginManagerBuilder::new();
87 /// builder.register(MyPlugin).await?;
88 /// ```
89 pub async fn register<P: Plugin + 'static>(&mut self, plugin: P) -> Result<(), BaseError> {
90 let name = normalize_plugin_name(plugin.name())?.to_string();
91
92 // 检查插件是否已注册(构建阶段直接访问 HashMap,无需加锁)
93 if self.plugins.contains_key(&name) {
94 return Err(BaseError::PluginAlreadyRegistered(name));
95 }
96
97 let plugin = Arc::new(plugin);
98
99 // 调用注册回调
100 plugin
101 .on_register()
102 .await
103 .map_err(|source| BaseError::PluginLifecycleFailed {
104 plugin: name.clone(),
105 stage: PluginLifecycleStage::Register,
106 source,
107 })?;
108
109 // 插入 HashMap
110 self.plugins.insert(name.clone(), plugin);
111
112 log::info!("插件已注册(构建阶段): {}", name);
113 Ok(())
114 }
115
116 /// 消费构建器,生成不可变的 PluginRegistry
117 ///
118 /// 调用此方法后,构建器被消费,返回运行阶段使用的 `PluginRegistry`。
119 /// `PluginRegistry` 在构建时执行一次拓扑排序并缓存结果。
120 ///
121 /// # 返回
122 /// - `Ok(PluginRegistry)`: 构建成功
123 /// - `Err(BaseError::PluginDependencyMissing)`: 某插件的依赖未注册
124 /// - `Err(BaseError::PluginCircularDependency)`: 插件之间存在循环依赖
125 ///
126 /// # 示例
127 ///
128 /// ```rust,ignore
129 /// use yang_base::plugin::PluginManagerBuilder;
130 ///
131 /// let mut builder = PluginManagerBuilder::new();
132 /// // ... 注册插件 ...
133 /// let registry = builder.build()?;
134 /// ```
135 pub fn build(self) -> Result<PluginRegistry, BaseError> {
136 // 检查每个插件的依赖是否都已注册
137 for (plugin_name, plugin) in &self.plugins {
138 for dep in plugin.dependencies() {
139 let dep = normalize_plugin_name(dep)?;
140 if !self.plugins.contains_key(dep) {
141 // 依赖未注册,返回错误
142 return Err(BaseError::PluginDependencyMissing(
143 plugin_name.clone(),
144 dep.to_string(),
145 ));
146 }
147 }
148 }
149 // 依赖完整性检查通过,构建注册表(内部会检测循环依赖)
150 PluginRegistry::new(self.plugins, self.configs)
151 }
152}
153
154impl Default for PluginManagerBuilder {
155 fn default() -> Self {
156 Self::new()
157 }
158}