TypeStack/class-transformer 基础使用指南

TypeStack/class-transformer 基础使用指南

class-transformer Decorator-based transformation, serialization, and deserialization between objects and classes. 项目地址: https://gitcode.com/gh_mirrors/cl/class-transformer

前言

在现代TypeScript开发中，对象转换是一个常见需求。TypeStack/class-transformer库提供了一套优雅的解决方案，通过装饰器模式实现了普通对象与类实例之间的双向转换。本文将详细介绍该库的基础使用方法。

核心转换函数

1. plainToInstance

plainToInstance函数用于将普通JavaScript对象转换为指定类的实例。这个转换过程会应用类定义中通过装饰器注册的元数据。

import { plainToInstance } from 'class-transformer';

const user = plainToInstance(User, userJson);

2. instanceToPlain

instanceToPlain函数则执行相反的操作，将已知的类实例转换回普通JavaScript对象。

import { instanceToPlain } from 'class-transformer';

const plainUser = instanceToPlain(userInstance);

核心装饰器

1. @Expose

@Expose装饰器用于指定属性在转换过程中的行为：

@Expose()
name: string;

可以配置选项：

• name - 指定转换后的属性名
• groups - 定义分组，用于选择性转换
• since - 版本控制，指定从哪个版本开始暴露
• until - 版本控制，指定到哪个版本为止暴露

2. @Exclude

@Exclude装饰器标记属性在转换过程中被忽略：

@Exclude()
password: string;

3. @Transform

@Transform装饰器允许自定义转换逻辑：

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

4. @Type

@Type装饰器显式指定属性的类型：

@Type(() => Role)
roles: Role[];

重要注意事项

1. 必须装饰所有属性：每个属性都必须使用@Expose或@Exclude装饰器进行标记。

2. 构造函数限制：转换过程中会调用目标类型的空构造函数。如果类型需要特殊初始化，应使用@Transform装饰器手动创建实例。

3. 嵌套对象处理：对于嵌套对象，必须使用@Type装饰器指定其类型，否则转换器无法正确处理。

最佳实践

1. 明确转换策略：在设计类时，应明确哪些属性需要转换，哪些需要排除。

2. 版本控制：利用@Expose的since和until选项实现API版本兼容。

3. 分组转换：使用groups选项实现不同场景下的选择性转换。

4. 性能考虑：对于大型对象或频繁转换场景，考虑缓存转换元数据。

示例代码

import { Expose, Type, Transform } from 'class-transformer';

class User {
  @Expose()
  id: number;

  @Expose({ name: 'userName' })
  name: string;

  @Exclude()
  password: string;

  @Type(() => Date)
  @Transform(({ value }) => new Date(value))
  registrationDate: Date;

  @Type(() => Role)
  roles: Role[];
}

class Role {
  @Expose()
  name: string;
}

// 使用示例
const userJson = {
  id: 1,
  userName: 'john',
  password: 'secret',
  registrationDate: '2023-01-01',
  roles: [{ name: 'admin' }]
};

const user = plainToInstance(User, userJson);
const plainUser = instanceToPlain(user);

通过掌握这些基础用法，开发者可以高效地在普通对象和类实例之间进行转换，为应用程序提供更强大的类型安全和灵活性。

class-transformer Decorator-based transformation, serialization, and deserialization between objects and classes. 项目地址: https://gitcode.com/gh_mirrors/cl/class-transformer