spring boot 的全局异常处理机制无法直接捕获负载均衡器(如 nginx、slb)产生的 http 错误,因为这类异常发生在应用服务器之外,客户端收到的是标准的 http 状态码而非 java 异常。要处理这种情况,需要结合前端或网关层的统一响应格式,并在 spring boot 中配置针对特定 http 状态码(如 502 bad gateway、504 gateway timeout)的自定义错误页面或 json 响应。

如何区分并处理网关返回的 502 和 504 错误
当负载均衡器因后端服务不可用或超时而拦截请求时,它会直接向客户端返回 502 或 504 状态码,此时 Spring Boot 的 Controller 层根本不会执行,因此 `@ControllerAdvice` 中的 `@ExceptionHandler` 无法捕获这些异常。正确的做法是利用 Spring Boot 的默认错误处理机制,通过配置 `server.error.whitelabel.enabled=false` 来禁用默认的 Whitelabel Error Page,并实现一个自定义的 `ErrorController` 或使用 `@RestController` 风格的错误映射来处理这些 HTTP 状态码。

import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;
@Controller
public class CustomErrorController implements ErrorController {
@RequestMapping("/error")
public ResponseEntity<Map<String, Object>> handleError(HttpServletRequest request) {
Map<String, Object> body = new HashMap<>();
Integer status = (Integer) request.getAttribute("javax.servlet.error.status_code");
if (status != null) {
if (status == 502 || status == 504) {
body.put("code", status);
body.put("message", "Gateway error: Service unavailable or timeout");
body.put("type", "LOAD_BALANCER_ERROR");
return new ResponseEntity<>(body, HttpStatus.valueOf(status));
}
}
// 其他错误处理逻辑
body.put("code", 500);
body.put("message", "Internal Server Error");
return new ResponseEntity<>(body, HttpStatus.INTERNAL_SERVER_ERROR);
}
@Override
public String getErrorPath() {
return "/error";
}
}
上述代码定义了一个全局的错误处理器,它拦截所有未处理的 HTTP 错误。当负载均衡器返回 502 或 504 时,`request.getAttribute("javax.servlet.error.status_code")` 会获取到对应的状态码。通过判断状态码,我们可以返回统一的 JSON 结构,告知前端这是网关层面的错误,而不是业务逻辑错误。这样,前端可以根据 `type` 字段决定是重试还是提示用户稍后尝试。
如何在微服务架构中统一网关错误的响应格式
在微服务架构中,通常会在 Spring Cloud Gateway 或 Zuul 等网关层进行负载均衡。如果希望在全局层面统一处理这些错误,可以在网关层配置全局过滤器,将负载均衡异常转换为标准的错误响应体。对于 Spring Boot 单体应用,如果它本身作为网关使用,可以通过 `GlobalFilter` 来实现。但更常见的情况是,Spring Boot 应用作为被调用的微服务,其上游网关负责负载均衡。此时,Spring Boot 应用只需确保自己的错误响应格式与网关一致即可。

import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.cloud.gateway.filter.factory.rewrite.CachedBodyOutputMessage;
import org.springframework.cloud.gateway.support.ServerWebExchangeUtils;
import org.springframework.core.Ordered;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
@Component
public class GlobalErrorHandlerFilter implements GlobalFilter, Ordered {
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
return chain.filter(exchange).then(Mono.fromRunnable(() -> {
HttpStatus statusCode = exchange.getResponse().getStatusCode();
if (statusCode == HttpStatus.BAD_GATEWAY || statusCode == HttpStatus.GATEWAY_TIMEOUT) {
exchange.getResponse().getHeaders().setContentType(
org.springframework.http.MediaType.APPLICATION_JSON);
// 这里可以写入统一的错误响应体
// 注意:在实际生产中,可能需要更复杂的逻辑来构建响应体
}
}));
}
@Override
public int getOrder() {
return -1;
}
}
这段代码展示了在 Spring Cloud Gateway 中如何实现全局错误处理。通过实现 `GlobalFilter`,我们可以在请求处理后检查响应状态码。如果检测到 502 或 504,我们可以修改响应头或响应体,使其符合全局统一的错误规范。这确保了无论错误来源是上游负载均衡器还是下游服务,客户端收到的响应格式都是一致的。需要注意的是,修改响应体在 WebFlux 环境下较为复杂,通常需要缓存请求体并重新写入,上述代码仅为示意,实际应用中需根据具体需求调整。
当负载均衡器返回 503 Service Unavailable 时如何处理
除了 502 和 504,负载均衡器还可能返回 503 Service Unavailable,这通常表示后端服务暂时过载或正在维护。处理 503 错误的逻辑与 502/504 类似,都需要在错误控制器中进行状态码判断。关键区别在于,503 错误可能伴随着 Retry-After 响应头,指示客户端等待多久后再重试。Spring Boot 的全局错误处理可以读取并透传这个头信息,或者在前端根据 503 状态码实现指数退避重试策略。
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;
@Controller
public class EnhancedErrorController extends CustomErrorController {
@RequestMapping("/error")
@Override
public ResponseEntity<Map<String, Object>> handleError(HttpServletRequest request) {
Map<String, Object> body = new HashMap<>();
Integer status = (Integer) request.getAttribute("javax.servlet.error.status_code");
if (status != null) {
if (status == 503) {
body.put("code", 503);
body.put("message", "Service temporarily unavailable");
body.put("type", "SERVICE_UNAVAILABLE");
// 可以添加重试建议
body.put("retryAfter", 5); // 假设建议等待5秒
return ResponseEntity.status(503).body(body);
}
}
return super.handleError(request);
}
}
通过继承之前的 `CustomErrorController` 并重写 `handleError` 方法,我们可以专门处理 503 错误。在返回的 JSON 中,我们添加了 `retryAfter` 字段,虽然这不是 HTTP 标准的一部分,但可以作为前端重试逻辑的参考。这种处理方式使得错误信息更加丰富,有助于前端做出更智能的用户体验决策,例如显示“系统繁忙,请稍后重试”并自动刷新页面。


















