这两年在做音频转文字相关的功能，绕不开的就是调用第三方文件转写API。Java 17的HttpClient是JDK内置的，不用引入额外依赖，单纯调个REST接口很舒服，但一碰到文件上传这种重IO场景，超时和失败就成了家常便饭。我接手的一个内部服务就是典型例子：调用转写API上传录音文件，高峰期超时率接近15%，日志里全是SocketTimeoutException和HTTP 504，刚开始以为是网络问题，后来发现是超时配置、重试策略、回退方案全都没做对。
这篇文章把我在这个项目里的完整思路和落地代码整理出来。内容围绕三件事：第一，文件转写API为什么容易超时，Java 17 HttpClient在超时控制上有哪些坑；第二，超时参数怎么配，上传请求怎么构建才不容易出问题；第三，失败后怎么分类、怎么重试、怎么回退，做到让整个调用链路在高并发和弱网下不至于整体崩掉。适合正在用Java 17写API调用、或准备把转写能力接进自己系统的后端同学参考。
1. 先搞清楚文件转写API为什么是超时重灾区
1.1 转写调用的典型链路与时间分布
文件转写API和普通REST API的最大区别在于时间分布完全不同。普通GET接口从发出到响应通常在几百毫秒内，超时配置按秒级给就够了。转写接口要干的事多得多：接收文件、落盘、可能还要做语音预处理、切片、丢给识别引擎，最后才返回JSON。如果上传的是一个几十MB的录音文件，光网络传输这一块在弱网环境下就可能拖到几十秒。再加上服务端排队和实际转写耗时，整个请求跨一两分钟都不稀奇。
这种长耗时接口如果还在用“3秒超时”的思路，基本是必炸的。而如果超时时间给得太宽，比如设成5分钟，一旦上游服务真的挂了，你的线程就会被占住5分钟，线程池一满，整个应用跟着雪崩。所以核心思路不是“把超时调到很大”，而是“把超时拆开，分段控制，并配合重试和回退”。
转写接口的耗时构成，可以粗略分四段：网络传输、服务端排队、转写执行、结果返回。前两段加起来通常占大头。分段控制的意思就是：连接超时严格一些，比如5到10秒；请求超时覆盖到“拿到响应头”，根据文件大小合理设置，比如30到60秒；至于响应体的读取，这里有一个大坑，后面单独讲。
1.2 Java 17 HttpClient能做什么、做不了什么
Java 11引入、Java 17稳定后的HttpClient，功能上其实很完整：同步异步都支持、HTTP/2、连接池、TLS、内置的BodyPublisher和BodyHandler，不用再为调一个接口引入Apache HttpClient或者OkHttp。但它在超时控制上给的东西非常基础。
先说它能做的：connectTimeout可以设连接超时，HttpRequest.timeout可以设请求超时，异步调用返回CompletableFuture可以用orTimeout加兜底。这些配置都是声明式的，写起来很简单。
但它没做的：第一，没有单独的socket read timeout，响应体传输过程中长时间收不到数据，HttpRequest.timeout管不到，因为到达响应头之后timeout就失效了；第二，没有内置重试机制，无论连接失败还是返回5xx，都得自己写；第三，没有内置回退或者容错的概念。所以把HttpClient当作一个“高级socket客户端”来用就行，超时、重试、回退这些可靠性逻辑全得靠业务层补上去。
这也解释了为什么很多人照抄官方文档配置完，上线还是会遇到“请求卡死几分钟不返回”这类问题。接下来要重点讲清楚三个超时层次怎么配。
2. 超时参数怎么配：三个超时层次
2.1 连接超时与请求超时的正确配法
连接超时是HttpClient级别的基础配置，覆盖的是TCP握手阶段。对于文件转写这种长请求场景，连接超时可以设得短一些，5到10秒足够。如果服务端连握手都不响应，多半是网络隔离、DNS解析失败、或者端口不通，设置长没有意义。
HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .version(HttpClient.Version.HTTP_1_1) .build();请求超时是HttpRequest自带的timeout，用法是在构建请求时显式声明：
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(transcribeUrl)) .timeout(Duration.ofSeconds(60)) .header("Authorization", "Bearer " + token) .POST(publisher) .build();这里的timeout实际语义是“从请求发出到收到响应头的时间上限”。也就是说，它不是整个请求的硬性超时，只要响应头一到，timeout任务就算完成，后面读body多久它不再管。所以它适合控制“服务端连接建立后久不响应”的情况，比如等待转写结果等到超时，会抛HttpTimeoutException。
超时时间怎么定？我提供一个可以参考的经验公式：请求超时 = 预计上传时间 + 服务端预计处理时间 + 30秒余量。比如预计上传10秒、服务端处理20秒，那至少给60秒；如果文件更大，按实际比例放大。宁可超时设宽一点，把可靠性交给下面的重试和回退，也不要因为超时太紧造成大量误杀。
2.2 multipart上传的BodyPublisher选择与内存控制
文件转写API的标准接收方式通常是multipart/form-data。HttpClient没有直接提供multipart的BodyPublisher，需要自己拼。小文件场景直接拼字节数组最省事：
static HttpRequest.BodyPublisher ofMultipart( String boundary, Map<String, String> fields, Path filePath, String fileField, String fileName, String contentType) throws IOException { byte[] crlf = "\r\n".getBytes(StandardCharsets.UTF_8); var bos = new ByteArrayOutputStream(); for (var e : fields.entrySet()) { bos.writeBytes(("--" + boundary).getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); bos.writeBytes(("Content-Disposition: form-data; name=\"" + e.getKey() + "\"").getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); bos.writeBytes(crlf); bos.writeBytes(e.getValue().getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); } bos.writeBytes(("--" + boundary).getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); bos.writeBytes(("Content-Disposition: form-data; name=\"" + fileField + "\"; filename=\"" + fileName + "\"").getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); bos.writeBytes(("Content-Type: " + contentType).getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); bos.writeBytes(crlf); Files.copy(filePath, bos); bos.writeBytes(crlf); bos.writeBytes(("--" + boundary + "--").getBytes(StandardCharsets.UTF_8)); bos.writeBytes(crlf); return HttpRequest.BodyPublishers.ofByteArray(bos.toByteArray()); }然后这样构造请求：
var boundary = "----JavaHttpClientBoundary" + System.nanoTime(); var publisher = ofMultipart(boundary, Map.of("language", "zh-CN"), file, "file", "record.wav", "audio/wav"); var request = HttpRequest.newBuilder(uri) .timeout(Duration.ofSeconds(60)) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .POST(publisher) .build();这里必须提醒一个内存风险：ByteArrayOutputStream把整个文件都读进内存。几十MB的音频文件问题不大，但如果是上百MB、或者QPS一高，就会出现频繁GC甚至OOM。解决方案有几个，我按文件大小给三条路线：小于50MB用上面的ByteArrayOutputStream拼装，简单可靠；50MB到200MB之间，用BodyPublishers.ofInputStream配合PipedStream来做流式传输；更大的文件，建议走下面第4章讲到的异步任务模式——先提交任务再轮询结果，上传阶段只传文件，不让服务端同步计算，对客户端内存压力小很多。
2.3 容易被忽略的响应体读取超时
前面已经反复提到一个关键点：HttpRequest.timeout管不到body下载阶段。这意味着如果服务端返回响应头之后，连接变慢或挂起，你的请求可能长时间卡在读body。实测表现就是：日志里没有异常，线程一直挂在那，远端既没有数据来，也没有断开。
解决办法是给异步调用叠加orTimeout。无论底层用同步还是异步，都建议用CompletableFuture做一层兜底：
CompletableFuture<HttpResponse<String>> future = client.sendAsync(request, HttpResponse.BodyHandlers.ofString()) .orTimeout(90, TimeUnit.SECONDS); future.whenComplete((resp, throwable) -> { if (throwable != null) { // 进入回退逻辑 } else { // 正常处理响应 } });orTimeout触发后，业务代码会拿到TimeoutException，可以进入回退。需要注意，它并不会真正取消底层HTTP连接，数据还在往里传，只是业务层不再等待。在高并发场景下，被丢弃的连接会继续占用连接池资源一段时间，所以如果超时发生得很频繁，要留意连接池的健康度，必要时重建client，或者对超时任务调用future.cancel(true)。
3. 失败怎么分类、回退怎么设计
3.1 错误码即诊断信息：先分类再决策
失败回退的第一步不是写重试逻辑，而是给错误分类。转写API调用过程中出现的错误可以归成三类：连接层错误、服务端错误、业务参数错误。
连接层错误表现为ConnectException、SocketTimeoutException、HttpTimeoutException、SSLException。这类错误的特征是“请求根本没可靠到达服务端，或者服务端没可靠返回”，基本可以安全重试。但如果请求已经发出去了，服务端其实可能已经收到了，就要考虑幂等。
服务端错误表现为HTTP 5xx：500服务内部异常，502/504网关超时，503服务暂不可用。这类是最典型的可重试错误。但重试也有讲究：503通常说明负载高，马上重试大概率还是503，所以必须配合退避。
业务参数错误表现为HTTP 4xx：400参数错误、401未授权、403无权限、404路径错误、413文件过大。这类错误重试没有任何意义，应该直接打日志、报警，甚至进入人工处理队列。有一种例外是429限流，虽然它也是4xx，但它是临时性的，服务端希望你在Retry-After之后重试，所以429要单独处理。
我的原则是：先根据状态码把问题区分开，再决定要不要重试、用什么节奏重试。不要所有异常一把梭重试，也不要把5xx和4xx混在一起处理。
3.2 指数退避重试：写一个可用的Retryer
重试最忌讳的是固定间隔重试，尤其是在服务端已经过载的情况下，一堆请求同时重试会形成重试风暴。正确做法是指数退避加随机抖动。指数退避好理解：第一次等1秒，第二次2秒，第三次4秒，直到最大上限。加抖动的目的，是让同一时刻失败的一批请求不会在退避时间到达时“整齐”地一起重试，而是错开，避免二次打爆服务端。
public final class Retryer { private final int maxAttempts; private final Duration baseDelay; private final Duration maxDelay; private final Predicate<Throwable> retryable; public Retryer(int maxAttempts, Duration baseDelay, Duration maxDelay, Predicate<Throwable> retryable) { this.maxAttempts = maxAttempts; this.baseDelay = baseDelay; this.maxDelay = maxDelay; this.retryable = retryable; } public <T> T execute(Callable<T> action) { int attempt = 0; while (true) { try { return action.call(); } catch (Exception e) { attempt++; if (attempt >= maxAttempts || !retryable.test(e)) { throw new TranscribeClientException("转写调用失败，已重试" + (attempt - 1) + "次", e); } sleep(backoff(attempt)); } } } private Duration backoff(int attempt) { long base = baseDelay.toMillis(); long exponent = 1L << Math.min(attempt, 10); long delay = Math.min(base * exponent, maxDelay.toMillis()); long jitter = ThreadLocalRandom.current().nextLong(0, base); return Duration.ofMillis(delay + jitter); } private void sleep(Duration delay) { try { Thread.sleep(delay.toMillis()); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new TranscribeClientException("重试等待被中断", e); } } }maxAttempts我通常设置为3到4次，baseDelay 1秒，maxDelay 15秒。重试时每次都要重新构建HttpRequest，因为如果用的是自定义InputStream的BodyPublisher，上一轮请求可能已经用掉了流；更重要的是，请求头里要带上同一个X-Request-Id，便于服务端幂等判断。
判断哪些异常可重试，写一个Predicate：
static boolean isRetryable(Throwable t) { if (t instanceof HttpTimeoutException || t instanceof ConnectException || t instanceof SocketTimeoutException || t instanceof SSLException) { return true; } if (t instanceof ApiCallException) { int code = ((ApiCallException) t).getStatusCode(); return code == 408 || code == 429 || code >= 500; } return false; }注意，Java HttpClient遇到非2xx状态码不会自动抛异常，必须自己在调用处检查response.statusCode()，然后封装成带状态码的业务异常。
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { throw new ApiCallException(response.statusCode(), response.body()); }3.3 真正的回退：备用通道、排队与幂等
重试不是万能的。如果服务端真的挂了5分钟，重试3次也救不回来。这时候回退机制要起作用。
我的做法是分级回退。
第一级是备用API通道。如果主转写服务超时，将同样的文件投给备用服务，但同一时间只保留一个活跃通道，避免两边同时产生高额费用。这里要注意：备用通道的返回格式可能不一样，要做适配层。
第二级是本地暂存加后台重试。文件先落到本地目录或数据库表，记录一个待转写任务的状态。主通道和备用通道都不可用时，任务进入pending状态，由后台的调度线程每分钟扫描一次，按状态重新投递。这样至少保证用户提交的音频不会因为瞬时故障被丢。
第三级是降级参数。用户如果接受较低的转写质量，可以在请求里改参数，比如从高精度模型切到标准模型、或者压缩音频之后再传。压缩音频到64kbps以下能大幅缩短上传和转写时间，提高成功概率。这个思路在弱网环境非常有用。
关于幂等，文件转写有一个其它接口没有的特殊性：服务端接收文件后立即开始处理，请求超时了但任务可能已经在跑。如果不做幂等处理，重试会产生两个转写任务，扣两次费。项目里我通过给请求增加X-Request-Id来实现：
String requestId = UUID.randomUUID().toString(); var request = HttpRequest.newBuilder(uri) .header("X-Request-Id", requestId) .POST(publisher) .build();如果主服务支持幂等键，重复的requestId会复用之前的任务；如果不支持，就要在重试前先调用查询接口，确认任务是否已经存在。这个查询成本通常比误重复扣费低得多。
4. 完整可落地的调用骨架
4.1 带超时和重试的同步上传实现
把前几节的东西串起来，一个完整的同步上传客户端长这样：
public class TranscribeClient { private final HttpClient httpClient; private final Retryer retryer; private final URI endpoint; public TranscribeClient(String endpoint, String token) { this.endpoint = URI.create(endpoint); this.httpClient = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .version(HttpClient.Version.HTTP_1_1) .build(); this.retryer = new Retryer(4, Duration.ofSeconds(1), Duration.ofSeconds(15), TranscribeClient::isRetryable); } public String transcribe(Path audioFile) { return retryer.execute(() -> { String boundary = "----TranscribeBoundary" + System.nanoTime(); String fileName = audioFile.getFileName().toString(); var publisher = MultipartEntity.of(boundary, Map.of("language", "zh-CN"), audioFile, "file", fileName, "audio/wav"); var request = HttpRequest.newBuilder(endpoint) .timeout(Duration.ofSeconds(90)) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .header("X-Request-Id", UUID.randomUUID().toString()) .POST(publisher) .build(); var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { throw new ApiCallException(response.statusCode(), response.body()); } return parseResult(response.body()); }); } }这段代码里的MultipartEntity就是前面那个拼multipart的辅助类，实际使用时按自己的包结构放好就行。parseResult按API的JSON格式解析，返回最终转写文本或任务ID。
4.2 异步任务模式：提交后轮询
很多转写API提供异步模式：先提交任务拿到taskId，再轮询任务状态。这种模式虽然多了一次调用，但对超时控制更友好，因为提交任务本身很快，真正的转写耗时不会占用你的HTTP连接。如果业务允许，我建议优先用这种模式。
提交任务：
var request = HttpRequest.newBuilder(endpoint) .timeout(Duration.ofSeconds(30)) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .POST(publisher) .build(); HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString()); if (response.statusCode() != 200 && response.statusCode() != 202) { throw new ApiCallException(response.statusCode(), response.body()); } String taskId = parseTaskId(response.body());轮询任务状态：
private String pollUntilFinished(String taskId) throws InterruptedException { URI queryUri = URI.create(endpoint + "/" + taskId); int maxPolls = 60; for (int i = 0; i < maxPolls; i++) { var queryRequest = HttpRequest.newBuilder(queryUri) .timeout(Duration.ofSeconds(20)) .GET() .build(); try { HttpResponse<String> resp = httpClient.send(queryRequest, BodyHandlers.ofString()); if (resp.statusCode() == 200) { return resp.body(); } // 服务端返回202表示任务还在处理，继续轮询 } catch (IOException e) { // 网络瞬时故障，忽略这一次轮询，下一轮还能查到 } Thread.sleep(Duration.ofSeconds(3)); } throw new TranscribeClientException("轮询超时，任务未在预期时间内完成: " + taskId); }轮询间隔3秒是我常用的值，可以根据API文档调整。轮询失败的容忍度比上传高：丢一次轮询结果不可怕，下一轮还能查到，所以不需要对轮询做严格重试，只要在最大轮询次数内完成即可。
4.3 配置参数速查表
| 配置项 | 建议值 | 说明 |
|---|---|---|
| 连接超时 | 5~10秒 | TCP建连阶段，设太长没意义 |
| 请求超时（上传） | 30~90秒 | 覆盖到响应头，按文件大小调整 |
| 响应体兜底 | 90~120秒 | 用orTimeout实现 |
| 重试次数 | 3~4次 | 超过这个数走回退 |
| 初始退避 | 1秒 | 指数增长 |
| 最大退避 | 15~30秒 | 防止重试风暴 |
| 轮询间隔 | 3~5秒 | 按API任务处理速度设定 |
| 最大轮询次数 | 视业务而定 | 与轮询间隔配合换算总等待时间 |
4.4 连接池与并发控制
还有一个容易被忽略的点：HttpClient内置连接池和异步事件循环，但并发控制需要自己处理。如果某个入口同时收到大量转写请求，可能瞬间建立几十上百个连接，把上游API的QPS配额打满。我的做法是加一个Semaphore，限制同时进行的转写请求数：
private final Semaphore semaphore = new Semaphore(8); public String transcribeConcurrently(Path audioFile) { try { semaphore.acquire(); return transcribe(audioFile); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new RuntimeException(e); } finally { semaphore.release(); } }并发数可以根据上游API的配额和单个任务的平均耗时来估算。比如QPS配额是5，单任务平均耗时60秒，那么同时进行的请求最多保持在十几到二十个左右，再高就会触发限流。
5. 上线后我踩过的几个坑
5.1 三个真实问题与排查过程
第一个坑：connectTimeout明明设了10秒，但请求还是卡了近两分钟才超时。
原因：connectTimeout只管连接建立。如果请求已经发出、连接也建立了，服务端一直不返回响应头，触发的是HttpRequest.timeout而不是connectTimeout。当时我把两者都设了，但日志里没看到超时异常，才发现是请求对象漏设了timeout，默认值等于无限大。服务端排队卡住时，线程就一直挂着。后来给所有请求显式设置timeout，问题消失。
第二个坑：重试后产生了重复转写任务。
原因：上传完成了但客户端这边等结果超时，自动重试一次。服务端实际已经收到文件并启动了转写任务，造成两笔扣费。排查时看调用上下游的时间戳，确认了两个任务启动时间相差刚好是一个重试间隔。后来加了X-Request-Id，并且重试前先按requestId查询任务是否存在。
第三个坑：内网环境下偶发SSLException，重试后恢复，但没做处理导致任务失败率偏高。
这类异常在弱网和长连接复用场景下时有发生，多数情况重试一次就能成功。之前没有把它归类为可重试异常，导致转写失败率虚高。后来在isRetryable里把SSLException和SocketTimeoutException一并纳入，失败率明显下降。
5.2 问题速查表
| 问题现象 | 可能原因 | 处理建议 |
|---|---|---|
| 请求卡住不返回 | HttpRequest未设置timeout或timeout过宽 | 显式设置请求超时，并叠加orTimeout |
| 连接超时但请求仍占用线程 | 请求已发出，触发的是请求超时而非连接超时 | 区分两类超时，按场景设置 |
| 重试后多扣费/多任务 | 上游已处理但客户端超时，重试造成重复 | 使用X-Request-Id和重试前查询 |
| 偶发SSL握手失败 | 长连接复用或网络抖动 | 加入可重试异常分类 |
| 上传大文件OOM | ByteArrayOutputStream全量缓存 | 用ofInputStream或自定义BodyPublisher |
| HTTP/2连接拖垮其他请求 | 多路复用流互相影响 | 文件上传场景退到HTTP/1.1连接池 |
| 429限流后重试依然429 | 没有按Retry-After退避 | 读取Retry-After，按其值加随机抖动重试 |
最后再分享一个小技巧，是我后来加进去的：对httpClient.sendAsync返回的CompletableFuture统一包一层orTimeout，同时把构建请求、发送、解析、重试判断这些都放进一个可复用的调用封装里，后面接新的转写服务时，只需要换endpoint和解析逻辑，超时和回退的行为是一致的。实测下来，最明显的变化不是成功率，而是系统在极端情况下的行为变得可预期了——该超时的能超时，该重试的会按节奏重试，不会再出现一个请求把线程池占满、把应用拖垮的情况。
