NestJS Swagger 中构造函数名称作为枚举默认值的处理问题

在 NestJS 项目中集成 Swagger 文档生成时，开发者可能会遇到一个关于枚举类型默认值的有趣问题。本文将深入分析这个问题的成因、影响以及解决方案。

问题现象

当开发者尝试在 DTO 类中使用 this.constructor.name 作为枚举类型的默认值时，Swagger 模块会错误地将其解析为字符串 "Function"，而不是预期的构造函数名称。例如：

enum SubjectEnum {
  SomeDto = 'SomeDto',
}

export class SomeDto {
  @ApiProperty({ enum: SubjectEnum, enumName: 'Subject' })
  readonly __caslSubjectType__: SubjectEnum = this.constructor
    .name as SubjectEnum;
}

生成的 OpenAPI 文档中会出现意外的默认值：

{
  "__caslSubjectType__": {
    "default": "Function",
    "allOf": [
      {
        "$ref": "#/components/schemas/Subject"
      }
    ]
  }
}

技术背景

这个问题涉及到几个关键的技术点：

1. TypeScript 的构造函数名称：this.constructor.name 在运行时确实会返回构造函数的名称，但在编译时和静态分析阶段，Swagger 模块无法确定其具体值。

2. Swagger 的静态分析：NestJS Swagger 模块在生成文档时主要进行静态分析，无法执行实际的代码逻辑来确定运行时值。

3. 默认值的处理机制：Swagger 对默认值的处理有一套特定的规则，当遇到无法确定的表达式时，会回退到某些默认行为。

问题根源

问题的核心在于 Swagger 的元数据提取机制。当它遇到 this.constructor.name 这样的动态表达式时：

1. 无法在静态分析阶段确定其实际值
2. 将整个表达式识别为 Function 类型
3. 因此生成了 "Function" 这个默认值

解决方案

目前有以下几种可行的解决方案：

1. 显式设置默认值为 null

@ApiProperty({
  enum: SubjectEnum,
  enumName: 'Subject',
  default: null
})

这种方法可以消除不正确的默认值，但可能不是最理想的解决方案。

2. 使用类装饰器统一处理

可以创建一个自定义装饰器来自动设置正确的类型名称：

function AutoSubjectType() {
  return function (constructor: Function) {
    const subjectType = constructor.name;
    Object.defineProperty(constructor.prototype, '__caslSubjectType__', {
      value: subjectType,
      enumerable: true,
      configurable: true
    });
  };
}

@AutoSubjectType()
export class SomeDto {
  @ApiProperty({ enum: SubjectEnum, enumName: 'Subject' })
  readonly __caslSubjectType__: SubjectEnum;
}

3. 等待官方修复

社区已经注意到这个问题，未来版本可能会提供更优雅的解决方案。开发者可以关注官方更新。

最佳实践建议

在处理类似场景时，建议：

1. 避免在装饰器元数据中使用动态表达式
2. 对于需要运行时确定的属性，考虑使用拦截器或中间件来处理
3. 对于文档生成，尽可能使用静态可分析的值

总结

这个问题展示了在静态文档生成和动态运行时行为之间的鸿沟。理解 Swagger 模块的工作原理有助于开发者设计出更健壮、更易于文档化的 API 结构。虽然目前有临时解决方案，但最佳实践是避免在装饰器元数据中使用动态表达式，转而使用更静态、更明确的方式定义 API 契约。