变更日志¶

4.x 版本¶

请参阅 4.x 变更日志查看稳定版本的变更日志。

5.0.0-alpha.14 版本¶

2024-04-17

重大变更：将 coroutines 扩展移动到 okhttp3.coroutines。之前此 artifact 与我们的核心模块共享 okhttp3 包名，这与 Java 平台模块系统不兼容。
修复 okhttp-coroutines：发布一个有效的 artifact。5.0.0-alpha.13 中的 coroutines JAR 文件已损坏，不应使用。

5.0.0-alpha.13 版本¶

2024-04-16

重大变更：将不稳定的新 API 标记为 @ExperimentalOkHttpApi。我们打算在不先稳定这些新 API 的情况下发布 OkHttp 5.0。

请勿在可能使用与编译模块时所用 OkHttp 版本不同的版本执行的模块中使用这些实验性 API。请勿在已发布的库中使用它们。如果您不愿意跟踪其更改，请勿使用它们。
重大变更：放弃对 Kotlin Multiplatform 的支持。

我们计划在 OkHttp 5.0 中支持多平台，但在构建之后，我们对实现上的权衡并不满意。我们无法在 Kotlin/JS 上使用我们的 HTTP 客户端引擎，并且我们尚未准备好为 Kotlin/Native 构建 TLS API。

我们更倾向于一个多平台 HTTP 客户端 API，该 API 在 Android 和 JVM 上由 OkHttp 提供支持，在其他平台上由其他引擎提供支持。Ktor 目前在这方面做得相当不错！
重大变更：在 OkHttpClient.Builder.callTimeout() 等 API 中使用 kotlin.time.Duration。此更新还放弃了对 OkHttp 5 早期 alpha 版本中引入的 DurationUnit 函数的支持。
重大变更：重新排列在 5.0.0-alpha.3 中引入的 Cache 构造函数中的参数顺序。
新增：Request.Builder.cacheUrlOverride() 用于自定义请求使用的缓存键。这可用于为缓存创建规范 URL，省略不重要的查询参数或其他无关数据。

此功能可用于 POST 请求以缓存其响应。在这种情况下，请求体不用于确定缓存键，因此您必须手动将与缓存相关的数据添加到覆盖 URL 中。例如，您可以添加一个 request-body-sha256 查询参数，以便具有相同 POST 数据的请求获得相同的缓存条目。
新增：HttpLoggingInterceptor.redactQueryParams() 配置要在日志中抹去的查询参数。为了最佳安全性，请勿将敏感信息放入查询参数中。
新增：ConnectionPool.setPolicy() 为目标地址配置最小连接池大小。使用此方法可以主动打开 HTTP 连接。

为满足此策略而打开的连接受连接池的 keepAliveDuration 限制，但不计入整个连接池的 maxIdleConnections 限制。

此功能会增加客户端的流量和服务器的负载。在采用此功能之前，请与您的服务器运营商沟通。
okhttp-android 新增：HttpLoggingInterceptor.androidLogging() 和 LoggingEventListener.androidLogging() 将 HTTP 调用或事件写入 Logcat。
新增：OkHttpClient.webSocketCloseTimeout 配置 WebSocket 连接在执行强制关闭之前等待正常关闭的时间。
修复：在 MultipartBody 中尊重 RequestBody.isOneShot()
修复 okhttp-coroutines：不要在 executeAsync() 中泄露响应体。我们之前有一个 bug，如果在协程返回其响应之前被取消，我们就不会调用 Response.close()。
升级：Okio 3.9.0。
升级：Kotlin 1.9.23。
升级：Unicode® IDNA 15.1.0

5.0.0-alpha.12 版本¶

2023-12-17

我们花了太长时间才发布此版本，其中包含许多更改。我们一直很忙。

尽管此版本被标记为 alpha，但其中唯一不稳定的内容是我们的新 API。此版本包含许多关键错误修复，可以安全地在生产环境中运行。我们渴望稳定我们的新 API，以便尽快脱离 alpha 阶段。

