NestJS同路由下HEAD与GET请求路由异常问题排查

问题现象 #

在RESTful API设计中，我们通过HEAD请求校验实体是否存在，但使用NestJS 10.4.4时出现异常：客户端发送同路由的HEAD请求（如HEAD /api/test/:id）会被错误路由到对应的GET控制器方法。经排查发现，该问题与控制器内方法的定义顺序直接相关：

• 若HEAD方法写在GET方法之后，HEAD请求会被GET方法拦截
• 若HEAD方法写在GET方法之前，请求能正常匹配到HEAD方法

原因分析 #

NestJS的路由匹配机制在处理同路径的不同HTTP方法时，会按照控制器中方法的定义顺序依次匹配。结合HTTP规范中HEAD请求可降级使用GET逻辑（仅返回响应头）的特性，当GET方法先被定义时，NestJS会优先匹配到先声明的GET方法，导致HEAD请求被错误拦截。

解决方案 #

确保同路由下，被@Head()装饰器修饰的方法定义在@Get()方法之前，让NestJS优先匹配HEAD请求的处理逻辑。

正确代码示例 #

// 同路由下HEAD方法必须放在GET方法之前
@Head(':id')  // 校验实体是否存在
async hasOne(@Res() response, @Param('id') id): Promise<any> {
  // 执行实体存在性校验逻辑
  const isExist = await checkEntityExists(id);
  response.sendStatus(isExist ? 200 : 404);
}

@Get(':id') // 获取单个实体详情
getOne(@Param('id') id): Promise<any> {
  // 执行获取实体数据逻辑
  return fetchEntityById(id);
}

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