使用泛型类时NestJS Swagger出现循环依赖问题求助

问题根源 #

Swagger的Schema解析工厂无法正确处理未绑定具体类型的泛型类，当ApiCollectionResponse<T>的records字段为T[]且T为Object时，会触发递归解析逻辑，导致循环依赖检测报错。

解决方法 #

1. 创建泛型类的具体子类（推荐）

为每个需要返回的实体类型创建对应的响应子类，明确绑定泛型参数：

// 假设你的实体类是Aggregate
export class AggregateCollectionResponse extends ApiCollectionResponse<Aggregate> {}

然后在控制器的@ApiResponse中使用这个子类，并通过懒加载函数避免依赖问题：

@Get()
@ApiResponse({
  status: HttpStatus.OK,
  description: '获取数据集合',
  type: () => AggregateCollectionResponse, // 懒加载子类
})
async list(@Query() query?: ProcessedQuery): Promise<AggregateCollectionResponse> {
  return this.service.list(query);
}

注意：移除isArray: true，因为返回的是单个ApiCollectionResponse对象，而非数组，records字段才是数组类型。

2. 在泛型类中用@ApiProperty指定具体类型

如果不需要创建多个子类，可以直接在泛型类的records字段上用@ApiProperty指定具体的实体类型：

import { ApiProperty } from '@nestjs/swagger';
import { Aggregate } from './aggregate.entity'; // 引入你的实体类

export class ApiCollectionResponse<T> {
  @ApiProperty({ type: () => Aggregate, isArray: true }) // 明确指定T的具体类型
  records?: T[];

  @ApiProperty()
  count: number;

  @ApiProperty({ required: false })
  next?: string;

  constructor(typeAsObject: new (Response) => T, Response: any, query: Record<string, string> = {}) {
    this.records = Response.map((item) => new typeAsObject(item)) || [];
    this.count = this.records.length;
    this.next = Response.next;
  }
}

控制器中保持懒加载配置：

@ApiResponse({
  status: HttpStatus.OK,
  description: '获取数据集合',
  type: () => ApiCollectionResponse,
})

这种方法的局限性是泛型类被固定为某一种实体类型，适合单一场景。

3. 手动定义Swagger Schema

如果上述方法不适用，可以直接在@ApiResponse中用schema字段手动定义响应结构：

@ApiResponse({
  status: HttpStatus.OK,
  description: '获取数据集合',
  schema: {
    type: 'object',
    properties: {
      records: {
        type: 'array',
        items: { $ref: '#/components/schemas/Aggregate' } // 引用实体的Swagger Schema
      },
      count: { type: 'number' },
      next: { type: 'string', nullable: true }
    }
  }
})

这种方式完全绕过泛型类的自动解析，适合复杂或特殊的响应结构定义。

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