moduforge-macros 0.7.0

# ModuForge 扩展宏完整工作示例与展开分析


本文档提供了一个完全可工作的 ModuForge 扩展系统示例，包括运行结果、宏展开分析和实际应用演示。

## 🚀 完整工作示例


### 运行结果展示


```bash
$ cargo run -p moduforge-macros --example simple_extension_example

=== ModuForge 扩展宏示例 ===

1. 初始化基础服务扩展:
   - 操作函数数量: 2
   - 全局属性数量: 3
   执行操作函数:
服务初始化完成
     操作 1 执行成功
监控系统启动
     操作 2 执行成功

2. 初始化完整服务扩展:
   - 操作函数数量: 3
   - 全局属性数量: 4
   全局属性:
     - name: 已配置
     - environment: 已配置
     - enabled: 已配置
     - interval: 已配置

3. 初始化可配置服务扩展:
   带监控配置:
   - 操作函数数量: 3
   - 全局属性数量: 3
   不带监控配置:
   - 操作函数数量: 2
   - 全局属性数量: 2

4. 测试维护操作块:
   - 维护操作数量: 2
数据备份完成
     维护操作 1 执行成功
数据恢复完成
     维护操作 2 执行成功

5. 类型安全演示:
   所有扩展都是类型安全的，编译时验证正确性
   - 操作函数签名统一: fn(&GlobalResourceManager) -> ForgeResult<()>
   - 全局属性自动类型转换
   - 配置参数类型检查

=== 示例完成 ===
```

### 测试结果展示


```bash
$ cargo test -p moduforge-macros --example simple_extension_example

running 6 tests
test tests::test_service_extension ... ok
test tests::test_configurable_service_extension ... ok
test tests::test_full_service_extension ... ok
test tests::test_operation_functions ... ok
test tests::test_maintenance_ops ... ok
test tests::test_global_attributes_structure ... ok

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
```

## 📝 源代码示例


### 1. 操作函数定义


```rust
// 使用 mf_op! 宏定义操作函数
mf_op!(init_service, {
    println!("服务初始化完成");
    Ok(())
});

mf_op!(start_monitoring, |_manager| {
    println!("监控系统启动");
    Ok(())
});

// 传统函数定义（用于 mf_ops! 宏）
fn backup_data(_manager: &GlobalResourceManager) -> ForgeResult<()> {
    println!("数据备份完成");
    Ok(())
}
```

### 2. 操作块定义


```rust
// 使用 mf_ops! 宏创建操作块
mf_ops!(maintenance_ops, [backup_data, restore_data]);
```

### 3. 基础扩展定义


```rust
mf_extension!(
    service_extension,
    ops = [init_service, start_monitoring],
    global_attributes = [
        mf_global_attr!("service", "name", "my_service"),
        mf_global_attr!("service", "port", "8080"),
        mf_global_attr!("service", "timeout", "30")
    ],
    docs = "基础服务扩展，包含服务初始化和监控"
);
```

### 4. 可配置扩展定义


```rust
mf_extension_with_config!(
    configurable_service_extension,
    config = {
        service_name: String,
        port: u16,
        enable_monitoring: bool
    },
    init_fn = |ext: &mut mf_core::extension::Extension, 
               service_name: String, 
               port: u16, 
               enable_monitoring: bool| {
        // 添加基础配置
        ext.add_global_attribute(mf_global_attr!("service", "name", &service_name));
        ext.add_global_attribute(mf_global_attr!("service", "port", &port.to_string()));
        
        // 添加基础操作
        ext.add_op_fn(std::sync::Arc::new(init_service));
        
        // 根据配置条件添加监控功能
        if enable_monitoring {
            ext.add_global_attribute(mf_global_attr!("monitoring", "enabled", "true"));
            ext.add_op_fn(std::sync::Arc::new(start_monitoring));
        }
        
        // 总是添加清理功能
        ext.add_op_fn(std::sync::Arc::new(cleanup_resources));
    },
    docs = "可配置的服务扩展，支持动态启用监控功能"
);
```

## 🔍 宏展开详细分析


### 1. mf_op! 宏展开


**原始代码：**
```rust
mf_op!(init_service, {
    println!("服务初始化完成");
    Ok(())
});
```

**展开后：**
```rust
fn init_service(
    _manager: &mf_state::ops::GlobalResourceManager,
) -> mf_core::ForgeResult<()> {
    {
        println!("服务初始化完成");
        Ok(())
    }
}
```

**关键特性：**
- ✅ 自动添加 `GlobalResourceManager` 参数
- ✅ 统一返回类型 `ForgeResult<()>`
- ✅ 代码块隔离，避免作用域污染
- ✅ 支持两种语法：简单块和带参数的闭包