新增：支持 Java 21 的虚拟线程（'OpenJDK Project Loom'）。我们更改了 OkHttp 的内部实现，使用 Lock 和 Condition 代替 synchronized 以实现最佳资源利用率。
新增：将我们的国际化域名 (IDN) 实现切换到 UTS #46 Nontransitional Processing。通过此修复，代码点 ß 不再映射到 ss。OkHttp 现在在库中嵌入了其自己的 IDN 映射表。
新增：优先使用客户端配置的 TLS 密码套件优先级顺序。（OkHttp 之前优先使用 JDK 的优先级顺序。）此更改可能导致您的 HTTP 调用协商与之前不同的密码套件！OkHttp 的默认密码套件是为良好的安全性和性能而选择的。
新增：ConnectionListener 发布连接、断开连接和使用池化连接的事件。
修复：立即更新连接的流量控制窗口，而不是等待接收流处理它。

此更改可能会增加 OkHttp 对于执行大量并发 HTTP 调用且接收数据速度快于处理速度的应用程序的内存使用量。之前，OkHttp 将 HTTP/2 的每连接未确认数据限制为 16 MiB。通过此修复，现在每流未确认数据限制为 16 MiB，并且没有每连接限制。
修复：在使用 Deflater 压缩 WebSocket 消息时，不要关闭它。我们之前有一个严重的 bug，WebSocket 在错误的线程上关闭，导致 Deflater 中出现 NullPointerException 崩溃。
修复：WebSocket 连接升级失败后不会崩溃。我们之前错误地在 WebSocket 连接的资源清理之前将其释放回连接池。
修复：接收到的 WebSocket 消息包含自终止压缩数据时，不会陷入无限循环。
修复：当响应码为 'HTTP 102 Processing' 或 'HTTP 103 Early Hints' 时，不会导致调用失败。
修复：尊重拦截器对连接和读取超时的更改。
修复：当磁盘上缓存的响应损坏时，能够优雅地恢复。
修复：当缓存磁盘写入失败时，不会泄露文件句柄。
修复：公共后缀数据库加载失败时不会挂起。我们之前有一个 bug，读取公共后缀数据库失败会导致后续读取挂起，而实际上应该崩溃。
修复：在 MockWebServer 中避免使用 InetAddress.getCanonicalHostName()。这可以避免在主机 IP 地址有额外的 DNS 注册时出现问题。
新增：为 JavaNetCookieJar 创建一个与 JPMS 兼容的 artifact。之前，多个 OkHttp artifact 在 okhttp3 包中定义类，但这被 Java 模块系统禁止。我们通过一个新的包 (okhttp3.java.net.cookiejar) 和一个新的 artifact com.squareup.okhttp3:okhttp-java-net-cookiehandler 解决了这个问题。（原始 artifact 现在委托给这个新的 artifact。）
```
implementation("com.squareup.okhttp3:okhttp-java-net-cookiehandler:5.0.0-alpha.12")
```
新增：Cookie.sameSite 确定是否应在跨站请求中发送 Cookie。服务器使用此属性防御跨站请求伪造 (CSRF) 攻击。
新增：在 HttpLoggingInterceptor 中记录 HTTP 调用的总时间。
新增：OkHttpClient.Builder 现在具有使用 kotlin.time.Duration 的 API。
新增：mockwebserver3.SocketPolicy 现在是一个密封接口 (sealed interface)。这是可能影响此 alpha API 早期采用者的几项向后不兼容 API 更改之一。
新增：mockwebserver3.Stream 用于双工流。
新增：mockwebserver3.MockResponseBody 用于流式响应体。
新增：mockwebserver3.MockResponse 现在是不可变的，并带有 Builder。
新增：mockwebserver3.RecordedRequest.handshakeServerNames 返回 TLS 握手中的 SNI (Server Name Indication) 属性。
升级：Kotlin 1.9.21。
升级：Okio 3.7.0。

5.0.0-alpha.11 版本¶

2022-12-24

