spring boot接口超时需分清对外调用与被调用两层：对外用resttemplate/webclient配置connect/read或response超时；对内需通过容器参数（如server.tomcat.connection-timeout）或异步+future.get()控制，spring.mvc.*-timeout等配置无效。
Spring Boot 中 REST 接口请求超时配置，核心要分清两个层面：一是本服务对外发起的 HTTP 调用（比如用 RestTemplate 或 WebClient 调第三方接口），二是本服务被外部调用时的容器级超时（比如 Tomcat 接收请求后处理太久）。两者配置位置、原理和工具完全不同，不能混用。
对外调用超时（RestTemplate / WebClient）
这是最常被问到的场景，指你代码里主动发出去的请求什么时候该放弃。
-
RestTemplate（同步，已不推荐但仍在用）：必须通过
ClientHttpRequestFactory设置。默认底层是SimpleClientHttpRequestFactory，它支持connectTimeout（建连超时）和readTimeout（读响应超时）：
Java 配置示例：
@Bean
public RestTemplate restTemplate() {
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(3000); // 3秒建连
factory.setReadTimeout(10000); // 10秒读响应
return new RestTemplate(factory);
}
-
WebClient（推荐，响应式）：基于 Netty，默认就带超时控制，用
ExchangeStrategies配置：
Java 配置示例：
@Bean
public WebClient webClient() {
return WebClient.builder()
.exchangeStrategies(ExchangeStrategies.builder()
.codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024))
.build())
.clientConnector(new ReactorClientHttpConnector(
HttpClient.create()
.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 3000)
.responseTimeout(Duration.ofSeconds(10))
))
.build();
}
- 注意：WebClient 的
responseTimeout是从请求发出到收到完整响应的总耗时上限，比 RestTemplate 的 connect+read 更贴近实际业务感知。
本服务被调用时的容器超时（Tomcat/Jetty/Undertow）
这是指别人访问你的 @RestController 接口，比如 GET /api/user，如果这个接口内部处理太慢（如查库卡住、远程调用没设超时），整个线程会一直占着，影响吞吐。这时需限制容器层的处理时间。
-
Tomcat（默认）：在
application.properties中配置：
# 等待请求头解析完成的最大时间（单位毫秒） server.tomcat.connection-timeout=20000 <h1>注意：这不是业务逻辑执行超时，而是连接建立后等待完整请求数据的时间</h1><h1>若想真正限制业务处理时长，需配合编程式中断或异步 + timeout</h1>
- 真正限制「业务方法执行多久就强制返回」，Spring MVC 本身不提供全局执行超时机制。常见做法是：把耗时操作移到
@Async方法中，并用Future.get(5, TimeUnit.SECONDS)控制；或用CompletableFuture.orTimeout()（WebFlux 场景更自然）。
配置文件方式的误区提醒
网上常看到这类写法：
spring.mvc.connect-timeout=10000 spring.mvc.read-timeout=10000
这是无效配置。Spring Boot 官方文档中没有 spring.mvc.*-timeout 这些属性。它们不会生效，也不会报错，容易让人误以为配对了。
- 真正能通过配置文件控制的，只有容器层（如
server.tomcat.connection-timeout）和 WebClient（需自定义HttpClient属性）； - RestTemplate 必须靠 Java Bean 配置，无法纯靠 properties/yml 驱动超时。
异常处理与兜底建议
超时发生后，程序不能静默失败：
- RestTemplate 超时抛
ResourceAccessException（含SocketTimeoutException）； - WebClient 超时触发
WebClientRequestException或TimeoutException； - 务必在调用处
try-catch，返回明确错误码（如 503 Service Unavailable）和提示（如“依赖服务响应超时，请稍后重试”）； - 对关键链路，可叠加降级策略（如返回缓存数据、空对象）或熔断（用 Resilience4j）。
