Rust的TypeScript类型定义生成工具typescript-type-def的使用，自动生成Rust到TypeScript的类型转换接口

typescript-type-def是一个用于为Rust类型生成TypeScript类型定义的工具库。它可以帮助你生成一个包含类型定义的TypeScript模块，这些类型定义描述了Rust类型的JSON序列化格式。

主要用途

这个工具主要用于当你需要将Rust类型序列化为JSON（使用serde_json）并在TypeScript中使用时，可以自动生成对应的TypeScript类型定义，而不需要手动维护两套类型定义。

一个典型的使用场景是开发一个带有Rust后端和TypeScript前端的Web应用程序。如果前后端通信的数据在Rust中定义并使用serde_json进行编码/解码传输，你可以使用这个工具自动生成这些类型的TypeScript定义文件，以便在前端代码中安全使用。

特性

• json_value：为serde_json中的JSON值类型添加TypeDef实现

示例

简单示例

use serde::Serialize;
use typescript_type_def::{
    write_definition_file,
    DefinitionFileOptions,
    TypeDef,
};

#[derive(Serialize, TypeDef)]
struct Foo {
    a: usize,
    b: String,
}

let ts_module = {
    let mut buf = Vec::new();
    let options = DefinitionFileOptions::default();
    write_definition_file::<_, Foo>(&mut buf, options).unwrap();
    String::from_utf8(buf).unwrap()
};
assert_eq!(
    ts_module,
    r#"// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type Usize=number;
export type Foo={"a":types.Usize;"b":string;};
}
"#
);

let foo = Foo {
    a: 123,
    b: "hello".to_owned(),
};
let json = serde_json::to_string(&foo).unwrap();
// 这个JSON与上面的TypeScript类型定义匹配
assert_eq!(json, r#"{"a":123,"b":"hello"}"#);

大型代码库示例

当处理包含许多类型的大型代码库时，一个有用的模式是声明一个"API"类型别名，列出你想要为其生成定义的所有类型：

use serde::Serialize;
use typescript_type_def::{write_definition_file, TypeDef};

#[derive(Serialize, TypeDef)]
struct Foo {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Bar {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Baz {
    a: Qux,
}

#[derive(Serialize, TypeDef)]
struct Qux {
    a: String,
}

// 这个类型列出了我们想要为其生成定义的所有顶级类型
// 你不需要在这里列出API中的每种类型，只需要列出那些不会被其他类型引用的类型
// 注意Qux没有被提到，但仍然会被生成，因为它是Baz的依赖
type Api = (Foo, Bar, Baz);

let ts_module = {
    let mut buf = Vec::new();
    write_definition_file::<_, Api>(&mut buf, Default::default()).unwrap();
    String::from_utf8(buf).unwrap()
};
assert_eq!(
    ts_module,
    r#"// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type Foo={"a":string;};
export type Bar={"a":string;};
export type Qux={"a":string;};
export type Baz={"a":types.Qux;};
}
"#
);

运行时创建类型信息示例

你也可以使用write_definition_file_from_type_infos和运行时创建的TypeInfo引用列表来创建定义文件：

use serde::Serialize;
use typescript_type_def::{write_definition_file_from_type_infos, TypeDef};

#[derive(Serialize, TypeDef)]
struct Foo {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Bar {
    a: String,
}

#[derive(Serialize, TypeDef)]
struct Baz {
    a: Qux,
}

#[derive(Serialize, TypeDef)]
struct Qux {
    a: String,
}

// 这个列表包含我们想要为其生成定义的所有顶级类型的类型信息
// 你不需要在这里列出API中的每种类型，只需要列出那些不会被其他类型引用的类型
// 注意Qux没有被提到，但仍然会被生成，因为它是Baz的依赖
let api = vec![
    &Foo::INFO,
    &Bar::INFO,
    &Baz::INFO,
];

let ts_module = {
    let mut buf = Vec::new();
    write_definition_file_from_type_infos(
        &mut buf,
        Default::default(),
        &api,
    )
    .unwrap();
    String::from_utf8(buf).unwrap()
};
assert_eq!(
    ts_module,
    r#"// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type Foo={"a":string;};
export type Bar={"a":string;};
export type Qux={"a":string;};
export type Baz={"a":types.Qux;};
}
"#
);

完整示例Demo

下面是一个完整的示例，展示如何使用typescript-type-def生成TypeScript类型定义并在实际项目中使用：

// Cargo.toml
// [dependencies]
// serde = { version = "1.0", features = ["derive"] }
// serde_json = "1.0"
// typescript-type-def = "0.5"

use serde::Serialize;
use typescript_type_def::{write_definition_file, TypeDef};

// 定义Rust数据结构
#[derive(Debug, Serialize, TypeDef)]
struct User {
    id: u64,
    username: String,
    email: String,
    is_active: bool,
    roles: Vec<Role>,
}

#[derive(Debug, Serialize, TypeDef)]
struct Role {
    name: String,
    permissions: Vec<String>,
}

// 生成TypeScript类型定义
fn generate_ts_definitions() -> String {
    let mut buf = Vec::new();
    write_definition_file::<_, User>(&mut buf, Default::default()).unwrap();
    String::from_utf8(buf).unwrap()
}

fn main() {
    // 生成TypeScript类型定义
    let ts_def = generate_ts_definitions();
    println!("Generated TypeScript definitions:\n{}", ts_def);
    
    // 创建一个User实例并序列化为JSON
    let user = User {
        id: 123,
        username: "john_doe".to_string(),
        email: "john@example.com".to_string(),
        is_active: true,
        roles: vec![
            Role {
                name: "admin".to_string(),
                permissions: vec!["read".to_string(), "write".to_string()],
            },
            Role {
                name: "user".to_string(),
                permissions: vec!["read".to_string()],
            },
        ],
    };
    
    let json = serde_json::to_string_pretty(&user).unwrap();
    println!("\nSerialized JSON:\n{}", json);
}

生成的TypeScript定义如下：

// AUTO-GENERATED by typescript-type-def

export default types;
export namespace types{
export type U64=number;
export type Role={"name":string;"permissions":string[];};
export type User={"id":types.U64;"username":string;"email":string;"is_active":boolean;"roles":types.Role[];};
}

对应的JSON输出：

{
  "id": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "is_active": true,
  "roles": [
    {
      "name": "admin",
      "permissions": [
        "read",
        "write"
      ]
    },
    {
      "name": "user",
      "permissions": [
        "read"
      ]
    }
  ]
}

这个示例展示了如何：

1. 定义Rust数据结构并使用TypeDef派生宏
2. 自动生成对应的TypeScript类型定义
3. 将Rust数据结构序列化为JSON
4. 确保生成的JSON与TypeScript类型定义匹配

你可以将生成的TypeScript定义保存到前端项目的类型定义文件中，然后在TypeScript代码中使用这些类型，确保类型安全。