class-transformer项目基础使用指南：对象与类的双向转换

class-transformer项目基础使用指南：对象与类的双向转换

class-transformer 项目地址: https://gitcode.com/gh_mirrors/cla/class-transformer

前言

在现代JavaScript/TypeScript开发中，我们经常需要在普通对象（Plain Object）和类实例（Class Instance）之间进行转换。class-transformer库提供了优雅的解决方案，通过装饰器（Decorators）实现对象与类实例之间的双向转换。本文将详细介绍该库的基础使用方法。

核心转换函数

class-transformer提供了两个核心转换函数：

1. plainToInstance - 将普通对象转换为指定类的实例

   • 用途：常用于将API返回的JSON数据转换为具有方法和业务逻辑的类实例
   • 特点：自动处理嵌套对象的转换，支持自定义转换规则

2. instanceToPlain - 将类实例转换为普通对象

   • 用途：常用于将类实例序列化为JSON发送到API
   • 特点：保留类结构信息，支持选择性暴露属性

核心装饰器详解

1. @Expose 装饰器

@Expose用于指定属性在转换过程中的暴露方式：

class User {
  @Expose()
  id: number;
  
  @Expose({ name: 'userName' })
  name: string;
}

• 基本用法：标记属性需要被转换
• 高级配置：可通过name选项指定转换后的属性名
• 注意事项：必须为每个需要转换的属性添加此装饰器

2. @Exclude 装饰器

@Exclude用于标记属性不参与转换：

class User {
  @Expose()
  id: number;
  
  @Exclude()
  password: string;
}

• 使用场景：敏感信息（如密码）、临时属性等
• 特点：转换时会完全忽略该属性

3. @Type 装饰器

@Type用于明确指定属性的类型：

class Photo {
  @Expose()
  url: string;
}

class User {
  @Expose()
  @Type(() => Photo)
  photos: Photo[];
}

• 作用：解决嵌套对象的类型识别问题
• 必要性：TypeScript类型信息在运行时不可用，必须显式声明
• 支持：所有基本类型和自定义类

4. @Transform 装饰器

@Transform用于自定义转换逻辑：

class User {
  @Expose()
  @Transform(({ value }) => new Date(value))
  birthDate: Date;
}

• 应用场景：
  • 特殊类型的实例化（如Date）
  • 数据格式转换
  • 复杂计算属性
• 回调参数：接收原始值，返回转换后的值

重要注意事项

1. 装饰器必须性：所有属性必须明确标记@Expose或@Exclude，否则转换时会被忽略

2. 构造函数限制：转换时会调用目标类的空构造函数，因此：

   • 确保类有无参构造函数
   • 对于需要特殊初始化的类，使用@Transform手动处理

3. 循环引用处理：默认不支持循环引用，需要额外配置

4. 性能考虑：大量数据转换时，应考虑缓存转换策略

实际应用示例

场景1：API响应转换为类实例

const userJson = '{"id":1,"name":"John","photos":[{"url":"photo1.jpg"}]}';
const user = plainToInstance(User, JSON.parse(userJson));

场景2：类实例序列化为JSON

const user = new User();
user.id = 1;
user.name = "John";
const userJson = JSON.stringify(instanceToPlain(user));

最佳实践建议

1. 保持一致性：团队应统一装饰器使用风格
2. 文档注释：为每个装饰器添加注释说明转换规则
3. 类型安全：结合TypeScript类型检查确保转换安全
4. 单元测试：为复杂转换逻辑编写测试用例

通过合理使用class-transformer，开发者可以简化对象与类实例之间的转换工作，使代码更加清晰、类型更加安全。

class-transformer 项目地址: https://gitcode.com/gh_mirrors/cla/class-transformer