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(|(_, °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 /// # 参数
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}