rust-patterns 0.1.1

# Rust Patterns


一个统一的 Rust 设计模式库，整合了 `rust-pattern-components` 和 `rust-pattern-macros`，提供类型安全、高效的设计模式实现。

[![Rust](https://img.shields.io/badge/rust-2024-blue.svg)](https://www.rust-lang.org/)
[![Crates.io](https://img.shields.io/crates/v/rust-patterns.svg)](https://crates.io/crates/rust-patterns)
[![Documentation](https://docs.rs/rust-patterns/badge.svg)](https://docs.rs/rust-patterns)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 架构


`rust-patterns` 是一个统一的包装器库，它整合了两个核心组件：

1. **`rust-pattern-components`** - 设计模式的核心实现
2. **`rust-pattern-macros`** - 过程宏，简化设计模式的使用

这个库重新导出了所有必要的类型、trait 和宏，让你可以通过单一依赖使用完整的设计模式功能。

## 特性


- 🚀 **类型安全** - 充分利用 Rust 的类型系统确保编译时安全
- 🧵 **线程安全** - 所有组件都设计为线程安全，支持并发使用
- 📦 **零成本抽象** - 使用宏和编译时注册实现零运行时开销
- 🔧 **统一接口** - 单一依赖访问所有设计模式功能
- 📚 **完整文档** - 详细的 API 文档和使用示例
- 🔌 **即插即用** - 开箱即用，无需配置多个依赖

## 支持的设计模式


### 1. 构建器模式 (Builder Pattern)

提供 `builder_helper!` 宏，为构建器类型添加条件性设置值的方法。

### 2. 工厂模式 (Factory Pattern)

包含完整的工厂模式实现，支持编译时注册和运行时查找。提供 `#[simple_factory]` 属性宏简化使用。

### 3. 观察者模式 (Observer Pattern)

类型安全的发布-订阅机制，支持弱引用和错误处理策略。提供 `#[observable]` 属性宏自动实现。

## 安装


将以下内容添加到你的 `Cargo.toml` 文件中：

```toml
[dependencies]
rust-patterns = "0.1"
```

这个依赖会自动引入：
- `rust-pattern-components` - 设计模式的核心实现
- `rust-pattern-macros` - 过程宏支持

## 快速开始


### 构建器模式（使用 builder_helper! 宏）


```rust
use rust_patterns::builder_helper;

struct User {
    name: String,
    email: Option<String>,
    age: Option<u32>,
}

struct UserBuilder {
    name: String,
    email: Option<String>,
    age: Option<u32>,
}

impl UserBuilder {
    fn new(name: String) -> Self {
        Self {
            name,
            email: None,
            age: None,
        }
    }

    fn email(mut self, email: String) -> Self {
        self.email = Some(email);
        self
    }

    fn age(mut self, age: u32) -> Self {
        self.age = Some(age);
        self
    }

    fn build(self) -> User {
        User {
            name: self.name,
            email: self.email,
            age: self.age,
        }
    }
}

// 为 UserBuilder 添加条件性设置方法
builder_helper!(Self, UserBuilder);

fn main() {
    let user = UserBuilder::new("Alice".to_string())
        .when_some(Some("alice@example.com".to_string()), |b, e| b.email(e))
        .when_some(None::<u32>, |b, a| b.age(a)) // 不会设置年龄
        .build();
    
    println!("User: {}, Email: {:?}", user.name, user.email);
}
```

### 工厂模式（使用 #[simple_factory] 属性宏）


```rust
use rust_patterns::simple_factory;

// 定义产品 trait
#[simple_factory]

pub trait Shape {
    fn draw(&self);
    fn area(&self) -> f64;
}

// 实现具体产品
#[derive(Default)]

struct Circle {
    radius: f64,
}

impl Shape for Circle {
    fn draw(&self) {
        println!("Drawing circle with radius {}", self.radius);
    }
    
    fn area(&self) -> f64 {
        std::f64::consts::PI * self.radius * self.radius
    }
}

#[derive(Default)]

struct Square {
    side: f64,
}

impl Shape for Square {
    fn draw(&self) {
        println!("Drawing square with side {}", self.side);
    }
    
    fn area(&self) -> f64 {
        self.side * self.side
    }
}

// 注意：实际使用中需要在单独的模块中注册工厂
// register_factory!(dyn Shape, "circle", Circle);
// register_factory!(dyn Shape, "square", Square);

fn main() {
    // 使用工厂创建实例
    // FactoryFallback 参数指定找不到工厂时的回退策略
    match ShapeFactory::create("circle", rust_patterns::FactoryFallback::NoFallback) {
        Ok((id, shape)) => {
            println!("Created shape: {}", id);
            shape.draw();
            println!("Area: {}", shape.area());
        }
        Err(e) => eprintln!("Error creating shape: {}", e),
    }
}
```

### 观察者模式（使用 #[observable] 属性宏）


```rust
use std::sync::Arc;
use rust_patterns::{observable, Observer, Observable};

// 使用 observable 宏自动实现 Observable trait
#[observable(state = f64, error = String)]

struct TemperatureSensor {
    temperature: f64,
}

// 实现观察者
struct TemperatureDisplay;

impl Observer for TemperatureDisplay {
    type Subject = TemperatureSensor;
    
    fn update(&self, state: &f64) -> Result<(), String> {
        println!("Temperature updated: {:.1}°C", state);
        Ok(())
    }
}

struct TemperatureLogger;

impl Observer for TemperatureLogger {
    type Subject = TemperatureSensor;
    
    fn update(&self, state: &f64) -> Result<(), String> {
        println!("[LOG] Temperature: {:.1}°C", state);
        Ok(())
    }
}

fn main() {
    // 创建被观察者（需要手动初始化）
    let mut sensor = TemperatureSensor {
        temperature: 20.0,
        registry: rust_patterns::ObserverRegistry::new(),
    };
    
    // 创建观察者
    let display = Arc::new(TemperatureDisplay);
    let logger = Arc::new(TemperatureLogger);
    
    // 附加观察者
    sensor.attach(display.clone());
    sensor.attach(logger.clone());
    
    // 更新温度并通知观察者
    sensor.temperature = 25.5;
    match sensor.notify(&sensor.temperature) {
        Ok(()) => println!("All observers notified successfully"),
        Err(e) => eprintln!("Error notifying observers: {}", e),
    }
    
    // 分离观察者
    sensor.detach(logger);
    
    // 再次通知（忽略错误）
    sensor.temperature = 26.0;
    sensor.notify_ignore_error(&sensor.temperature).unwrap();
}
```

## API 文档


### 构建器模式


#### `builder_helper!` 宏


为构建器类型添加 `when_some` 方法，允许条件性地设置可选值。

```rust
builder_helper!(Self, BuilderType1, BuilderType2);
// 或
builder_helper!(&mut Self, BuilderType1, BuilderType2);
```

生成的 `when_some` 方法签名：
```rust
fn when_some<T>(self, value: Option<T>, func: impl FnOnce(Self, T) -> Self) -> Self
```

### 工厂模式


#### `#[simple_factory]` 属性宏（来自 rust-pattern-macros）


应用于 trait 定义，自动生成对应的工厂结构体。

```rust
#[simple_factory]

pub trait MyTrait {
    // trait 方法
}

// 也可以指定额外的 trait bound
#[simple_factory(Send + Sync)]

pub trait MyTrait {
    // trait 方法
}
```

#### `register_factory!` 宏（来自 rust-pattern-components）


注册具体实现到工厂系统。

```rust
register_factory!(dyn MyTrait, "implementation_id", ConcreteType);
```



### 观察者模式


#### `Observer` trait（来自 rust-pattern-components）


观察者必须实现的 trait：

```rust
pub trait Observer {
    type State;
    type Error;
    
    fn update(&self, state: &Self::State) -> Result<(), Self::Error>;
}
```

#### `Observable` trait 和 `#[observable]` 属性宏


`Observable` trait 定义被观察者必须实现的接口，`#[observable]` 属性宏自动生成实现：

```rust
#[observable(state = Type, error = ErrorType)]

struct MyStruct {
    // 字段定义
}
```

宏会为结构体：
1. 添加 `registry: ObserverRegistry<Self>` 字段
2. 实现 `Observable` trait
3. 提供 `attach`、`detach`、`notify` 和 `notify_ignore_error` 方法





## 组件详情


### 核心组件

- **`rust-pattern-components`** (`0.1.1`) - 提供构建器、工厂、观察者模式的核心实现
- **`rust-pattern-macros`** (`0.1.1`) - 提供 `#[simple_factory]` 和 `#[observable]` 属性宏

### 版本兼容性

所有组件版本保持同步，确保兼容性：
- `rust-patterns = "0.1"` 对应 `rust-pattern-components = "0.1"` 和 `rust-pattern-macros = "0.1"`

## 高级用法


### 自定义错误处理


```rust
use rust_patterns::{observable, Observer, Observable};
use thiserror::Error;

#[derive(Debug, Error)]

enum AppError {
    #[error("Invalid temperature: {0}")]
    InvalidTemperature(f64),
    #[error("Network error")]
    NetworkError,
}

#[observable(state = f64, error = AppError)]

struct TemperatureSensor {
    temperature: f64,
}

struct TemperatureValidator;

impl Observer for TemperatureValidator {
    type Subject = TemperatureSensor;
    
    fn update(&self, state: &f64) -> Result<(), AppError> {
        if *state < -273.15 {
            Err(AppError::InvalidTemperature(*state))
        } else {
            println!("Valid temperature: {}", state);
            Ok(())
        }
    }
}
```

### 线程安全的观察者


```rust
use std::sync::Arc;
use std::thread;
use rust_patterns::{observable, Observer, Observable};

#[observable(state = String, error = ())]

struct MessageBroadcaster {
    message: String,
}

struct ConcurrentObserver {
    id: usize,
}

impl Observer for ConcurrentObserver {
    type Subject = MessageBroadcaster;
    
    fn update(&self, state: &String) -> Result<(), ()> {
        println!("Observer {} received: {}", self.id, state);
        Ok(())
    }
}

fn main() {
    let mut broadcaster = MessageBroadcaster {
        message: String::new(),
        registry: rust_patterns::ObserverRegistry::new(),
    };
    let mut handles = vec![];
    
    // 创建多个观察者
    for i in 0..5 {
        let observer = Arc::new(ConcurrentObserver { id: i });
        broadcaster.attach(observer.clone());
        
        // 在单独的线程中模拟异步通知
        let broadcaster_clone = broadcaster.clone();
        let handle = thread::spawn(move || {
            let message = format!("Message from thread {}", i);
            // 在实际使用中，需要更新状态并通知
            // broadcaster_clone.notify_ignore_error(&message).unwrap();
        });
        handles.push(handle);
    }
    
    for handle in handles {
        handle.join().unwrap();
    }
}
```

## 性能特点


- **零运行时开销**：工厂模式使用编译时注册，无运行时查找开销
- **内存高效**：观察者模式使用弱引用，避免内存泄漏
- **线程安全**：所有组件都设计为 `Send + Sync`
- **无动态分配**：构建器模式在编译时生成代码
- **统一依赖**：单一包整合所有设计模式功能
- **宏支持**：属性宏简化复杂模式的使用

## 贡献指南


1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request

## 许可证


本项目基于 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 致谢


- 感谢 Rust 社区提供的优秀工具和库
- 受《设计模式：可复用面向对象软件的基础》一书启发
- 感谢所有贡献者和用户

## 相关项目


- [rust-pattern-components](https://github.com/sdht-siset/rust-pattern-components) - 设计模式核心实现
- [rust-pattern-macros](https://github.com/sdht-siset/rust-pattern-macros) - 设计模式过程宏

## 联系方式


如有问题或建议，请通过以下方式联系：
- 提交 [Issue](https://github.com/sdht-siset/rust-patterns/issues)
- 发送邮件至：yanglsh@yeah.net

---

**Rust Patterns** - 统一的 Rust 设计模式库，让设计模式更简单、更安全、更高效！