4. 错误码分类体系：系统级错误码、业务级错误码、第三方依赖错误码、安全错误码

在 BFF 层落地错误码规范时，最核心的决策是建立一套可扩展、可归因的分类体系。错误码不能是扁平的数字列表，而必须按照错误的来源与性质进行分层。本章将错误码划分为四大类别：系统级、业务级、第三方依赖级和安全级，每一类对应不同的处理策略、监控指标与告警阈值。

4.1 分类总览与编码结构

推荐采用 “字母前缀 + 数字分段” 的编码方式，使分类信息直接编码在错误码字符串中。以下为通用编码结构：

这种编码结构在日志聚合、监控告警和 API 响应体中都能快速过滤。例如，在 Grafana 中通过 error_code =~ "SYS-.*" 即可筛选所有系统级故障。

4.2 系统级错误码（SYS）

系统级错误码表示 BFF 层自身基础设施或运行环境出现故障。这类错误通常需要运维或平台团队介入处理，与业务逻辑无关。典型场景包括：

• 连接资源失败：Redis 连接池耗尽、数据库连接超时、消息队列不可用。
• 内部处理异常：JSON 序列化/反序列化失败、模板渲染错误、文件读写异常。
• 资源限制：请求体超过大小限制、并发数超过线程池阈值、内存分配失败。
• 配置错误：关键配置项缺失、环境变量未设置、路由规则解析失败。

// 系统级错误码枚举示例（TypeScript）
export enum SysErrorCode {
  DB_CONNECTION_FAILED = 'SYS-1001',
  REDIS_POOL_EXHAUSTED = 'SYS-1002',
  REQUEST_BODY_TOO_LARGE = 'SYS-1003',
  INTERNAL_SERIALIZE_ERROR = 'SYS-1004',
  CONFIG_MISSING = 'SYS-1005',
}

4.3 业务级错误码（BIZ）

业务级错误码对应业务规则校验失败或用户操作不符合预期。这类错误是 BFF 层最常处理的类型，需要向前端返回友好的提示信息，且不应触发运维告警。

4.4 第三方依赖错误码（DEP）

BFF 作为聚合层，高度依赖下游微服务或外部 API。第三方依赖错误码专门用于标识下游服务返回的错误，帮助快速区分“BFF 自身问题”与“下游问题”。

DEP 错误码的设计要点：

• 透传 vs 映射：对于下游返回的错误码，BFF 可以选择直接透传（如 DEP-3000 + 原始错误码），也可以映射为统一的 BFF 错误码。
• 熔断与降级：当 DEP 错误码连续出现时，应触发熔断器打开，避免雪崩。
• 超时与重试：DEP-3010 表示下游超时，BFF 应记录重试次数和耗时。

// 第三方依赖错误码映射示例
public class DepErrorMapper {
  private static final Map<String, String> MAPPING = Map.of(
    "USER_SERVICE_TIMEOUT", "DEP-3010",
    "ORDER_SERVICE_UNAVAILABLE", "DEP-3020",
    "PAYMENT_SERVICE_INVALID_RESPONSE", "DEP-3030"
  );

  public static String map(String downstreamCode) {
    return MAPPING.getOrDefault(downstreamCode, "DEP-3999");
  }
}

4.5 安全错误码（SEC）

安全错误码覆盖认证、授权、防篡改、防重放等安全相关场景。这类错误需要与安全风控系统联动，且通常需要记录详细的审计日志。

4.6 分类体系在异常处理框架中的落地

在 BFF 的异常处理框架中，错误码分类直接决定了异常类的继承结构和处理器的路由逻辑。以下是一个基于分类的异常类层次设计：

通过这种分类体系，BFF 的异常处理框架可以实现：

• 差异化处理：系统级异常自动触发告警和熔断；业务级异常仅返回提示；依赖级异常触发重试或降级；安全级异常记录审计日志。
• 统一响应格式：所有异常最终输出为包含 category 字段的 JSON 响应，前端可根据分类决定是否展示错误详情。
• 监控聚合：在 Prometheus 中按 category 标签聚合错误率，设置不同的告警阈值。