在自定义防腐网关中，不能直接在顶层async函数用try-catch统一转标准提示契约，而应在请求发起层（如httpClient调用处）分层拦截错误，按网络、响应、业务三类动态识别并构造含code/message/level/retryable字段的标准契约，避免丢失堆栈、误统错类型或耦合业务逻辑。
在自定义防腐网关中，不能直接在顶层 async 函数里用 try-catch 包裹 await 调用并统一转标准提示契约——因为网关通常运行在中间件或代理层，错误可能来自下游服务、序列化、超时、认证失败等不同环节，需分层拦截、分类识别、动态构造契约。
明确错误捕获的边界位置
防腐网关的核心是“隔离外部不确定性”，所以 try-catch 不应放在业务逻辑层，而应落在网关实际发起请求的那一刻（如 axios/fetch 封装层或适配器层）：
- 在网关转发前做参数校验，抛出
ValidationError类错误，由统一异常处理器捕获 - 在真正调用下游接口时（例如
await httpClient.request(...)），用 try-catch 包住这一行 - 避免在路由入口或控制器里写 await + try-catch —— 这会把网关职责和业务逻辑耦合
动态识别错误类型并映射标准契约字段
网络错误不是单一类型：ECONNREFUSED、ETIMEDOUT、4xx/5xx 响应、JSON 解析失败、下游返回非标准 error body……需按特征提取关键信息：
- 对 AxiosError：检查
error.code（如 'ECONNABORTED'）、error.response?.status、error.request是否为空 - 对 fetch：区分
err.name === 'AbortError'（超时）、err instanceof TypeError && err.message.includes('failed to fetch')（网络中断） - 对响应体：即使 status >= 200，也要检查下游是否返回了
{ code: 5001, message: '库存不足' }这类业务错误，此时不应视为“成功”
构造可扩展的标准提示契约
标准契约不是固定字符串，而是带语义的结构体，便于前端统一处理（如 toast、log、重试判断）：
- 推荐格式：
{ code: string, message: string, level: 'error' | 'warn' | 'info', traceId?: string, retryable?: boolean } - code 不用 HTTP 状态码，而用网关定义的领域码（如
'GATEWAY_TIMEOUT'、'SERVICE_UNAVAILABLE'、'DOWNSTREAM_INVALID_RESP'） - message 应脱敏且用户友好（避免暴露下游服务名、堆栈），但保留必要上下文（如“支付服务暂不可用”而非“调用 pay-svc 失败”）
- 根据错误类型自动设
retryable：超时/连接拒绝可重试；400/401 一般不重试；500 需结合下游 header 中的X-Retry-After判断
避免常见陷阱
看似简单，实操中容易踩坑：
- 不要在 catch 里直接 throw 新 Error —— 会丢失原始堆栈和类型信息，改用包装错误：
throw new GatewayError(originalErr, { code: '...', message: '...' }) - 不要把所有错误都转成 500 —— 防腐网关的价值正在于区分“我挂了”和“它挂了”，前者需告警，后者只需降级提示
- 日志记录要包含原始 error + 标准契约 + 请求标识（如 requestId），否则排查时无法反查上下文
- 如果网关支持多协议（HTTP/gRPC/WebSocket），每种协议的错误形态不同，需各自实现适配逻辑，再统一归一为标准契约
