Java JDK HttpClient超时行为解析及Apache CXF适配疑问

问题1：JDK HttpClient的请求超时是否确实从请求发起开始计时，包含数据发送时间？ #

是的，JDK HttpClient通过HttpRequest.Builder#timeout()设置的请求超时是覆盖整个请求生命周期的全局超时——从调用请求发送方法开始，包含DNS解析、TCP连接建立、请求头/请求体发送、等待服务器响应、响应体接收的全部阶段。这和CXF 3.5.x及更早版本中仅在请求发送完成后等待响应时生效的套接字读取超时完全不同，也是大文件传输时发送过程中就触发超时关闭连接的核心原因。

问题2：为何CXF客户端未将此类超时以明确异常上报，如何更高效诊断这类超时问题？ #

CXF在适配JDK HttpClient时，没有对JDK HttpClient超时触发的连接关闭做专门的异常封装——JDK HttpClient超时后会直接断开TCP连接，导致底层流抛出java.io.IOException: Read end dead这类通用IO异常，而非更直观的TimeoutException。

高效诊断这类问题的方法：

• 开启JDK HttpClient的DEBUG级日志：通过代码或日志配置文件设置jdk.internal.httpclient的日志级别为FINEST，能直接看到超时触发的具体日志记录；
• 开启CXF HTTP传输层日志：将org.apache.cxf.transport.http的日志级别设为DEBUG，跟踪请求发送的进度，确认超时发生在哪个阶段；
• 自定义CXF异常拦截器：在客户端添加Phase.RECEIVE或Phase.SEND_END阶段的拦截器，捕获底层IO异常，结合日志上下文判断是否由超时导致，转换成业务侧更易识别的异常；
• 抓包验证：用Wireshark捕获TCP包，查看FIN包的触发时机是否与JDK HttpClient的超时日志时间吻合，确认是超时导致的连接关闭。

问题3：针对同时处理小文件（数KB）和大文件（最高10GB）的应用，应如何配置超时？是否需根据文件大小调整超时时长？ #

不能用单一的全局请求超时，需要拆分超时逻辑并根据场景动态调整，具体方案：

• 拆分超时类型：
  • 连接超时：设置较短的固定值（比如30秒），仅控制TCP连接建立的时间，不受文件大小影响；
  • 响应读取超时：对应原HTTPClientPolicy#setReceiveTimeout的逻辑，仅在请求体发送完成后等待服务器响应时生效，可设置固定值（比如5分钟）；
    注意：在CXF新版本中，需要通过HttpClientBuilderConfigurer定制JDK HttpClient的参数，用ResponseTimeoutHandler来单独设置响应读取超时，而非依赖全局请求超时。
• 大文件传输禁用全局请求超时：
  对于大文件，关闭JDK HttpClient的全局请求超时，改用分块传输（Transfer-Encoding: chunked），同时配置套接字读取超时——这样超时只会在等待服务器响应时触发，不会打断大文件的发送过程。
• 动态调整超时：
  根据文件大小计算动态超时值，比如设置基础超时（60秒）+ 每GB文件增加300秒的额外超时，在发送请求前通过CXF的API动态配置JDK HttpClient的超时参数。
• 启用HTTP/2：
  JDK HttpClient原生支持HTTP/2，对于大文件传输的效率更高，且超时处理更灵活，能减少因传输速率慢导致的不必要超时触发。

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