使用 @controlleradvice 配合 @exceptionhandler 可以捕获连接超时异常。针对 spring boot 默认使用的 resttemplate,需要捕获 resourceaccessexception;若使用 webclient,则需捕获 webclientrequestexception。在处理器中通过 cause.getcause() 获取底层的 sockettimeoutexception 或 connectexception,从而区分是连接建立失败还是数据读取超时。

RestTemplate 全局异常处理实现
对于基于同步调用的 RestTemplate,Spring MVC 的全局异常处理器可以直接拦截 org.springframework.web.client.ResourceAccessException。该异常是网络层异常的包装类,其内部原因通常包含具体的超时类型。开发者只需定义一个继承自 ResponseEntityExceptionHandler 的类,并添加 @RestControllerAdvice 注解即可生效。

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.client.ResourceAccessException;
@ControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
@ExceptionHandler(ResourceAccessException.class)
public ResponseEntity<string> handleTimeout(ResourceAccessException ex) {
Throwable cause = ex.getCause();
if (cause instanceof java.net.SocketTimeoutException) {
return ResponseEntity.status(504).body("Gateway Timeout: Read timed out");
} else if (cause instanceof java.net.ConnectException) {
return ResponseEntity.status(503).body("Service Unavailable: Connection refused");
}
return ResponseEntity.status(500).body("Network Error: " + cause.getMessage());
}
}</string>
上述代码定义了统一的返回结构。当 RestTemplate 发起请求时,如果底层 Socket 无法在指定时间内建立连接,会抛出带有 ConnectException 原因的 ResourceAccessException;如果连接成功但服务器未在限定时间内响应数据,则会抛出带有 SocketTimeoutException 原因的同类异常。通过判断 getCause() 的类型,可以精准返回不同的 HTTP 状态码和错误信息。
WebClient 异步流式异常处理
如果使用响应式的 WebClient,由于它是基于 Reactor 的异步非阻塞模型,传统的 @ControllerAdvice 无法直接拦截其内部的订阅异常。需要在构建 WebClient 时配置 ExchangeFilterFunction,或者在调用链末端使用 onErrorResume 进行统一处理。这里展示如何在过滤器层面统一捕获超时异常。

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeFunction;
import reactor.core.publisher.Mono;
import reactor.util.retry.Retry;
import java.time.Duration;
@Component
public class TimeoutFilter implements ExchangeFilterFunction {
@Override
public Mono<clientresponse> filter(ClientRequest request, ExchangeFunction next) {
return next.exchange(request)
.timeout(Duration.ofSeconds(5))
.onErrorResume(java.net.http.HttpTimeoutException.class, e ->
Mono.just(ClientResponse.create(HttpStatus.GATEWAY_TIMEOUT).build())
)
.onErrorResume(org.springframework.web.reactive.function.client.WebClientRequestException.class, e ->
Mono.just(ClientResponse.create(HttpStatus.SERVICE_UNAVAILABLE).body(e.getMessage()).build())
);
}
}</clientresponse>
在 WebClient 的场景下,timeout 操作符会将超时转换为 java.net.http.HttpTimeoutException(Java 11+)或 OnErrorNotImplementedException。而底层的连接拒绝或 DNS 解析失败通常会包装在 WebClientRequestException 中。通过在 Filter 中链式调用 onErrorResume,可以将这些异常转换为标准的 ClientResponse,从而保证下游业务逻辑接收到的是明确的错误响应而非未处理的异常堆栈。
如何区分 ConnectException 与 SocketTimeoutException
在全局异常处理中,准确区分“连不上”和“读得慢”至关重要。这取决于 ResourceAccessException 的 getCause() 返回的具体实例。如果是 java.net.ConnectException: Connection refused,说明目标主机可达但端口未监听或服务未启动,此时应返回 503 Service Unavailable。如果是 java.net.SocketTimeoutException: connect timed out,说明 TCP 三次握手在指定时间内未完成,通常也是 503 或 504。如果是 SocketTimeoutException: Read timed out,说明连接已建立,但服务器处理缓慢或未返回数据,此时应返回 504 Gateway Timeout。这种区分有助于前端或客户端根据状态码采取不同的重试策略,例如对 503 进行指数退避重试,而对 504 可能直接提示用户稍后尝试。











