Spring WebClient无法解码application/octet-stream为File对象问题

问题根因 #

OpenAPI规范中定义二进制返回值的结构如下：

"schema": {
  "type": "string",
  "format": "binary"
}

插件默认将该类型映射为java.io.File，生成的接口方法代码为：

public Mono<ResponseEntity<File>> downloadWithHttpInfo(String filename) throws WebClientResponseException {
    ParameterizedTypeReference<File> localVarReturnType = new ParameterizedTypeReference<File>() {};
    return downloadRequestCreation(filename).toEntity(localVarReturnType);
}

调用时服务端返回200状态码、Content-Type: application/octet-stream的正常响应，客户端抛出异常：

org.springframework.web.reactive.function.UnsupportedMediaTypeException:
    Content type 'application/octet-stream' not supported for bodyType=java.io.File

该异常由Spring WebClient内置toEntity()方法抛出：WebClient默认没有提供application/octet-stream媒体类型到java.io.File的解码器实现，不属于自定义业务代码问题。

两种方案验证结论 #

• 方案A（优先推荐）：配置插件将二进制类型映射为org.springframework.core.io.Resource
  该方案是官方原生支持的配置能力，无额外运行时侵入。Spring WebClient原生支持将二进制流解码为Resource类型，不存在类型不支持的问题。配置方式为在OpenAPI Generator Maven Plugin的configOptions节点中添加类型映射规则，将string/binary的映射类型指定为org.springframework.core.io.Resource，生成的代码会自动将返回类型调整为Mono<ResponseEntity<Resource>>。拿到返回的Resource对象后，可自行通过FileCopyUtils或Resource#transferTo方法将流落地为本地File对象，逻辑可控无兼容问题。

• 方案B：自定义WebClient解码器支持File类型解析
  该方案技术上可行，但维护成本更高。需要自定义实现Spring WebClient的Decoder接口，完成二进制流读取、临时文件创建、流写入、异常处理、临时文件回收等全链路逻辑，再将自定义解码器注册到WebClient的ExchangeStrategies配置中。如果全局注册解码器可能影响其他接口的默认解码逻辑，如果仅为生成的客户端单独配置WebClient实例，整体维护成本远高于方案A，仅在项目强依赖返回java.io.File类型、无法调整生成规则时使用。

选型建议 #

无特殊强依赖场景下直接选择方案A，通过生成器配置修正类型映射即可解决问题，不需要额外编写运行时代码，兼容性和稳定性最优。

内容的提问来源于stack exchange，提问作者user1589188