spring boot 的全局异常处理机制无法直接捕获网关转发产生的异常，因为网关（如 spring cloud gateway）与后端服务是独立的进程，它们之间通过 http 协议通信。当网关遇到网络超时、连接拒绝或下游服务返回错误状态码时，它会将这些情况封装为特定的运行时异常抛出，而不是将后端的业务异常透传过来。要解决这个问题，需要在网关项目中配置全局异常处理器，专门拦截网关层面的异常类型，并根据需要将其转换为前端可识别的统一响应格式。
如何捕获网关的网络层异常
在 Spring Cloud Gateway 中，网络层的异常通常表现为 ResponseStatusException 或 ConnectException。这些异常发生在请求到达后端服务之前或之后，属于基础设施层面的问题。开发者可以通过实现 GlobalExceptionHandler 接口或在配置类中注册 ErrorWebExceptionHandler 来捕获这些异常。重点在于区分“路由未找到”和“连接失败”，前者通常对应 404，后者可能对应 503 或自定义的错误码。通过重写 handleUncaughtException 方法，可以统一处理这些不可预见的网络中断，确保客户端收到明确的错误提示，而不是默认的 HTML 错误页面。
import org.springframework.boot.web.reactive.error.ErrorWebExceptionHandler;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.buffer.DataBufferFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
@Order(-1)
@Component
public class GatewayExceptionHandler implements ErrorWebExceptionHandler {
@Override
public Mono<void> handle(ServerWebExchange exchange, Throwable ex) {
ServerHttpResponse response = exchange.getResponse();
if (response.isCommitted()) {
return Mono.empty();
}
HttpStatus status;
String message;
if (ex instanceof ResponseStatusException) {
status = ((ResponseStatusException) ex).getStatusCode();
message = ex.getMessage();
} else if (ex.getCause() instanceof java.net.ConnectException) {
status = HttpStatus.SERVICE_UNAVAILABLE;
message = "Service Unavailable: Connection refused";
} else {
status = HttpStatus.INTERNAL_SERVER_ERROR;
message = "Internal Server Error";
}
response.setStatusCode(status);
response.getHeaders().setContentType(org.springframework.http.MediaType.APPLICATION_JSON);
DataBufferFactory bufferFactory = response.bufferFactory();
String result = "{\"code\":" + status.value() + ",\"message\":\"" + message + "\"}";
return response.writeWith(Mono.just(bufferFactory.wrap(result.getBytes())));
}
}</void>
如何捕获网关的路由匹配异常
当请求的 URL 路径无法匹配任何配置的 Route 时，网关会抛出 NoHandlerFoundException 或类似的 404 异常。这与后端服务的 404 不同，它是网关自身的行为。为了捕获这类异常，需要在网关的配置中显式地处理路由缺失的情况。通常的做法是定义一个兜底的路由规则，或者在全局异常处理器中专门针对 404 状态码进行拦截。这样可以避免网关返回标准的 Tomcat 或 Netty 错误页，而是返回 JSON 格式的错误信息，保持前后端交互的一致性。此外，还可以结合 PredicateFactory 自定义断言逻辑，提前拦截非法请求，减少异常抛出的频率。
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.cloud.gateway.filter.factory.rewrite.CachingRequestBodyGatewayFilterFactory;
import org.springframework.core.Ordered;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
@Component
public class NotFoundRouteFilter implements GlobalFilter, Ordered {
@Override
public Mono<void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
// 在实际应用中，这里通常不需要手动过滤，因为网关会自动处理路由匹配
// 但为了演示如何捕获特定条件，我们可以检查路径是否以 /api/v1 开头
String path = exchange.getRequest().getPath().value();
if (path.startsWith("/api/v1") && !exchange.getAttribute("route.id").equals("backend-service")) {
// 模拟路由未找到的处理
exchange.getResponse().setStatusCode(HttpStatus.NOT_FOUND);
return exchange.getResponse().setComplete();
}
return chain.filter(exchange);
}
@Override
public int getOrder() {
return -2; // 确保在默认路由过滤器之前执行
}
}</void>
网关转发异常中哪些字段可用于前端重试决策
在网关转发的异常响应中，最关键的字段是 HTTP 状态码和自定义的错误消息。对于前端而言，状态码决定了是否需要重试：5xx 系列（如 502 Bad Gateway, 503 Service Unavailable）通常表示临时性故障，适合进行指数退避重试；而 4xx 系列（如 400 Bad Request, 401 Unauthorized）则表示客户端错误，重试无效。此外，如果网关配置了熔断器（如 Resilience4j），异常信息中可能包含熔断器触发的标记，前端可以根据这些标记决定是否暂停发送请求。开发者应在网关的异常处理器中，将这些信息结构化地返回给前端，例如在 JSON 响应中包含 retryable 布尔值字段，明确指示前端是否应该尝试重新发起请求。
