Spring WebClient 文件下载失败（空文件）的完整解决方案-java教程-PHP中文网

Spring WebClient 文件下载失败（空文件）的完整解决方案

使用 Spring WebClient 下载二进制文件时出现 0 字节空文件，通常源于 DataBufferUtils.write() 链式调用未正确完成或资源未及时释放；本文提供可落地的修复代码、关键注意事项及验证方法。

使用 spring webclient 下载二进制文件时出现 0 字节空文件，通常源于 `databufferutils.write()` 链式调用未正确完成或资源未及时释放；本文提供可落地的修复代码、关键注意事项及验证方法。

在 Spring WebFlux 生态中，WebClient 是响应式 HTTP 客户端，其异步非阻塞特性要求开发者严格遵循响应式编程范式——任何 Flux/Mono 流都必须被订阅（subscribe）或显式触发执行，否则不会真正发起请求或写入数据。你遇到的“请求成功但文件为空”问题，根本原因正是：DataBufferUtils.write(...).share().block() 中的 block() 调用虽等待完成，但 write() 返回的是 Mono，而你未对其结果做有效消费或错误处理，导致部分场景下流提前终止或缓冲区未刷新。

✅ 正确写法：确保 Mono 被完整消费并处理异常

Path path = Paths.get("src/main/resources/", test + ".bin");

WebClient client = WebClient.create();

Mono<void> downloadMono = client
    .get()
    .uri(download_url)
    .header("Authorization", "Bearer " + token)
    .retrieve()
    // 显式处理错误状态码（推荐返回具体错误信息）
    .onStatus(HttpStatus::isError, response -> 
        response.bodyToMono(String.class)
            .flatMap(errorBody -> Mono.error(
                new RuntimeException("HTTP " + response.statusCode() + ": " + errorBody)
            ))
    )
    // 流式读取原始字节流
    .bodyToFlux(DataBuffer.class)
    // 写入文件（返回 Mono<void>）
    .transform(dataBufferFlux -> DataBufferUtils.write(
        dataBufferFlux, 
        path, 
        StandardOpenOption.CREATE, 
        StandardOpenOption.WRITE
    ));

// 关键：必须 subscribe 或 block 并检查结果
try {
    downloadMono.block(); // 同步阻塞等待完成（适用于非纯响应式环境）
    log.info("✅ 文件下载完成: {}", path.toAbsolutePath());
} catch (Exception e) {
    log.error("❌ 文件下载失败", e);
    throw new CustException("下载失败: " + e.getMessage(), 500);
}</void></void>

⚠️ 关键注意事项

不要省略 StandardOpenOption.WRITE：仅 CREATE 无法覆盖/写入内容，必须显式添加 WRITE（尤其在重复下载同一路径时）；
避免 share().block() 的冗余调用：DataBufferUtils.write() 已返回 Mono，share() 对单次写入无意义，且可能干扰调度器行为；
务必捕获并记录异常：onStatus 中抛出的异常若未被 block() 捕获，将静默失败；
路径安全性：生产环境应校验 test 变量，防止路径遍历（如 ../../../etc/passwd），建议使用 FilenameUtils.getName() 或白名单过滤；
大文件场景优化：若文件较大（>100MB），建议添加 doOnNext 监控进度，并配置 WebClient 的 codecs 以限制缓冲区大小：
```
.codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(8 * 1024 * 1024))
```

? 验证是否真正生效？

运行以下最小化单元测试（无需启动应用）快速复现与验证：

@Test
void webClientDownloadIntegrationTest() throws IOException {
    String downloadUrl = "https://httpbin.org/image/png"; // 返回二进制 PNG
    Path tempFile = Files.createTempFile("download-test-", ".bin");

    Mono<void> writeMono = WebClient.create()
        .get().uri(downloadUrl)
        .retrieve()
        .onStatus(HttpStatusCode::isError, r -> Mono.error(new RuntimeException("HTTP Error")))
        .bodyToFlux(DataBuffer.class)
        .transform(flux -> DataBufferUtils.write(flux, tempFile, StandardOpenOption.CREATE, StandardOpenOption.WRITE));

    StepVerifier.create(writeMono)
        .verifyComplete(); // 断言写入完成

    assertTrue(Files.size(tempFile) > 0, "文件大小应大于 0");
    Files.delete(tempFile);
}</void>