新增：默认启用快速回退（fast fallback）。这是我们对 Happy Eyeballs (RFC 8305) 的实现。使用 OkHttpClient.Builder.fastFallback(false) 禁用。
修复：不记录服务器发送事件的响应体。
修复：跳过早期提示 (状态码 103) 响应。
修复：不在 Request.toString() 中记录敏感头部信息。
修复：当调度器的 ExecutorService 在仍有许多排队调用时关闭，不会导致崩溃。
升级：GraalVM 22。
升级：Kotlin 1.7.10。

5.0.0-alpha.10 版本¶

2022-06-26

修复：为 Maven 构建配置多平台 artifact (com.squareup.okhttp3:okhttp:3.x.x) 依赖于 JVM artifact (com.squareup.okhttp3:okhttp-jvm:3.x.x)。这应该能解决 Maven 无法解释 Gradle 元数据的问题。
修复：再次尝试在运行时支持 Kotlin 1.5.31。我们之前在使用 1.5.x 中的 DurationUnit（这是一个 typealias）时导致崩溃。
升级：Okio 3.2.0。

5.0.0-alpha.9 版本¶

2022-06-16

新增：强制执行 URL 中的标签长度限制。HttpUrl 现在拒绝域名无效的 URL。这包括过长的域名（超过 253 个字符）、过长的标签（点之间超过 63 个字符）以及空标签。
新增：不在 multipart 请求体中包含 Content-Length 头部。服务器必须仅使用边界来分隔 OkHttp 的请求体。（此更改使 OkHttp 与浏览器和其他 HTTP 客户端更加一致。）
新增：删除 MockWebServer.useHttps() 中的 tunnelProxy 参数。此更改仅影响使用 mockwebserver3 包的 OkHttp 5.x API。
修复：不调用 toDuration()，因为它在 kotlin-stdlib 1.4 中不可用。

5.0.0-alpha.8 版本¶

2022-06-08

修复：更改 H2_PRIOR_KNOWLEDGE 与 HTTP 代理的工作方式。之前 OkHttp 假定代理本身是一个预知 HTTP/2 服务器。通过此更新，OkHttp 会尝试像 HTTPS 一样建立 CONNECT 隧道。对于带有代理的预知连接，OkHttp 现在与这些 curl 参数一致
```
curl \
  --http2-prior-knowledge \
  --proxy localhost:8888 \
  --proxytunnel \
  http://squareup.com/robots.txt
```
修复：支持在低至 1.4 版本的 kotlin-stdlib 上执行 OkHttp。该库仍然可以在最新的 Kotlin 版本 (1.6.21) 上构建，但不再需要该版本作为运行时依赖项。这应该能更容易地在 Gradle 插件中使用 OkHttp。
修复：直到请求体完全传输完毕后才开始计算响应超时。这仅与双工请求体有关，因为它们在读取响应体时会同时写入。
新增：MockResponse.inTunnel() 是一个新的 mockwebserver3 API，用于配置在创建代理隧道时提供的响应。这废弃了 MockWebServer 上的 tunnelProxy 参数和 UPGRADE_TO_SSL_AT_END 套接字选项。（仅 mockwebserver3 上的 API 发生了变化；旧的 okhttp3.mockwebserver API 保持不变。）

5.0.0-alpha.7 版本¶

2022-04-26

此版本引入了新的 Kotlin 友好型 API。 当我们在 OkHttp 4.0 中将 OkHttp 从 Java 迁移到 Kotlin 时，我们保留了 Java 优先的 API。在 5.0 中，我们将继续支持 Java，并为 Kotlin 用户增加额外的改进。在此 alpha 版本中，我们很高兴能跳过请求的 Builder 模式，并消除了响应体上常见的非空断言 (!!) 来源。

5.0.0 系列的 alpha 版本具有生产质量的代码和不稳定的 API。我们预计会对 5.0.0-alpha.X 中引入的 API 进行更改。这些版本可安全用于生产环境，并且 'alpha' 严格表示我们仍在尝试一些新 API。如果您急需以下修复或功能，请升级。

新增：Request 的命名参数和默认参数构造函数

val request = Request(
  url = "https://cash.app/".toHttpUrl(),
)

