3. HTTP 状态码在 BFF 中的正确使用：2xx/3xx/4xx/5xx 状态码语义、自定义业务状态码设计、状态码映射规范

BFF 作为前端与后端微服务之间的“翻译层”，HTTP 状态码的使用不能简单透传后端原始状态码，也不能全部返回 200 然后在响应体中塞错误码。正确的做法是：BFF 根据前端消费习惯重新映射状态码，同时保留业务语义。本章从标准语义、自定义设计、映射规范三个维度展开。

3.1 HTTP 标准状态码在 BFF 中的语义

BFF 应严格区分“通信状态”与“业务状态”。通信状态由 HTTP 状态码表达，业务状态由响应体中的自定义码表达。下表列出 BFF 中最常用的标准状态码及其语义边界：

3.2 自定义业务状态码设计

HTTP 状态码只有几十个，无法表达千差万别的业务语义。因此 BFF 必须在响应体中携带自定义业务状态码。设计时遵循“三段式”结构：

// 响应体统一格式
{
  "code": 100200,       // 业务状态码
  "message": "success", // 人类可读描述
  "data": { ... },      // 业务数据
  "traceId": "abc123"   // 链路追踪 ID
}

三段式编码规则：

• 第一位（1位）：错误来源。1=系统级，2=业务级，3=安全级，4=第三方依赖。
• 第二位（2位）：模块编号。01=用户，02=订单，03=支付，04=商品，99=通用。
• 第三位（3位）：具体错误编号。从 001 开始递增，预留 100 个空位。

3.3 状态码映射规范

BFF 从后端微服务获取响应后，需要执行“三层映射”才能返回给前端。映射流程如下图所示：

映射规范总结为四条硬规则：

1. 通信错误透传：后端返回 4xx 客户端错误（401/403/404/429），BFF 直接透传对应 HTTP 状态码，不修改状态码分类。
2. 服务端错误降级：后端返回 5xx，BFF 必须转换为 502/503/504，或降级为 200 + 业务码 400xxx，绝不允许透传 500。
3. 业务错误统一为 200：后端业务逻辑异常（如“订单已取消”“库存不足”），BFF 统一返回 HTTP 200，业务语义由自定义码表达。
4. BFF 自身异常独立编码：BFF 限流、熔断、超时等自身故障，使用 429/503/504 + 3xxxx 业务码，与后端错误隔离。

3.4 映射实现示例（Node.js）

// BFF 状态码映射中间件（Node.js + Express 示例）
function statusCodeMapper(req, res, next) {
  // 保存原始 res.json 方法
  const originalJson = res.json.bind(res);

  res.json = function (body) {
    // 如果响应体已有自定义格式，不重复包装
    if (body && typeof body.code === 'number') {
      return originalJson(body);
    }

    // 根据 HTTP 状态码决定映射策略
    const status = res.statusCode;

    if (status >= 200 && status < 300) {
      // 成功：包装为 100200
      return originalJson({
        code: 100200,
        message: 'success',
        data: body,
        traceId: req.traceId
      });
    }

    if (status >= 400 && status < 500) {
      // 客户端错误：透传状态码，业务码映射
      const codeMap = {
        400: 100400,
        401: 100401,
        403: 100403,
        404: 100404,
        429: 300001
      };
      return originalJson({
        code: codeMap[status] || 100400,
        message: body?.message || '客户端请求错误',
        data: null,
        traceId: req.traceId
      });
    }

    if (status >= 500) {
      // 服务端错误：降级为 502/503/504，业务码 4xxxx
      const downgradeStatus = status === 504 ? 504 : 502;
      res.status(downgradeStatus);
      return originalJson({
        code: 400001,
        message: '服务暂时不可用，请稍后重试',
        data: null,
        traceId: req.traceId
      });
    }

    return originalJson(body);
  };

  next();
}

3.5 状态码映射规范检查清单

通过以上规范，BFF 能够为前端提供可预测、可枚举、可自动化处理的错误响应体系。前端团队只需维护一张业务码映射表，即可覆盖所有异常场景，无需关心后端微服务的具体实现细节。