Nest.js中ObjectIdPipe在查询参数未传入时失效的问题

问题根源 #

Nest.js 默认仅当查询参数存在（哪怕值为null/undefined/空字符串）时才会调用对应的管道。如果请求中完全没有该参数，管道不会被执行，导致参数无法按预期处理为undefined。

解决方案 #

方案一：修改管道与查询参数配置 #

通过在@Query装饰器中设置required: false，强制Nest将undefined传入管道处理，同时调整管道兼容undefined输入：

@Get()
findAll(
  @Query('foreignId', ObjectIdPipe, { required: false }) foreignId?: Types.ObjectId | undefined,
) {
  console.log(foreignId); // 参数不存在时输出undefined，有效时输出ObjectId，无效值时输出undefined
  return this.booksService.findBooks({ foreignId });
}

@Injectable()
export class ObjectIdPipe implements PipeTransform<string | undefined, Types.ObjectId | undefined> {
  transform(value: string | undefined, metadata: ArgumentMetadata): Types.ObjectId | undefined {
    console.log("Original value:", value);
    // 处理undefined、null、空字符串或无效ObjectId的情况
    if (!value || !isObjectIdOrHexString(value)) {
      return undefined;
    }
    return new Types.ObjectId(value);
  }
}

方案二：封装自定义装饰器（多接口复用） #

如果多个接口都需要该逻辑，封装自定义装饰器避免重复配置：

// object-id-query.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { Types, isObjectIdOrHexString } from 'mongoose';

export const ObjectIdQuery = createParamDecorator(
  (paramName: string, ctx: ExecutionContext): Types.ObjectId | undefined => {
    const request = ctx.switchToHttp().getRequest();
    const value = request.query[paramName];
    if (value && isObjectIdOrHexString(value)) {
      return new Types.ObjectId(value);
    }
    return undefined;
  },
);

// 控制器中使用
@Get()
findAll(
  @ObjectIdQuery('foreignId') foreignId?: Types.ObjectId | undefined,
) {
  console.log(foreignId);
  return this.booksService.findBooks({ foreignId });
}

方案三：添加无效格式校验（可选） #

如果需要对无效的ObjectId格式返回错误，修改管道抛出异常：

import { BadRequestException } from '@nestjs/common';

@Injectable()
export class ObjectIdPipe implements PipeTransform<string | undefined, Types.ObjectId | undefined> {
  transform(value: string | undefined, metadata: ArgumentMetadata): Types.ObjectId | undefined {
    if (!value) {
      return undefined;
    }
    if (isObjectIdOrHexString(value)) {
      return new Types.ObjectId(value);
    }
    // 无效格式时抛出400错误
    throw new BadRequestException(`Invalid ObjectId format for ${metadata.data}`);
  }
}

内容的提问来源于stack exchange，提问作者Adora González