Nest Swagger泛型类属性定义问题：分页orderBy字段未显示

一、orderBy在Swagger UI不显示的核心原因 #

TypeScript泛型在编译阶段会被类型擦除，运行时不存在keyof T的具体类型信息。而NestJS的Swagger模块（@nestjs/swagger）依赖运行时元数据生成API文档，无法从泛型定义中推断出orderBy的合法值或类型，因此不会将该字段纳入Swagger的查询参数列表。

你尝试的IsRecord装饰器完全不匹配orderBy的场景：orderBy是单个字符串类型（对应T的键名），但IsRecord是用来验证键为字符串、值为数组的对象结构的，两者类型不兼容，自然无法解决问题，甚至会导致额外的验证错误。

另外，你提到@IsRecord的object为空，这是因为属性装饰器的第一个参数是类的原型对象，但如果将该装饰器应用在泛型类的属性上，且未实例化具体的泛型实现类时，可能会出现元数据获取异常，但核心还是这个装饰器不适用于当前场景。

二、正确解决orderBy的Swagger显示与验证问题 #

方案1：在具体DTO类中显式声明orderBy #

由于泛型擦除，必须在继承BasePagination的具体DTO中，明确指定orderBy的合法值，并通过@ApiProperty告知Swagger：

// 示例：User实体类
class User {
  id: number;
  name: string;
  email: string;
}

// 具体的分页DTO
export class UserPaginationDto extends BasePagination<User> {
  @ApiProperty({ enum: ['id', 'name', 'email'] }) // 显式列出User的键
  @IsIn(['id', 'name', 'email']) // 验证传入值是否合法
  orderBy: keyof User;
}

方案2：封装通用装饰器简化重复代码 #

如果需要多个DTO复用逻辑，可以封装一个装饰器，动态传入目标类的键列表：

import { ApiProperty } from '@nestjs/swagger';
import { IsIn } from 'class-validator';

export function OrderByKeys<T>(keys: Array<keyof T>) {
  return function (target: any, propertyKey: string) {
    ApiProperty({ enum: keys })(target, propertyKey);
    IsIn(keys)(target, propertyKey);
  };
}

// 使用示例
export class UserPaginationDto extends BasePagination<User> {
  @OrderByKeys<User>(['id', 'name', 'email'])
  orderBy: keyof User;
}

方案3：利用TypeScript类型工具自动提取键（需配合代码生成） #

如果想避免手动写键名，可以用TypeScript的keyof结合代码生成工具（如ts-morph），在编译阶段自动生成具体DTO的orderBy枚举，但这种方式复杂度较高，适合大型项目。

三、关于IsRecord装饰器的修正（若仍需使用） #

如果你的其他字段需要验证“键为字符串、值为数组”的对象结构，修正装饰器的验证逻辑，并确保应用在对象类型的属性上：

import { registerDecorator, ValidationOptions, ValidationArguments } from 'class-validator';
import { isObject } from 'class-validator';

export const IsRecord = (validationOptions?: ValidationOptions) => {
  return function (object: any, propertyName: string) {
    registerDecorator({
      name: 'IsRecord',
      target: object.constructor,
      propertyName: propertyName,
      constraints: [],
      options: {
        message: '必须是键为字符串、值为数组的对象',
        ...validationOptions,
      },
      validator: {
        validate(value: unknown, _args: ValidationArguments) {
          if (!isObject(value)) return false;
          // 允许空对象
          if (Object.keys(value).length === 0) return true;
          return Object.entries(value).every(([key, val]) => {
            return typeof key === 'string' && Array.isArray(val);
          });
        },
      },
    });
  };
};

// 正确使用场景：对象类型的属性
export class SomeDto {
  @IsRecord()
  filters: Record<string, any[]>;
}

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