Skip to main content

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}