求Java MapStruct在TypeScript、NestJS及Node.js中的替代方案

一、现有同类TypeScript库 #

如果偏好MapStruct的注解式字段映射风格，以下几个库可以满足需求：

• class-transformer + class-validator：这是最贴近MapStruct用法的组合。通过@Transform、@Exclude等注解实现字段映射、忽略，还支持自定义转换逻辑。比如合并姓名的场景：

  import { Exclude, Transform, plainToInstance } from 'class-transformer';
  
  class UserEntity {
    firstName: string;
    lastName: string;
    password: string;
  }
  
  class UserDto {
    @Transform(({ obj }) => `${obj.firstName} ${obj.lastName}`)
    fullName: string;
  
    @Exclude()
    password: never;
  }
  
  // 使用示例
  const userEntity = { firstName: 'John', lastName: 'Doe', password: '123456' };
  const userDto = plainToInstance(UserDto, userEntity);
  

• auto-mapper-ts：专门面向对象映射的库，支持注解配置字段映射规则、自定义转换器，还能处理嵌套对象和数组映射，功能全面。
• mapper-ts：轻量级映射库，通过装饰器定义映射关系，语法简洁，适合中小型项目的简单映射场景。

二、自定义开发建议 #

如果现有库无法完全匹配你的需求，可以基于TypeScript的装饰器和元数据能力自行实现：

1. 核心前提 #

先在tsconfig.json中启用装饰器相关编译选项：

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

2. 关键实现步骤 #

• 定义映射装饰器：封装@MapField（指定源字段）、@ExcludeField（忽略字段）、@MapWith（自定义转换函数）三类装饰器，用元数据存储映射规则：

  // 装饰器定义
  export function MapField(sourceField?: string): PropertyDecorator {
    return (target, propertyKey) => {
      Reflect.defineMetadata(`map:source:${propertyKey}`, sourceField || propertyKey, target);
    };
  }
  
  export function ExcludeField(): PropertyDecorator {
    return (target, propertyKey) => {
      Reflect.defineMetadata(`map:exclude:${propertyKey}`, true, target);
    };
  }
  
  export function MapWith(transformer: (source: any) => any): PropertyDecorator {
    return (target, propertyKey) => {
      Reflect.defineMetadata(`map:transform:${propertyKey}`, transformer, target);
    };
  }
  

• 实现映射器核心逻辑：读取目标类的元数据，遍历字段并执行映射规则：

  export class CustomMapper {
    static map<T, U>(source: T, targetClass: new () => U): U {
      const target = new targetClass();
      const targetProto = Object.getPrototypeOf(target);
  
      Object.getOwnPropertyNames(targetProto).forEach(propertyKey => {
        // 跳过需要排除的字段
        const isExcluded = Reflect.getMetadata(`map:exclude:${propertyKey}`, targetProto);
        if (isExcluded) return;
  
        // 获取源字段名和转换函数
        const sourceField = Reflect.getMetadata(`map:source:${propertyKey}`, targetProto) || propertyKey;
        const transformer = Reflect.getMetadata(`map:transform:${propertyKey}`, targetProto);
  
        let value = (source as any)[sourceField];
        // 执行自定义转换逻辑
        if (transformer) value = transformer(source);
  
        (target as any)[propertyKey] = value;
      });
  
      return target;
    }
  }
  

• 使用示例：

  class UserEntity {
    firstName: string;
    lastName: string;
    password: string;
  }
  
  class UserDto {
    @MapWith((source: UserEntity) => `${source.firstName} ${source.lastName}`)
    fullName: string;
  
    @ExcludeField()
    password: never;
  }
  
  const user = new UserEntity();
  user.firstName = 'Jane';
  user.lastName = 'Smith';
  user.password = 'abc123';
  
  const dto = CustomMapper.map(user, UserDto);
  // dto.fullName = 'Jane Smith'，password字段被忽略
  

• 优化方向：后续可以扩展支持嵌套对象映射、数组批量映射，还可以通过编译时生成映射函数的方式，避免运行时反射带来的性能开销，同时添加类型校验确保映射的类型安全。

内容的提问来源于stack exchange，提问作者Vimaire