Rust类型定义转换库typescript-type-def-derive使用指南

typescript-type-def-derive是一个Rust过程宏库，用于自动从Rust类型生成TypeScript类型定义。它简化了前后端共享类型的工作流程，特别适合全栈Rust开发者。

安装

在Cargo.toml中添加依赖：

[dependencies]
typescript-type-def-derive = "0.1"
serde = { version = "1.0", features = ["derive"] }  # 可选，用于序列化支持

基本用法

为结构体生成TypeScript定义

use typescript_type_def::TypeDef;

#[derive(TypeDef)]
struct User {
    id: u32,
    username: String,
    is_active: bool,
    roles: Vec<String>,
}

这将生成对应的TypeScript接口：

interface User {
    id: number;
    username: string;
    is_active: boolean;
    roles: string[];
}

为枚举生成TypeScript定义

#[derive(TypeDef)]
enum Status {
    Active,
    Inactive,
    Banned(String),  // 带有关联数据的变体
    Suspended { reason: String, days: u32 },  // 具名字段变体
}

生成的TypeScript类型：

type Status = 
    | "Active"
    | "Inactive"
    | { Banned: string }
    | { Suspended: { reason: string, days: number } };

高级特性

自定义类型名称

#[derive(TypeDef)]
#[typescript(name = "IUser")]  // 自定义TypeScript类型名称
struct User {
    // 字段...
}

忽略字段

#[derive(TypeDef)]
struct User {
    id: u32,
    username: String,
    #[typescript(skip)]  // 跳过此字段
    password_hash: String,
}

可选字段

#[derive(TypeDef)]
struct User {
    id: u32,
    username: String,
    #[typescript(optional)]  // 标记为可选
    email: Option<String>,
}

使用Serde属性

库会自动识别常用的Serde属性：

#[derive(TypeDef, Serialize)]
struct User {
    #[serde(rename = "userId")]  // 自动应用到TypeScript
    id: u32,
    username: String,
}

生成TypeScript定义字符串

use typescript_type_def::TypeDef;

let ts_definition = User::type_def().to_string();
println!("{}", ts_definition);

实际应用示例

use typescript_type_def::{TypeDef, DefinitionFile};

#[derive(TypeDef)]
pub struct ApiResponse<T: TypeDef> {
    success: bool,
    data: T,
    error: Option<String>,
}

#[derive(TypeDef)]
pub struct Product {
    id: u32,
    name: String,
    price: f64,
    categories: Vec<String>,
}

// 生成完整的TypeScript定义文件
let mut file = DefinitionFile::new();
file.add::<ApiResponse<Product>>();
file.add::<Product>();

println!("{}", file.to_string());

输出结果：

interface Product {
    id: number;
    name: string;
    price: number;
    categories: string[];
}

interface ApiResponse<T> {
    success: boolean;
    data: T;
    error: string | null;
}

完整示例demo

下面是一个完整的Rust项目示例，展示如何使用typescript-type-def-derive库：

// main.rs
use typescript_type_def::{TypeDef, DefinitionFile};

// 定义一个用户结构体
#[derive(TypeDef)]
pub struct User {
    id: u64,
    username: String,
    #[typescript(optional)]
    email: Option<String>,
    #[typescript(skip)]
    password_hash: String,
    is_admin: bool,
}

// 定义一个API响应结构体
#[derive(TypeDef)]
pub struct ApiResponse<T: TypeDef> {
    code: u32,
    message: String,
    data: Option<T>,
}

// 定义一个订单状态枚举
#[derive(TypeDef)]
pub enum OrderStatus {
    Pending,
    Processing,
    Shipped,
    Delivered,
    Cancelled(String), // 取消原因
}

fn main() {
    // 创建TypeScript定义文件
    let mut file = DefinitionFile::new();
    
    // 添加所有需要导出的类型
    file.add::<User>();
    file.add::<ApiResponse<User>>();
    file.add::<OrderStatus>();
    
    // 输出生成的TypeScript定义
    println!("// 自动生成的TypeScript类型定义\n");
    println!("{}", file.to_string());
}

生成的TypeScript定义：

// 自动生成的TypeScript类型定义

interface User {
    id: number;
    username: string;
    email: string | null;
    is_admin: boolean;
}

interface ApiResponse<T> {
    code: number;
    message: string;
    data: T | null;
}

type OrderStatus = 
    | "Pending"
    | "Processing"
    | "Shipped"
    | "Delivered"
    | { Cancelled: string };

注意事项

1. 基本类型会自动映射：

   • Rust的i32/u32等 → TypeScript的number
   • String → string
   • bool → boolean
   • Vec<T> → T[]
   • Option<T> → T | null

2. 对于自定义类型，确保它们也实现了TypeDef trait

3. 复杂生命周期或泛型约束可能需要额外处理

这个库极大简化了维护Rust和TypeScript之间类型同步的工作，特别适合WebAssembly项目或前后端分离架构中使用Rust作为后端的场景。