Rust对象映射库o2o-impl的使用指南

概述

o2o-impl是一个Rust宏库，用于简化对象之间的转换过程。它通过自动生成转换代码来减少手动编写繁琐的转换逻辑，特别适合在不同层(如数据库层、业务逻辑层、API层)之间传输数据时使用。

主要特性

• 自动生成From/TryFrom实现
• 支持嵌套结构转换
• 可自定义字段映射规则
• 支持可选字段和错误处理
• 编译时生成代码，无运行时开销

基本使用方法

1. 添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
o2o = "0.3"

2. 基本结构转换

use o2o::o2o;

#[derive(o2o)]
#[from(Source)] // 自动生成 From<Source> 实现
struct Target {
    some_int: i32,
    some_float: f32,
    some_string: String,
}

struct Source {
    some_int: i32,
    some_float: f32,
    some_string: String,
}

fn main() {
    let source = Source {
        some_int: 123,
        some_float: 456.789,
        some_string: "Hello".to_string(),
    };
    
    let target: Target = source.into();
    println!("Converted: {}, {}, {}", target.some_int, target.some_float, target.some_string);
}

3. 字段名映射

当字段名不一致时，可以使用#[map_from]属性：

#[derive(o2o)]
#[from(Source)]
struct Target {
    #[map_from(some_int)] // 指定源字段名
    number: i32,
    #[map_from(some_float)]
    float_value: f32,
    #[map_from(some_string)]
    text: String,
}

4. 嵌套结构转换

#[derive(o2o)]
#[from(Source)]
struct Target {
    id: i32,
    #[o2o(from_owned)] // 转换嵌套结构
    user: UserDto,
}

#[derive(o2o)]
#[from(User)]
struct UserDto {
    name: String,
    age: i32,
}

struct Source {
    id: i32,
    user: User,
}

struct User {
    name: String,
    age: i32,
}

5. 可选字段和错误处理

#[derive(o2o)]
#[try_from(Source)] // 生成 TryFrom 实现
struct Target {
    id: i32,
    #[map_from(user_name)] // 可选字段
    name: Option<String>,
    #[map_from(age)]
    #[o2o(from_if(|age| *age >= 0, "Age cannot be negative"))]
    age: i32,
}

struct Source {
    id: i32,
    user_name: Option<String>,
    age: i32,
}

fn main() {
    let source = Source {
        id: 1,
        user_name: Some("Alice".to_string()),
        age: -5,
    };
    
    match Target::try_from(source) {
        Ok(_) => println!("Conversion successful"),
        Err(e) => println!("Error: {}", e), // 会输出 "Error: Age cannot be negative"
    }
}

高级用法

自定义转换函数

#[derive(o2o)]
#[from(Source)]
struct Target {
    #[map_from(value)]
    #[o2o(from_with(|x| format!("Value is: {}", x))] // 自定义转换逻辑
    formatted_value: String,
}

忽略字段

#[derive(o2o)]
#[from(Source)]
struct Target {
    id: i32,
    #[o2o(skip)] // 忽略此字段
    ignored_field: i32, // 需要提供默认值或实现Default
}

完整示例

下面是一个综合使用o2o-impl各种特性的完整示例：

use o2o::o2o;

// 源数据结构
struct PersonSource {
    person_id: i32,
    full_name: String,
    years_old: i32,
    email: Option<String>,
    address: AddressSource,
    metadata: String, // 我们不关心这个字段
}

struct AddressSource {
    street: String,
    city: String,
    zip_code: String,
}

// 目标数据结构
#[derive(o2o)]
#[try_from(PersonSource)] // 生成TryFrom实现
struct PersonDto {
    #[map_from(person_id)]
    id: i32,
    #[map_from(full_name)]
    name: String,
    #[map_from(years_old)]
    #[o2o(from_if(|age| *age >= 0, "Age must be positive"))]
    age: i32,
    #[map_from(email)]
    contact_email: Option<String>,
    #[o2o(from_owned)] // 转换嵌套结构
    address: AddressDto,
    #[o2o(skip)] // 忽略metadata字段
    #[o2o(default)] // 使用默认值
    ignored_field: i32,
}

#[derive(o2o)]
#[from(AddressSource)]
struct AddressDto {
    street: String,
    city: String,
    #[map_from(zip_code)]
    postal_code: String,
}

fn main() {
    let source = PersonSource {
        person_id: 1,
        full_name: "John Doe".to_string(),
        years_old: 30,
        email: Some("john@example.com".to_string()),
        address: AddressSource {
            street: "123 Main St".to_string(),
            city: "New York".to_string(),
            zip_code: "10001".to_string(),
        },
        metadata: "Some metadata".to_string(),
    };

    // 使用自动生成的TryFrom实现
    match PersonDto::try_from(source) {
        Ok(person) => {
            println!("Converted successfully:");
            println!("ID: {}", person.id);
            println!("Name: {}", person.name);
            println!("Age: {}", person.age);
            println!("Email: {:?}", person.contact_email);
            println!("Address: {}, {}, {}", 
                person.address.street, 
                person.address.city, 
                person.address.postal_code);
        }
        Err(e) => println!("Conversion failed: {}", e),
    }
}

性能考虑

o2o-impl在编译时生成所有转换代码，因此运行时性能与手写转换代码相同，没有额外的运行时开销。

总结

o2o-impl通过减少样板代码显著提高了Rust开发效率，特别是在需要频繁在不同数据表示之间转换的项目中。它的强类型保证和编译时检查也帮助避免了运行时错误。