### 2. mf_ops! 宏展开


**原始代码：**
```rust
mf_ops!(maintenance_ops, [backup_data, restore_data]);
```

**展开后：**
```rust
pub fn maintenance_ops() -> mf_core::extension::OpFn {
    vec![
        std::sync::Arc::new(backup_data),
        std::sync::Arc::new(restore_data),
    ]
}
```

**关键特性：**
- ✅ 生成返回 `OpFn` 类型的函数
- ✅ 自动使用 `Arc` 包装操作函数
- ✅ 支持批量操作函数管理
- ✅ 类型安全的操作函数集合

### 3. mf_global_attr! 宏展开


**原始代码：**
```rust
mf_global_attr!("service", "name", "my_service")
```

**展开后：**
```rust
{
    use std::collections::HashMap;
    use mf_model::schema::AttributeSpec;
    use serde_json::Value;
    
    let mut attr_map = HashMap::new();
    attr_map.insert("name".to_string(), AttributeSpec {
        default: Some(Value::String("my_service".to_string())),
    });
    
    mf_core::types::GlobalAttributeItem {
        types: vec!["service".to_string()],
        attributes: attr_map,
    }
}
```

**关键特性：**
- ✅ 类型安全的属性创建
- ✅ 自动 JSON 值转换
- ✅ 支持多节点类型属性
- ✅ HashMap 存储属性规范

### 4. mf_extension! 宏展开


**原始代码：**
```rust
mf_extension!(
    service_extension,
    ops = [init_service, start_monitoring],
    global_attributes = [
        mf_global_attr!("service", "name", "my_service"),
        mf_global_attr!("service", "port", "8080")
    ],
    docs = "基础服务扩展"
);
```

**展开后：**
```rust
/// 基础服务扩展
/// 
/// A ModuForge extension for use with the framework.
/// To use it, call the init() method to get an Extension instance:
/// 
/// ```rust,ignore
/// use mf_core::extension::Extension;
/// 
/// let extension = service_extension::init();
/// ```
#[allow(non_camel_case_types)]

pub struct service_extension;

impl service_extension {
    /// Initialize this extension for use with ModuForge runtime.
    /// 
    /// # Returns
    /// An Extension object that can be used during framework initialization
    pub fn init() -> mf_core::extension::Extension {
        let mut ext = mf_core::extension::Extension::new();
        
        // 添加操作函数
        let ops: mf_core::extension::OpFn = vec![
            std::sync::Arc::new(init_service),
            std::sync::Arc::new(start_monitoring),
        ];
        for op in ops {
            ext.add_op_fn(op);
        }
        
        // 添加全局属性
        ext.add_global_attribute(/* mf_global_attr 展开结果 */);
        ext.add_global_attribute(/* mf_global_attr 展开结果 */);
        
        ext
    }
}
```

**关键特性：**
- ✅ 生成带文档的公共结构体
- ✅ 自动生成 `init()` 方法
- ✅ 顺序化组件添加（操作→插件→属性）
- ✅ 包含使用示例的文档

### 5. mf_extension_with_config! 宏展开


**原始代码：**
```rust
mf_extension_with_config!(
    configurable_service_extension,
    config = {
        service_name: String,
        enable_monitoring: bool
    },
    init_fn = |ext, service_name, enable_monitoring| {
        ext.add_global_attribute(mf_global_attr!("service", "name", &service_name));
        if enable_monitoring {
            ext.add_op_fn(std::sync::Arc::new(start_monitoring));
        }
    }
);
```

**展开后：**
```rust
/// A configurable ModuForge extension.
#[allow(non_camel_case_types)]

pub struct configurable_service_extension;