新增：Response.body 现在是非空的。在 OkHttp 4.x 中通常就是这样，但 Kotlin 类型声明是可空的，以支持诸如 Response.cacheResponse、Response.networkResponse 和 Response.priorResponse 上的响应体等罕见情况。在这种情况下，响应体现在是非空的，但尝试读取其内容将失败。
新增：用于请求标签的 Kotlin 特定 API。Kotlin 用户只能使用类型参数查找标签，例如 request.tag<MyTagClass>()。
新增：MockWebServer 对 HTTP/1xx 响应的支持得到改进。迁移到新的 mockwebserver3 包后，新增了一个字段 MockResponse.informationalResponses。
修复：在 HTTP/100 响应后不将 trailers 解释为 headers。这仅在 HTTP 响应体本身为空时才是一个 bug。
修复：当快速回退调用同时具有延迟连接和已持有连接时，不会崩溃。
修复：OkHttpClient 不再实现 Cloneable。它本就不应该实现；该类是不可变的。这是 OkHttp 2.x (!) 时期遗留下来的，当时该类是可变的。我们利用 5.x 升级的机会删除了非常过时的 API。
修复：当 Android 的 NativeCrypto 因 "ssl == null" 崩溃时，能够优雅地恢复。这发生在 OkHttp 在已关闭连接上检索 ALPN 状态时。
升级：Kotlin 1.6.21。
升级：Okio 3.1.0。

5.0.0-alpha.6 版本¶

2022-03-14

修复：不尝试关闭池化连接。我们在之前的 alpha 版本中发现偶尔的快速回退调用由于意外的竞争条件而崩溃。

5.0.0-alpha.5 版本¶

2022-02-21

修复：不在 OkHttp 的生产依赖项中包含 Assertk。此回归是在 5.0.0-alpha.4 版本中引入的。
修复：不要求 Dns 实现解析已经是 IP 地址的字符串。
修复：将快速回退更改为仅竞赛 TCP 握手。为了避免浪费工作，OkHttp 不会为同一调用并发尝试多次 TLS 握手。
修复：在 GraalVM 本机镜像中加载公共后缀数据库时不会崩溃。函数 HttpUrl.topPrivateDomain() 使用资源文件识别私有域，但我们在 GraalVM 上未包含此文件。

5.0.0-alpha.4 版本¶

2022-02-01

此版本引入了快速回退 (fast fallback)，以更好地支持 IPv4+IPv6 混合网络。 快速回退是我们对 Happy Eyeballs (RFC 8305) 的实现。通过此功能，OkHttp 将同时尝试 IPv6 和 IPv4 连接，并保留首先建立连接的那个。快速回退为 IPv6 连接提供了 250 毫秒的提前启动时间，以便在可用 IPv6 的网络中优先使用 IPv6。

要选择启用此功能，请配置您的 OkHttpClient.Builder

OkHttpClient client = new OkHttpClient.Builder()
    .fastFallback(true)
    .build();

新增：将构建从 Kotlin-JVM 更改为 Kotlin-multiplatform（包含 JVM）。原生和 JavaScript 平台都是不稳定的预览版本，在后续版本中可能会出现向后不兼容的更改。
修复：在混淆构建中加载公共后缀数据库资源时不会崩溃。
修复：不要静默忽略从 EventSourceListener.onOpen() 调用 EventSource.cancel()。
修复：在使用 Conscrypt 固定证书时，强制执行最大中间证书约束。当服务器提供的证书链同时形成受信任但未固定的链和不受信任但已固定的链时，这会影响 Conscrypt。
升级：Kotlin 1.6.10。

5.0.0-alpha.3 版本¶

2021-11-22

