中转站返回的 HTTP 错误码需要先按传输层故障处理,不能直接等同于上游业务抛出的异常。常见如 502 Bad Gateway、504 Gateway Timeout、429 Too Many Requests,这些状态码表示网关连接上游失败、上游响应超时或网关限流命中,业务请求可能根本没有到达业务代码,也可能已经处理但结果没有透传回来。如果服务端统一拿 HTTP 状态码作为业务判断依据,会导致告警分错组、重试打空甚至重复处理。处理第一步是分清错误码落在链路哪一层。
通常可以从三个点做初步确认。第一,响应头。网关一般会透传自定义字段,例如 X-Upstream-Status、X-Gateway-Error、X-Cache-Status,这些字段标明结果来自上游还是网关本身。第二,响应体。网关的通用错误结构一般带固定 error.code、request_id,业务错误结构常带业务模块的 code、message。第三,链路日志。用网关返回的 traceId 或 requestId 检索网关日志和上游应用日志,确认同一个请求在上游是否有处理记录。
按以下顺序做一次最小排查:
- 用 curl 或 Postman 直接调用中转站,记录返回的 HTTP 状态码和所有响应头。
- 检查响应头中是否包含 x-upstream-status、x-gateway-timeout 等字段。
- 检查响应体中是否存在业务 code 字段,常见字段名是 code、errcode、bizCode、respCode。
- 用返回的 traceId 查网关日志和上游日志,判断请求是否真的到达业务服务。
这里需要保留两个判断:上游有处理记录但网关仍然返回 5xx,说明是网关回传阶段异常;上游没有记录而网关返回 5xx,说明是网络链路或网关进程故障。两个场景的后续对策不同,前者需要查网关的转发配置和超时时间,后者需要查网络连通性和网关负载。
把网关错误和业务错误拆到不同异常分支
确认网关错误码确实存在之后,需要让接收端代码按类型分派。目标是在 Feign、RestTemplate 或 WebClient 的异常处理层,先读响应体再判断 HTTP 状态码,而不是一进异常就按状态码分类。优先级应该是:响应体里能找到业务 code,当作业务异常处理;找不到业务 code,再根据 HTTP 状态码判断是否网关错误。
以 Feign 的 ErrorDecoder 为例:
public class GatewayAwareErrorDecoder implements ErrorDecoder {
private final ObjectMapper mapper = new ObjectMapper();
@Override
public Exception decode(String methodKey, Response response) {
String body = null;
try (InputStream is = response.body().asInputStream()) {
body = new String(is.readAllBytes(), StandardCharsets.UTF_8);
} catch (IOException e) {
// 无法读取响应体时,按网关错误处理
}
if (body != null) {
try {
JsonNode node = mapper.readTree(body);
if (node.has("code")) {
return new BusinessException(node.get("code").asInt(),
node.get("message").asText());
}
} catch (JsonProcessingException ignored) {
// 响应体不是 JSON,继续按状态码判断
}
}
if (response.status() == 502
|| response.status() == 504
|| response.status() == 429) {
return new GatewayException(response.status(), "中转站链路错误");
}
return new RuntimeException(body);
}
}这段代码的关键顺序是:先读 body 找业务 code,找不到再按 HTTP 状态码分派。如果把 response.status() 放在最外层判断,业务 code 永远没有机会被读取,问题就回到原路。RestTemplate 场景可以把同样逻辑放进 ResponseErrorHandler;WebClient 场景应在 exchange() 中先取 body,再决定是否向下游抛错,避免 onStatus 直接按状态码兜底。
网关错误统一抛 GatewayException,业务异常继续抛 BusinessException。全局异常处理器对两类异常分开处理:GatewayException 返回链路错误信息,不进业务告警;BusinessException 保持原有提示语义。
重试和熔断只对可恢复的网关错误生效
不是所有网关错误都适合重试。502、504、连接超时、读超时属于瞬时链路故障,可以重试;429 表示网关限流,需要看响应头是否带 Retry-After,如果有就按 Retry-After 等待,没有则需要设置比重试间隔更长的退避时间;401、403 如果来自网关鉴权,重试没有意义,应直接进入告警或凭证刷新。
业务侧返回的 4xx 说明请求参数或业务规则不满足,不需要重试;业务侧 5xx 要结合接口是否幂等决定是否重试。在 resilience4j、Spring Retry 的配置里,只把 GatewayException 加入 retryExceptions,BusinessException 不放进重试列表。这样重试和熔断不会把网关瞬时错误放大成业务故障。
用日志和监控确认分支是否正确命中
策略是否生效,要以日志为准。建议在 GatewayException 和 BusinessException 两个分支打印不同的日志关键词,例如 gateway_error、biz_error。日志至少包含请求路径、上游状态码、网关状态码、耗时和 traceId。告警系统可以按两个关键词分组,分别设置阈值,避免把网关错误码全部归到业务告警里。
可以做两个最小验证。第一,让中转站返回一个 502 或 429,观察调用方日志是否只出现 gateway_error,业务告警没有新增。第二,让上游业务模块主动抛业务异常,确认 biz_error 分支正常工作。两组对照可以确认错误码分派没有混淆。
风险边界在于中转站响应头和响应体结构差异较大,以上判断依赖的 code、x-upstream-status、Retry-After 字段,需要以实际网关透传格式为准。如果中转站不保留任何原始状态信息,就只能靠链路追踪平台比对网关日志与上游日志,不能仅凭 HTTP 状态码给出最终结论。