4、统一错误码体系设计：租户级、服务级、系统级错误码分层规范

在多租户 SaaS 鉴权拦截链路中，错误码的混乱是导致故障定位慢、熔断策略误判、租户隔离失效的首要原因。本章定义一套三层错误码分层规范，将错误码按影响范围划分为租户级、服务级、系统级，并给出编码规则、分段定义与熔断映射关系。

4.1 三层错误码架构总览

下图展示了错误码在鉴权拦截链路中的分层归属与传递路径：

4.2 错误码编码规范

错误码采用 层级前缀 + 数字分段 的固定格式，共 7 位字符：

格式：[层级前缀]-[三位数字]
层级前缀：TNT（租户级） | SRV（服务级） | SYS（系统级）
示例：TNT-301、SRV-101、SYS-001

4.3 鉴权拦截链路错误码明细

针对鉴权拦截链路的核心节点，定义以下标准化错误码：

4.4 错误码与熔断降级的映射关系

熔断降级组件通过错误码前缀自动匹配熔断策略，无需硬编码业务逻辑：

// 伪代码：熔断决策引擎
function decideCircuitBreaker(errorCode, tenantId) {
    if (errorCode.startsWith("SYS-")) {
        return globalCircuitBreaker.trip();          // 全局熔断
    } else if (errorCode.startsWith("SRV-")) {
        return serviceDegrader.degrade();            // 服务降级
    } else if (errorCode.startsWith("TNT-")) {
        return tenantCircuitBreaker.trip(tenantId);  // 租户级熔断
    } else {
        return unknownErrorHandler(errorCode);
    }
}

4.5 错误码传递与日志规范

错误码在鉴权拦截链路中必须透传，并在日志中按层级聚合：

• 请求头透传：在 HTTP 响应头 X-Error-Code 中携带错误码，供网关和客户端识别。
• 日志标签：日志输出时使用 [TNT]、[SRV]、[SYS] 标签，便于监控系统按层级告警。
• 聚合指标：Prometheus 指标 saas_error_total{level="tenant", code="TNT-301"} 按层级和错误码聚合。

// 日志输出示例
2025-03-20 10:15:32 [ERROR] [TNT] [tenantId=acme-corp] TNT-301 租户API配额超限
2025-03-20 10:15:33 [WARN]  [SRV] [service=auth] SRV-101 鉴权服务超时，触发降级
2025-03-20 10:15:34 [CRIT] [SYS] [cluster=redis] SYS-001 缓存集群不可用，全局熔断

4.6 错误码扩展与版本管理

错误码体系需要支持版本化扩展，避免因新增错误码导致熔断策略混乱：