修复：更改 Headers.toString() 以抹去授权和 cookie 头部信息。
修复：不执行 DNS 来获取 RecordedRequest.requestUrl 的主机名。这之前是在对本地主机名进行 DNS 查找，但我们实际上只需要 Host 头部。
修复：在 Java 17+ 上检测平台信任管理器时，不会因 InaccessibleObjectException 崩溃。
修复：如果 cookie 的值是单个双引号字符，不会崩溃。
修复：取消由 EventSources.processResponse() 创建的事件源时，不会崩溃。
新增：Cache 现在有一个公共构造函数，接受一个 [okio.FileSystem] 参数。这使得实现用于缓存加密或压缩的装饰器成为可能。
新增：Cookie.newBuilder()，用于基于现有 cookie 构建新 cookie。
新增：在 JDK 8u261 或更高版本上运行时使用 TLSv1.3。
新增：QueueDispatcher.clear() 可用于重置 MockWebServer 实例。
新增：FileDescriptor.toRequestBody() 对于 Android 的存储访问框架用户特别有用。
升级：Kotlin 1.5.31。
升级：Okio 3.0.0。

5.0.0-alpha.2 版本¶

2021-01-30

在此版本中，MockWebServer 具有新的 Maven 坐标和包名。 MockWebServer 存在一个长期问题，即其 API 依赖于 JUnit 4。我们重新组织了代码，在保留向后兼容性的同时消除了该依赖项。

Maven 坐标	包名	描述
com.squareup.okhttp3:mockwebserver3:5.0.0-alpha.2	mockwebserver3	核心模块。无 JUnit 依赖！
com.squareup.okhttp3:mockwebserver3-junit4:5.0.0-alpha.2	mockwebserver3.junit4	可选的 JUnit 4 集成。
com.squareup.okhttp3:mockwebserver3-junit5:5.0.0-alpha.2	mockwebserver3.junit5	可选的 JUnit 5 集成。
com.squareup.okhttp3:mockwebserver:5.0.0-alpha.2	okhttp3.mockwebserver	已废弃。依赖于 JUnit 4。

新的 API 在 Maven 坐标和包名中都使用 mockwebserver3。这个新的 API 是不稳定的，在最终的 5.0.0 版本发布之前很可能会发生变化。

如果您有代码继承自 okhttp3.mockwebserver.QueueDispatcher，则此更新与源代码或二进制不兼容。迁移到新的 mockwebserver3 包将解决此问题。

新增：DNS over HTTPS 现在是 OkHttp 的一个稳定功能。我们在 2018 年将其作为实验性模块引入。我们对其稳定的 API 和可靠的实现充满信心。
修复：解决 Android 10 和 11 中可能由两个线程并发关闭 SSL 套接字触发的崩溃问题。这会在崩溃日志中显示为 NullPointerException: bio == null。
修复：在 FormBody 中使用加号 + 代替 %20 来编码空格字符。这是 OkHttp 中一个长期存在的 bug。此修复使 OkHttp 与主流 Web 浏览器保持一致。
修复：如果 Conscrypt 返回 null 版本，不会崩溃。
修复：在 GraalVM 本机镜像中将公共后缀数据作为资源包含。
修复：当缓存损坏时快速失败。
修复：当私钥无法编码时快速失败。
修复：尝试验证非 ASCII 主机名时快速失败。
升级：GraalVM 21。
升级：Kotlin 1.4.20。

5.0.0-alpha.1 版本¶

2021-01-30

此版本增加了对 GraalVM 的初步支持。

GraalVM 是一个令人兴奋的新平台，我们渴望采用它。与 JVM 相比，其启动时间的改进尤其令人印象深刻。请使用 okcurl 尝试它

$ ./gradlew okcurl:nativeImage
$ ./okcurl/build/graal/okcurl https://cash.app/robots.txt

这是我们第一个支持 GraalVM 的版本。我们在此平台上的代码不如 JVM 和 Android 成熟！请报告您遇到的任何问题：我们将紧急修复它们。

修复：即使服务器取消了请求，也会尝试读取响应体。这将导致某些调用返回如 HTTP/1.1 429 Too Many Requests 等友好的错误码，而不是 SocketException: Connection reset 和 StreamResetException: stream was reset: CANCEL 等传输错误。
新增：支持 OSGi 元数据。

升级：Okio 2.9.0。

implementation("com.squareup.okio:okio:2.9.0")

请注意，此版本最初于 2020 年 10 月 6 日以 4.10.0-RC1 发布。与该版本唯一的区别是版本名称。