NestJS结合Axios搭建BFF时如何自动透传后端请求错误状态码

算力阿峰

2026-8-28

方案可行性结论

你设想的全局Axios异常过滤器方案完全可行，是BFF场景下透传下游服务状态码的常规实现，比逐个接口手动捕获异常的维护成本低很多，完全能解决当前任意Axios请求失败默认返回500的问题。

基础实现参考

实现时不用挨个映射Nest内置的异常类（比如401对应UnauthorizedException、404对应NotFoundException），Nest原生HttpException支持直接传入自定义状态码，直接透传下游返回的状态和响应体即可，省掉维护状态码映射表的额外成本。
核心逻辑注意先识别Axios异常特征：Axios抛出的错误会自带isAxiosError: true标记，有下游响应的错误会挂载error.response属性，包含状态码、响应体、响应头等信息。
最小可用过滤器代码如下：

import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
import { Response } from 'express';
import { AxiosError } from 'axios';

// 只捕获Axios抛出的异常，不干扰其他业务异常、Nest框架内置异常的处理
@Catch(AxiosError)
export class AxiosExceptionFilter implements ExceptionFilter {
  catch(exception: AxiosError, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    // 只有下游服务正常返回了错误响应的场景才透传状态码
    if (exception.response) {
      const { status, data } = exception.response;
      response.status(status).json(data);
      return;
    }

    // 无响应的场景（超时、DNS解析失败、网络断开等）统一返回服务端错误
    response.status(500).json({
      code: 500,
      message: '下游服务调用失败',
      detail: exception.message
    });
  }
}

全局注册后即可生效，在main.ts中加入：

app.useGlobalFilters(new AxiosExceptionFilter());

如果需要依赖注入，也可以在根模块通过APP_FILTER令牌注册。

可选的更优实现

根据业务粒度需求，你也可以选以下两种方案，灵活度比纯全局过滤器更高：

Axios实例拦截器统一转换异常
直接在初始化Axios实例（包括Nest HttpModule、第三方Axios封装模块注册的实例）时添加响应拦截器，在拦截器内直接把非2xx响应转为Nest识别的HttpException。这种方式更靠近请求发起层，可以针对不同下游服务配置不同规则：比如用户中心接口全量透传状态码，支付接口只透传4xx状态码、5xx统一降级为自定义错误，粒度控制更精准。
拦截器示例代码：
```
import { HttpException } from '@nestjs/common';
import axios from 'axios';

// 针对用户中心服务的Axios实例配置全透传规则
const userServiceAxios = axios.create({ baseURL: 'http://user-service-inner' });
userServiceAxios.interceptors.response.use(
  (res) => res.data,
  (error) => {
    if (error.response) {
      throw new HttpException(error.response.data, error.response.status);
    }
    throw new HttpException('用户服务暂不可用', 503);
  }
);
```
这种方式抛出的是标准Nest HttpException，可以直接被项目内已有的统一响应、Swagger、日志拦截器等组件识别，不需要额外适配。
全局默认透传+局部特殊处理
用全局过滤器做默认的状态码透传逻辑，遇到需要特殊处理的场景（比如某个非核心下游接口404时要返回兜底数据，不能直接透传错误），直接在对应业务代码里加try/catch捕获Axios异常走自定义逻辑即可，不会和全局过滤器冲突，兼顾低维护成本和灵活度。

实现注意事项

透传响应时注意过滤下游返回的敏感头信息，比如内部服务标识、内网Set-Cookie等，避免泄露内部架构信息。
严格区分「下游返回错误响应」和「请求未到达下游」的场景，后者（超时、网络断开、证书错误等）没有response对象，不要硬透传不存在的状态码，按服务端错误统一处理即可。
如果是聚合类BFF接口（单接口并行调用多个下游），要按业务优先级处理异常：核心下游报错直接透传，非核心下游报错可以做降级处理，不要因为次要接口故障直接打回整个请求。

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