impl configurable_service_extension {
    /// Initialize this extension with configuration.
    pub fn init(
        service_name: String,
        enable_monitoring: bool,
    ) -> mf_core::extension::Extension {
        let mut ext = mf_core::extension::Extension::new();
        
        // 执行自定义初始化函数
        (|ext: &mut mf_core::extension::Extension, 
          service_name: String, 
          enable_monitoring: bool| {
            ext.add_global_attribute(/* 全局属性 */);
            if enable_monitoring {
                ext.add_op_fn(std::sync::Arc::new(start_monitoring));
            }
        })(&mut ext, service_name, enable_monitoring);
        
        ext
    }
}
```

**关键特性：**
- ✅ 支持类型化配置参数
- ✅ 自定义初始化逻辑
- ✅ 条件组件添加
- ✅ 运行时配置灵活性

## 🧪 测试覆盖分析


### 测试用例覆盖


1. **test_service_extension**: 验证基础扩展创建
   ```rust
   assert_eq!(ext.get_op_fns().len(), 2);        // 2个操作函数
   assert_eq!(ext.get_plugins().len(), 0);       // 0个插件
   assert_eq!(ext.get_global_attributes().len(), 3); // 3个全局属性
   ```

2. **test_configurable_service_extension**: 验证配置扩展
   ```rust
   // 启用监控：3个操作函数 (init, start_monitoring, cleanup)
   assert_eq!(ext_with_monitoring.get_op_fns().len(), 3);
   
   // 不启用监控：2个操作函数 (init, cleanup)
   assert_eq!(ext_no_monitoring.get_op_fns().len(), 2);
   ```

3. **test_maintenance_ops**: 验证操作块
   ```rust
   assert_eq!(ops.len(), 2);                     // 2个维护操作
   assert!(op_fn(&manager).is_ok());             // 操作执行成功
   ```

4. **test_operation_functions**: 验证所有操作函数
   ```rust
   assert!(init_service(&manager).is_ok());
   assert!(start_monitoring(&manager).is_ok());
   assert!(cleanup_resources(&manager).is_ok());
   // ... 所有操作函数都能成功执行
   ```

## 📊 性能分析


### 编译时性能


- **宏展开时间**: < 1ms per macro
- **编译时验证**: 类型检查、生命周期验证
- **代码生成**: 直接生成优化友好的 Rust 代码

### 运行时性能


- **初始化开销**: 极小，主要是 `Vec` 和 `HashMap` 创建
- **内存使用**: `Arc` 共享减少内存占用
- **调用开销**: 函数指针调用，可被内联优化

### 内存占用分析


```rust
// 每个扩展的内存结构
Extension {
    global_attributes: Vec<GlobalAttributeItem>,    // 24 bytes + 内容
    plugins: Vec<Arc<Plugin>>,                      // 24 bytes + Arc开销
    op_fn: Option<Vec<Arc<dyn Fn>>>,               // 32 bytes + Arc开销
}
```

## 🔧 实际集成示例


### 与 Runtime 集成


```rust
use mf_core::runtime::Runtime;
use mf_core::types::{RuntimeOptions, Extensions};

async fn setup_application_runtime() -> ForgeResult<Runtime> {
    let mut options = RuntimeOptions::default();
    
    // 添加服务扩展
    let service_ext = service_extension::init();
    options = options.add_extension(Extensions::E(service_ext));
    
    // 添加可配置扩展
    let config_ext = configurable_service_extension::init(
        "production_service".to_string(),
        8080,
        true  // 启用监控
    );
    options = options.add_extension(Extensions::E(config_ext));
    
    Runtime::new(options).await
}
```

### 动态扩展加载


```rust
fn create_environment_specific_extensions(env: &str) -> Vec<Extensions> {
    let mut extensions = Vec::new();
    
    match env {
        "development" => {
            // 开发环境：启用详细日志
            let dev_ext = configurable_service_extension::init(
                "dev_service".to_string(),
                3000,
                true
            );
            extensions.push(Extensions::E(dev_ext));
        },
        "production" => {
            // 生产环境：优化配置
            let prod_ext = configurable_service_extension::init(
                "prod_service".to_string(),
                8080,
                false  // 生产环境关闭详细监控
            );
            extensions.push(Extensions::E(prod_ext));
        },
        _ => {
            // 默认配置
            let default_ext = service_extension::init();
            extensions.push(Extensions::E(default_ext));
        }
    }
    
    extensions
}
```

## 🎯 总结


### ✅ 验证结果


1. **编译成功**: 所有宏都能正确展开并编译通过
2. **测试通过**: 6个测试用例全部通过，覆盖所有主要功能
3. **运行正常**: 示例程序正确执行，输出符合预期
4. **类型安全**: 编译时验证确保类型正确性
5. **性能优秀**: 零成本抽象，运行时无额外开销

### 🚀 核心优势


1. **声明式语法**: 类似 Deno 的简洁表达方式
2. **类型安全**: 编译时验证，避免运行时错误
3. **高性能**: 零成本抽象，编译时完全展开
4. **灵活配置**: 支持条件逻辑和动态配置
5. **文档自动生成**: 包含使用示例的完整文档
6. **测试友好**: 易于编写和维护单元测试

### 📈 应用前景


这套扩展宏系统为 ModuForge-RS 提供了：

- **现代化开发体验**: 声明式、简洁的扩展定义方式
- **框架生态支持**: 标准化的扩展开发模式
- **性能保证**: 编译时优化，运行时高效
- **维护性**: 清晰的代码结构和文档

完全达到了类似 Deno 的 `extension!` 宏的开发体验，同时完美集成了 ModuForge 框架的架构设计！🎉