OkHttp 3.x 变更日志

版本 3.14.9

2020-05-17

• 修复：在 Android Studio Canary 4.1 中作为插件运行时不会崩溃。为了启用特定平台的 TLS 特性，OkHttp 必须检测它是在 JVM 中运行还是在 Android 中运行。即将发布的 Android Studio 在 JVM 中运行，但包含 Android 的类，这导致 OkHttp 混乱！

版本 3.14.8

2020-04-28

• 修复：在 Java 8u252 上不会崩溃，该版本引入了之前仅在 Java 9 及更高版本中才有的 API。请参阅 Jetty 的 API 更改概述及其后果。

版本 3.14.7

2020-02-24

• 修复：由于使用了受限制的方法，在 Android 11 上不会崩溃。这可以防止出现“Expected Android API level 21+ but was 29”异常导致的崩溃。

版本 3.14.6

2020-01-11

• 修复：在发送降级 ping 时连接关闭不会崩溃。这修复了 OkHttp 3.14.5 中引入的回归错误。

版本 3.14.5

2020-01-03

• 修复：在超时后降级 HTTP/2 连接。当 HTTP/2 流超时时，它可能仅影响该流或整个连接。通过此修复，OkHttp 现在将在流超时后发送 HTTP/2 ping，以确定连接是否应保持可用于连接池。

版本 3.14.4

2019-09-29

• 修复：取消由于意外异常而失败的调用。我们曾有一个 bug，一个入队的调用如果由于未受检查的可抛异常（例如 NullPointerException 或 OutOfMemoryError）而崩溃，则永远不会回调。现在，我们使用 IOException 调用 Callback.onFailure()，报告调用已取消。触发异常仍会传递给线程的 UncaughtExceptionHandler。
• 修复：在迭代缓存时不会驱逐不完整的条目。我们曾有一个 bug，迭代 Cache.urls() 会阻止正在写入的条目被写入。

版本 3.14.3

2019-09-10

• 修复：当传入数据与流关闭竞争时，不会丢失 HTTP/2 流控制字节。如果这种情况发生足够多次，连接最终会停滞。

• 修复：原子地确认并应用入站 HTTP/2 设置。之前我们存在竞争条件，可能会在确认之前使用新的流控制容量，导致严格的 HTTP/2 服务器使调用失败。

• 修复：当合并的连接立即变为不健康时，能正常恢复。

版本 3.14.2

2019-05-19

• 修复：从 HTTP/2 连接错误中恢复时锁定路由。我们曾有一个 bug，两个同时失败的调用可能导致 OkHttp 崩溃，出现 NoSuchElementException，而不是预期的 IOException。

• 修复：在格式化描述来自 HTTPS 代理的截断响应的错误消息时，不会因为 NullPointerException 崩溃。

版本 3.14.1

2019-04-10

• 修复：当没有更多路由时，拦截器重试不会崩溃。这是 3.14.0 事件清理引入的一个边缘情况回归。

• 修复：当交换非空时提供可操作的建议。在 3.14 之前，当拦截器在没有关闭响应体的情况下重试时，OkHttp 会静默地泄漏连接。在 3.14 中，我们检测到了这个问题，但异常信息没有帮助。

版本 3.14.0

2019-03-14

• 此版本删除了长期弃用的 OkUrlFactory 和 OkApacheClient API。 这些外观将 OkHttp 的实现隐藏在另一个客户端的 API 之后。如果您仍然需要此功能，请将 ObsoleteUrlFactory.java 或 ObsoleteApacheClient.java 复制粘贴到您的项目中。

• OkHttp 现在支持通过 HTTP/2 进行双工调用。 对于普通的 HTTP 调用，请求必须在响应开始之前完成。对于双工调用，请求体和响应体同时传输。这可用于在单个 HTTP 调用中实现交互式对话。

  通过覆盖新的 RequestBody.isDuplex() 方法返回 true 来创建双工调用。这个简单的选项极大地改变了请求体和整个调用的行为。

  RequestBody.writeTo() 方法现在可以保留对提供的 sink 的引用，并在 writeTo 返回后将其交给另一个线程写入。

  EventListener 现在可能看到请求和响应以以前不允许的方式交错出现。例如，监听器可能收到 responseHeadersStart()，然后是 requestBodyEnd()，两者都在同一个调用上。即使对于单个调用，此类事件也可能由不同的线程触发。

  重写或替换请求体的拦截器现在可能会无意中干扰双工请求体。此类拦截器应检查 RequestBody.isDuplex() 并在双工时避免访问请求体。

  双工调用需要 HTTP/2。如果代わりに建立了 HTTP/1，则双工调用将失败。双工调用最常见的用例是 gRPC。

• 新增：通过覆盖 RequestBody.isOneShot() 防止 OkHttp 重传请求体。这在写入请求体具有破坏性时最有用。

• 新增：我们在 EventListener 中添加了 requestFailed() 和 responseFailed() 方法。在某些失败情况下，会调用这些方法，而不是 requestBodyEnd() 和 responseBodyEnd()。它们也可能在之前未发布事件的情况下触发。在此版本中，我们对事件代码进行了内部重写，以修复事件丢失或不平衡的问题。

• 修复：在 onFailure() 回调紧接之前取消调用时，不会泄漏连接。

• 修复：在连接双工调用、web sockets 和 server-sent events 时应用调用超时。一旦流建立，将不再强制执行进一步的超时。

• 修复：在重定向或其他后续操作中重用连接时保留 Route。这导致一些 Authenticator 调用在预期非空时看到 null 路由。

• 修复：在 TLS_AES_128_CCM_8_SHA256 的名称中使用正确的密钥大小，它是一个 TLS 1.3 密码套件。我们意外地指定了 256 的密钥大小，阻止了该密码套件在任何 TLS 握手时被选择。我们没有注意到，因为 Android、Java 或 Conscrypt 都不支持此密码套件。

  我们从受限、现代和兼容的密码套件集中删除了此密码套件和 TLS_AES_128_CCM_SHA256。Firefox 和 Chrome 中默认均未启用这两个密码套件。

  有关 OkHttp 默认 TLS 选项的所有更改日志，请参阅我们的 TLS 配置历史跟踪器。

• 新增：升级到 Conscrypt 2.0.0。OkHttp 可与其他版本的 Conscrypt 一起使用，但这是我们正在测试的版本。

  implementation("org.conscrypt:conscrypt-openjdk-uber:2.0.0")
  

• 新增：更新嵌入式公共后缀列表。

版本 3.13.1

2019-02-05

• 修复：在 Android 上使用自定义 X509TrustManager 或 SSLSocket 时不会崩溃。当我们删除 Android 4.4 的过时代码时，意外地也删除了对自定义子类的支持。我们已恢复该支持！

版本 3.13.0

2019-02-04

• 此版本将我们的最低要求提高到 Java 8+ 或 Android 5+。 停止支持旧设备是一个重大改变，我们不会轻易做出！这篇文章解释了我们这样做的原因以及如何升级。

  OkHttp 3.12.x 分支将是我们的 Android 2.3+ (API level 9+) 和 Java 7+ 的长期分支。这些平台缺乏对 TLS 1.2 的支持，不应使用。但由于升级困难，我们将在 2021 年 12 月 31 日之前（此承诺最初到 2020 年 12 月 31 日；我们已延长）向 3.12.x 分支反向移植关键修复。

• TLSv1 和 TLSv1.1 默认不再启用。 主要网络浏览器正在努力在 2020 年初彻底移除这些版本。如果您的服务器尚未准备好，您可以将 OkHttp 3.13 配置为允许 TLSv1 和 TLSv1.1 连接

  OkHttpClient client = new OkHttpClient.Builder()
      .connectionSpecs(Arrays.asList(ConnectionSpec.COMPATIBLE_TLS))
      .build();
  

• 新增：您现在可以使用 Response.trailers() 访问 HTTP trailers。此方法只能在读取整个 HTTP 响应体之后调用。

• 新增：升级到 Okio 1.17.3。如果您使用的是 Kotlin 友好的 Okio 2.x，此版本需要 2.2.2 或更高版本。

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

• 修复：发送 HTTP/2 请求头时不会遗漏取消。

• 修复：调用重定向时不会遗漏整个操作超时。
• 修复：如果 web sockets 的响应格式错误或 onOpen() 抛出异常，不会泄漏连接。
• 修复：由于 FileNotFoundException 导致请求体失败时不会重试。
• 修复：当 URL 包含 IPv4-mapped IPv6 地址时不会崩溃。
• 修复：在 Android API 28 上构建 HandshakeCertificates 时不会崩溃。
• 修复：允许 multipart 文件名包含非 ASCII 字符。
• 新增：获取 MockWebServer 调度器的 API。
• 新增：以 java.time.Instant 访问头的 API。
• 新增：如果 SSLSocketFactory 被用作 SocketFactory，则快速失败。
• 新增：在 LoggingEventListener 中记录 TLS 握手。

版本 3.12.13

2021-01-30

• 修复：解决 Android 10 和 11 中的崩溃问题，该问题可能在两个线程同时关闭 SSL socket 时触发。这会在崩溃日志中显示为 NullPointerException: bio == null。

版本 3.12.12

2020-05-17

• 修复：在 Android Studio Canary 4.1 中作为插件运行时不会崩溃。为了启用特定平台的 TLS 特性，OkHttp 必须检测它是在 JVM 中运行还是在 Android 中运行。即将发布的 Android Studio 在 JVM 中运行，但包含 Android 的类，这导致 OkHttp 混乱！

版本 3.12.11

2020-04-28

• 修复：在 Java 8u252 上不会崩溃，该版本引入了之前仅在 Java 9 及更高版本中才有的 API。请参阅 Jetty 的 API 更改概述及其后果。

版本 3.12.10

2020-02-29

• 修复：在 Android 4.1 上检测到在 Android 11 中成为受限制的方法时不会崩溃。在我们的 3.12.x 分支上支持整整十年的 Android 版本是很棘手的！

版本 3.12.9

2020-02-24

• 修复：由于使用了受限制的方法，在 Android 11 上不会崩溃。这可以防止出现“Expected Android API level 21+ but was 29”异常导致的崩溃。

版本 3.12.8

2020-01-11

• 修复：在发送降级 ping 时连接关闭不会崩溃。这修复了 OkHttp 3.12.7 中引入的回归错误。

版本 3.12.7

2020-01-03

• 修复：在超时后降级 HTTP/2 连接。当 HTTP/2 流超时时，它可能仅影响该流或整个连接。通过此修复，OkHttp 现在将在流超时后发送 HTTP/2 ping，以确定连接是否应保持可用于连接池。

版本 3.12.6

2019-09-29

• 修复：取消由于意外异常而失败的调用。我们曾有一个 bug，一个入队的调用如果由于未受检查的可抛异常（例如 NullPointerException 或 OutOfMemoryError）而崩溃，则永远不会回调。现在，我们使用 IOException 调用 Callback.onFailure()，报告调用已取消。触发异常仍会传递给线程的 UncaughtExceptionHandler。
• 修复：在迭代缓存时不会驱逐不完整的条目。我们曾有一个 bug，迭代 Cache.urls() 会阻止正在写入的条目被写入。

版本 3.12.5

2019-09-10

• 修复：当传入数据与流关闭竞争时，不会丢失 HTTP/2 流控制字节。如果这种情况发生足够多次，连接最终会停滞。

• 修复：原子地确认并应用入站 HTTP/2 设置。之前我们存在竞争条件，可能会在确认之前使用新的流控制容量，导致严格的 HTTP/2 服务器使调用失败。

版本 3.12.4

2019-09-04

• 修复：在某些有 bug 的 Android 4.x 设备上查找不存在的类时不会崩溃。

版本 3.12.3

2019-05-07

• 修复：允许 multipart 文件名包含非 ASCII 字符。
• 修复：在重定向或其他后续操作中重用连接时保留 Route。这导致一些 Authenticator 调用在预期非空时看到 null 路由。

版本 3.12.2

2019-03-14

• 修复：如果 HTTPS 服务器在 TLS 握手中不返回任何证书，则不会崩溃。
• 修复：在 onFailure() 回调紧接之前取消调用时，不会泄漏连接。

版本 3.12.1

2018-12-23

• 修复：移除重叠的 package-info.java。这导致某些构建工具出现问题。

版本 3.12.0

2018-11-16

• OkHttp 现在支持 TLS 1.3。 这需要 Conscrypt 或 Java 11+。

• 代理身份验证器现在会被要求进行抢先身份验证。 OkHttp 现在将在通过 HTTP 代理（HTTP CONNECT）创建 TLS 隧道之前请求身份验证凭据。身份验证器应通过方案为“OkHttp-Preemptive”的挑战来识别抢先身份验证。

• OkHttp 现在提供全程操作超时。 这设定了整个调用可能花费的时间限制，涵盖解析 DNS、连接、写入请求体、服务器处理和读取完整响应体。如果调用需要重定向或重试，所有这些必须在一个超时周期内完成。

  使用 OkHttpClient.Builder.callTimeout() 指定默认持续时间，使用 Call.timeout() 指定单个调用的超时时间。

• 新增：返回值和字段现在是非空的，除非另有标注。

• 新增：LoggingEventListener 使轻松了解调用的基本性能成为可能。此类位于 logging-interceptor artifact 中。
• 新增：Headers.Builder.addUnsafeNonAscii() 允许添加非 ASCII 值而不会立即抛出异常。
• 新增：可以在 HttpLoggingInterceptor 中隐藏头部信息。
• 新增：Headers.Builder 现在接受日期。
• 新增：OkHttp 现在在 Java 8+ 和 Android 26+ 上接受 java.time.Duration 作为超时参数。
• 新增：Challenge 包含所有身份验证参数。

• 新增：升级到 BouncyCastle 1.60、Conscrypt 1.4.0 和 Okio 1.15.0。我们尚不要求 Kotlin 友好的 Okio 2.x，但 OkHttp 可以很好地与该系列版本兼容。

  implementation("org.bouncycastle:bcprov-jdk15on:1.60")
  implementation("org.conscrypt:conscrypt-openjdk-uber:1.4.0")
  implementation("com.squareup.okio:okio:1.15.0")
  

• 修复：优雅地处理调度器 executor 关闭。当没有线程来执行调用时，其回调现在会接收到 RejectedExecutionException。

• 修复：不会永久缓存带有 Cache-Control: immutable 的响应。我们误解了最初的 immutable 提案！
• 修复：将 Authenticator 的 Route 参数更改为可空。此参数标记为非空，但在某些情况下可能会传入 null。
• 修复：当通过 IPv6 地址访问 MockWebServer 时，不会创建格式错误的 URL。
• 修复：如果系统默认身份验证器为 null，则不会崩溃。
• 修复：在 Android 上生成椭圆曲线证书时不会崩溃。
• 修复：在 RoboVM 上进行平台检测时不会崩溃。
• 修复：当 web socket 升级失败时不会泄漏 socket 连接。

版本 3.11.0

2018-07-12

• OkHttp 的新 okhttp-tls 子模块驯服了 HTTPS 和 TLS。

  HeldCertificate 是一个 TLS 证书及其私钥。使用其构建器生成证书，然后使用它来签署另一个证书或执行 TLS 握手。certificatePem() 方法以熟悉的 PEM 格式（--- BEGIN CERTIFICATE ---）编码证书；privateKeyPkcs8Pem() 以类似的方式编码私钥。

  HandshakeCertificates 保存了 TLS 握手所需的 TLS 证书。在服务器端，它保存您的 HeldCertificate 及其链。在客户端，它保存用于签署服务器证书链的受信任根证书。HandshakeCertificates 也适用于互相 TLS，角色互换。

  这些类使得在 MockWebServer 中仅需 几行代码 即可启用 HTTPS。

• OkHttp 现在支持“先前知识”的明文 HTTP/2。 通过在 OkHttpClient.Builder 上将 Protocol.H2_PRIOR_KNOWLEDGE 设置为唯一的协议来启用此功能。此模式仅支持 http: URL，最适合在 HTTPS 不适合的封闭环境中使用。

• 新增：HttpUrl.get(String) 是 HttpUrl.parse(String) 的替代方法，当 URL 格式错误时会抛出异常而不是返回 null。在已知输入格式正确的情况下，使用此方法可以避免检查 null。我们还添加了 MediaType.get(String)，它是 MediaType.parse(String) 的一个抛出异常的替代方法。

• 新增：在 OkHttp 3.9 中预览的 EventListener API 已升级为稳定 API。使用此接口跟踪指标并监控 HTTP 请求的大小和持续时间。
• 新增：okhttp-dnsoverhttps 是一个实验性的 API，用于通过 HTTPS 进行 DNS 查询。使用 HTTPS 进行 DNS 查询可提供更好的安全性和潜在的更好性能。此功能为预览版：API 可能更改。
• 新增：okhttp-sse 是 Server-Sent Events (SSE) 的早期预览版。此功能尚不完整，仅适合实验性使用。
• 新增：MockWebServer 现在支持客户端身份验证（相互 TLS）。调用 requestClientAuth() 以允许可选的客户端证书，或调用 requireClientAuth() 以要求客户端证书。
• 新增：RecordedRequest.getHandshake() 返回发送到 MockWebServer 的请求的 HTTPS 握手信息。
• 修复：在 MockWebServer 中遵循 MockResponse 头部延迟。
• 修复：不会释放具有多个取消调用的 HTTP/2 连接。我们有一个 bug，取消调用会导致共享的 HTTP/2 连接被不必要地释放。这损害了连接重用。
• 修复：确保取消和丢弃的 HTTP/2 数据不会永久计入有限的流量控制窗口。我们有一些 bug，当流被取消或重置时，窗口大小记账会出错。
• 修复：如果 TLS 会话返回意外的版本（NONE）或密码套件（SSL_NULL_WITH_NULL_NULL），能正常恢复。
• 修复：不会全局更改 Conscrypt 配置。我们从进程范围的设置迁移到仅配置 OkHttp 的 TLS sockets。
• 修复：优先使用 TLSv1.2（如果可用）。在某些较旧的平台上，需要选择加入 TLSv1.2。
• 新增：Request.tag() 允许使用多个标签。使用 Class<?> 作为键来识别标签。请注意，如果请求没有标签，tag() 现在返回 null。以前它会返回请求本身。
• 新增：Headers.Builder.addAll(Headers)。
• 新增：ResponseBody.create(MediaType, ByteString)。
• 新增：将 R8/ProGuard 规则嵌入到 jar 中。这些规则将由 R8 自动应用。
• 修复：如果 Authenticator 抛出异常，则释放连接。
• 修复：更改 OkHttpClient.cache() 的声明以返回 @Nullable Cache。返回值一直可以为 null，但之前没有正确声明。
• 修复：反转连接异常的抑制。当调用及其重试都失败时，我们现在抛出最初的异常，该异常最有可能提供可操作的信息。
• 修复：在抛出 InterruptedIOException 时保留中断状态。现在，一个中断应该足以中断正在进行的 OkHttp 调用。
• 修复：当响应体在拦截器内部被消费时，不会丢弃对 EventListener.callEnd() 的调用。

版本 3.10.0

2018-02-24

• pingInterval() 功能现在会积极检查 web sockets 和 HTTP/2 连接的连接性。

  以前，如果您配置了一个 ping 间隔，OkHttp 会发送 ping，但它不会跟踪是否收到了回复 pong。通过此更新，OkHttp 要求每个 ping 必须收到响应：如果未收到，连接将被关闭，并调用监听器的 onFailure() 方法。

  Web sockets 一直有 ping，但在 HTTP/2 连接上的 ping 是此版本新增的功能。Ping 用于正在处理调用的连接和连接池中的空闲连接。（Ping 不影响池化连接的驱逐时间）。

  如果您配置了 ping 间隔，应确认其足够长，以容纳客户端到服务器的往返时间。如果您的 ping 间隔太短，慢速连接可能会被误解为失败的连接。对于大多数用例而言，30 秒的 ping 间隔是合理的。

• OkHttp 现在支持 Conscrypt。 Conscrypt 是一个将 BoringSSL 集成到 Java 平台的 Java 安全提供者。Conscrypt 支持比 JVM 默认提供者更多的密码套件，并且可能更高效地执行。

  要使用它，首先在您的构建系统中注册 Conscrypt 依赖。

  如果您将 okhttp.platform 系统属性设置为 conscrypt，OkHttp 将使用 Conscrypt。

  或者，如果您将其安装为首选安全提供者，OkHttp 也会使用 Conscrypt。为此，请在创建 OkHttpClient 之前添加以下代码。

  Security.insertProviderAt(
      new org.conscrypt.OpenSSLProvider(), 1);
  

  Conscrypt 是 Android 上捆绑的安全提供者，因此无需在该平台上配置它。

• 新增：HttpUrl.addQueryParameter() 对更多字符进行百分号转义。以前，使用此方法时不会对某些 ASCII 标点符号进行百分号转义。这不会影响在 HttpUrl.parse() 和 HttpUrl.Builder.addEncodedQueryParameter() 等 API 中已编码的查询参数。

• 新增：CBC 模式的 ECDSA 密码套件已从 OkHttp 的默认配置中移除：TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 和 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA。这遵循了 Chromium 的更改，以移除这些密码套件，因为它们脆弱且很少使用。
• 新增：对于主机名，不再回退到通用名称 (CN) 验证。此行为在 2000 年 5 月的 RFC 2818 中已弃用，最近已被主要网络浏览器弃用。
• 新增：遵循 Retry-After 响应头。如果存在此头部且延迟为 0 秒，HTTP 503 (Unavailable) 响应会自动重试。如果头部不存在或延迟为 0 秒，HTTP 408 (Client Timeout) 响应会自动重试。
• 新增：允许除 GET 和 HEAD 之外的所有 HTTP 方法都包含请求体。
• 新增：与 Java 平台模块系统一起使用的自动模块名称 okhttp3。
• 新增：当 HttpLoggingInterceptor 用作网络拦截器时，记录 gzipped 响应体。
• 新增：Protocol.QUIC 常量。此协议不受支持，但此常量是为了完整性而包含的。

• 新增：升级到 Okio 1.14.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.14.0</version>
  </dependency>
  
  com.squareup.okio:okio:1.14.0
  

• 修复：处理 HTTP/1.1 100 Continue 状态行，即使对于未发送 Expect: continue 请求头的请求也是如此。

• 修复：不会将 web sockets 计入调度器的每主机连接限制。
• 修复：避免使用无效的 HTTPS 会话。这可以防止 OkHttp 崩溃并出现错误 Unexpected TLS version: NONE。
• 修复：当 304 (Not Modified) 响应覆盖存储的“Content-Encoding”头部时，不会损坏响应缓存。
• 修复：在耗尽流 ID 命名空间（约 5.36 亿个流）之前，优雅地关闭 HTTP/2 连接。
• 修复：绝不向 Authenticator 传递 null Route。曾有一个 bug，对于过早关闭的连接，会省略路由。

版本 3.9.1

2017-11-18

• 新增：当 Android 的 DNS 因意外的 NullPointerException 崩溃时，能正常恢复。
• 新增：当 Android 的 socket 连接因意外的 ClassCastException 崩溃时，能正常恢复。
• 修复：当查询本身为空时，不会在 encodedQuery() 中包含 URL 的 fragment。

版本 3.9.0

2017-09-03

• 拦截器功能更强大。 Chain 接口现在可以访问调用并调整所有调用超时。请注意，此更改对于实现 Chain 接口的代码是源不兼容的。我们预计这在实践中不会成为问题！

• OkHttp 有一个实验性的新 API 用于跟踪指标。 新的 EventListener API 旨在帮助开发者监控 HTTP 请求的大小和持续时间。此功能是一个不稳定的预览版：API 可能更改，实现不完整。这是一个重要的新 API，我们渴望收到反馈。

• 新增：通过 Google Play Services 的动态安全提供者支持 ALPN。这将 HTTP/2 支持扩展到具有 Google Play Services 的旧版 Android 设备。

• 新增：查找候选合并连接时考虑所有路由。这增加了共享 HTTP/2 连接的可能性。
• 新增：身份验证挑战和凭据现在使用字符集。在您的身份验证器中使用此功能支持包含非 ASCII 字符的用户名和密码。
• 新增：在 FormBody.Builder 中接受字符集。以前，表单体始终是 UTF-8。
• 新增：支持 immutable 缓存控制指令。
• 修复：当 HTTP/2 调用在连接关闭时被重定向时，不会崩溃。
• 修复：不会丢弃与 GOAWAY 帧竞争的健康流的头部。此 bug 会导致 HTTP/2 流在连接关闭时偶尔挂起。
• 修复：当响应为 HTTP 408 Request Timeout 时，遵循 OkHttpClient.retryOnConnectionFailure()。如果启用了重试，OkHttp 在收到 408 响应时会精确重试一次。
• 修复：如果空的 HEAD 响应体指定了 Content-Length，读取时不会崩溃。
• 修复：如果在读取公共后缀数据库时线程被中断，不会崩溃。
• 修复：加载公共后缀数据库时使用相对资源路径。使用相对于类的路径加载资源可防止在 OkHttp 类被重新定位（shaded）时发生冲突，从而允许存在多个私有数据库副本。
• 修复：接受主机为 IPv6 地址的 URL 的 cookie。
• 修复：如果在协议尚未协商时，不在 HttpLoggingInterceptor 中记录协议（HTTP/1.1, h2）！以前我们默认记录 HTTP/1.1，这令人困惑。
• 修复：从 MockWebServer 的 HTTP/2 :status 头部中省略消息。
• 修复：在 MockWebServer 中正确处理 ‘Expect: 100 Continue’。

版本 3.8.1

2017-06-18

• 修复：优雅地从过时的合并连接中恢复。我们有一个 bug，连接合并（在 OkHttp 3.7.0 中引入）和过时连接恢复可能相互作用，导致 RouteSelector 中出现 NoSuchElementException 崩溃。

版本 3.8.0

2017-05-13

• OkHttp 现在使用 @Nullable 标注所有可能为 null 的值。 我们添加了对 JSR 305 注解的编译时依赖。这是一个 提供的 依赖，无需包含在您的构建配置、.jar 文件或 .apk 中。我们使用 @ParametersAreNonnullByDefault，所有参数和返回类型除非明确标注 @Nullable，否则绝不为 null。

• 警告：此版本对于 Kotlin 用户是源不兼容的。 可空性以前模糊不清且宽松，但现在编译器将强制执行严格的 null 检查。

• 新增：响应消息现在非空。这就是状态行“HTTP 404 Not Found”中的“Not Found”。如果您正在以编程方式构建响应（使用 new Response.Builder()），现在必须始终提供一个消息。允许使用空字符串 ""。OkHttp 本身返回的响应消息从未为空，允许应用程序代码省略消息曾是一个历史错误。

• 质询的方案（scheme）和领域（realm）现在非空。如果您正在调用 new Challenge(scheme, realm)，则必须提供非空值。这些值在 OkHttp 创建的质询中从未为空，但在创建质询的应用程序代码中可能为空。

• 新增：Handshake 的 TlsVersion 现在非空。如果您调用 Handshake.get() 时提供 null 作为 TLS 版本，现在必须改为提供非空的 TlsVersion。在 OkHttp 3.0 之前持久化的缓存响应没有存储 TLS 版本；对于这些未知值，握手默认设置为 TlsVersion.SSL_3_0。

• 新增：升级到 Okio 1.13.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.13.0</version>
  </dependency>
  
  com.squareup.okio:okio:1.13.0
  

• 修复：优雅地从 Android 7.0 的 socket 抛出的意外 NullPointerException 中恢复。

版本 3.7.0

2017-04-15

• OkHttp 不再通过尝试 TLSv1 连接来从 TLS 握手失败中恢复。 这种回退对于错误实现版本协商的服务器是必要的。现在 99.99% 的服务器都能正确处理，这种回退机制已过时。
• 修复：不接受在公共域（public domain）上设置的 cookie。此前，恶意站点可以在顶级域名（如 co.uk）上注入 cookie，因为我们的 cookie 解析器没有遵循 公共后缀列表。除了此修复之外，还新增了一个 API，HttpUrl.topPrivateDomain()，如果 URL 有私有域名，它将返回该名称。
• 修复：将 MediaType.charset() 更改为对意外字符集返回 null。
• 修复：如果失效响应没有正文，则不跳过缓存失效。
• 修复：不对 WebSocket 使用加密随机数生成器。一些 Android 设备错误地实现了 SecureRandom！
• 修复：正确规范化 HttpUrl 中的 IPv6 地址。此前，这阻止了 OkHttp 信任颁发给某些 IPv6 地址的 HTTPS 证书。
• 修复：在不成功的 Expect: 100-continue 之后不重用连接。
• 修复：处理密码套件名称的 TLS_ 或 SSL_ 前缀。这对于仅使用 SSL_ 前缀的 IBM JVM 是必需的。
• 修复：如果流 ID 为 0，则拒绝 HTTP/2 数据帧。

• 新增：升级到 Okio 1.12.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.12.0</version>
  </dependency>
  
  com.squareup.okio:okio:1.12.0
  

• 新增：连接合并（Connection coalescing）。即使域名不同，OkHttp 也可以在共享 IP 地址和 HTTPS 证书的调用之间重用 HTTP/2 连接。

• 新增：MockWebServer 的 RecordedRequest 通过 getRequestUrl() 方法暴露了请求的 HttpUrl。

版本 3.6.0

2017-01-29

• 修复：在缓存初始化错误时，不会因“cache is closed”错误崩溃。
• 修复：在连接中的 HttpUrlConnection 上调用 disconnect() 可能导致其陷入无限重试循环！此回归在 OkHttp 2.7.0 中引入。
• 修复：丢弃包含 ASCII NULL 和其他不良字符的 cookie。此前，此类 cookie 在包含到请求中时会导致 OkHttp 崩溃。
• 修复：释放重复的多路复用连接。如果同时与 HTTP/2 服务器建立连接，则关闭除第一个连接之外的所有连接。
• 修复：如果第一个帧不是 SETTINGS，则使 HTTP/2 连接失败。
• 修复：禁止在头部名称中使用空格。
• 修复：如果请求是部分请求，则不提供 gzip 压缩。
• 修复：MockWebServer 现在可用于 JUnit 5。该更新 破坏了规则。
• 新增：支持 Expect: 100-continue 作为请求头部。调用者可以使用此头部悲观地推迟传输请求正文，直到服务器给出许可。
• 新增：允许网络拦截器重写 HTTP/2 的 Host 头部。这使得域名前端（domain fronting）成为可能。
• 新增：Credentials.basic() 的字符集支持。

版本 3.5.0

2016-11-30

• WebSocket 现在是 OkHttp 的稳定功能。 自 OkHttp 2.3 中引入作为测试版功能以来，我们的 WebSocket 客户端已经成熟。使用 OkHttpClient.newWebSocket() 连接到服务器的 WebSocket，使用 send() 发送消息，并使用 WebSocketListener 接收消息。

  okhttp-ws 子模块不再可用，OkHttp 之前版本中的 okhttp-ws artifact 与 OkHttp 3.5 不兼容。升级到新包时请注意，WebSocket 和 WebSocketCall 类已合并。发送消息现在是异步的，可以在 WebSocket 连接建立之前排队。

• 如果系统的 HTTP 代理失败，OkHttp 不再尝试直接连接。 此行为令人惊讶，因为 OkHttp 会忽略用户指定的配置。如果您需要自定义代理回退行为，请实现您自己的 java.net.ProxySelector。

• 修复：在支持 TLSv1.3 的设备上支持 TLSv1.3。

• 修复：在等效的 OkHttpClient 实例之间共享连接池。之前的版本存在一个错误，在某些情况下共享连接池不能保证共享连接。

• 修复：在所有条件缓存未命中时优先使用服务器的响应正文。此前，如果缓存响应具有较新的 Last-Modified 日期，我们会返回缓存响应的正文。
• 修复：在条件缓存命中时更新存储的时间戳。
• 新增：优化的 HTTP/2 请求头部编码。更多头部被 HPACK 编码，字符串字面量现在采用 Huffman 编码。
• 新增：暴露 Multipart 中的 Part 头部和正文。

• 新增：使 ResponseBody.string() 和 ResponseBody.charStream() 支持 BOM。如果您的 HTTP 响应正文以 字节序标记 开头，它将被消耗并用于选择剩余字节的字符集。大多数应用程序不需要字节序标记。

• 新增：升级到 Okio 1.11.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.11.0</version>
  </dependency>
  
  com.squareup.okio:okio:1.11.0
  

• 修复：在没有请求正文时避免发送空的 HTTP/2 数据帧。

• 修复：在 JavaNetCookieJar 中添加一个前导 . 以实现更好的域名匹配。
• 修复：在请求开始时优雅地从 HTTP/2 连接关闭中恢复。
• 修复：如果 MediaType 的字符集被 '单引号' 括起来，则放宽处理。
• 修复：允许在头部值中使用水平制表符。
• 修复：解析 HTTP 身份验证头部时，允许质询参数以任意顺序出现。

版本 3.4.2

2016-11-03

• 修复：HTTP/2 连接关闭时优雅地恢复。我们存在一个错误，已关闭的 HTTP/2 连接被认为是可用的。这导致调用尝试恢复时进入无限循环。

版本 3.4.1

2016-07-10

• 修复了编码 HTTP 头部的一个主要错误。 在 3.4.0 和 3.4.0-RC1 中，OkHttp 的 HPACK 编码器存在一个 off-by-one 错误。这个错误可能导致在一系列 HTTP/2 请求后发出错误的头部！所有使用 OkHttp 3.4.0 或 3.4.0-RC1 的用户都应该升级以获取此错误修复。

版本 3.4.0

2016-07-08

• 新增：支持 HPACK 编码器的动态表大小更改。
• 修复：在 Headers.toMultimap() 中使用 TreeMap。这使得对返回的 map 进行字符串查找时不区分大小写。
• 修复：不在 HttpURLConnection 中共享 OkHttpClient 的 Dispatcher。

版本 3.4.0-RC1

2016-07-02

• 我们重写了 HttpURLConnection 和 HttpsURLConnection。 此前，我们在两个前端 API：HttpURLConnection 和 Call 之间共享一个 HTTP 引擎。在此版本中，我们对结构进行了调整，使得 HttpURLConnection 前端现在内部委托给 Call API。这使得 OkHttp 核心对于这两个前端都实现了实质性的简化和优化。

  对于大多数 HTTP 请求，此更改的影响可以忽略不计。如果您的应用程序使用了 HttpURLConnection.connect()、setFixedLengthStreamingMode() 或 setChunkedStreamingMode()，OkHttp 现在将使用异步分派器线程来建立 HTTP 连接。

  我们不期望此更改会带来任何行为或性能影响。尽管如此，在应用此更新时，请测试您的 OkUrlFactory 和 HttpURLConnection 代码。

• 密码套件现在可以有任意名称。 此前 CipherSuite 是一个 Java 枚举，不升级 OkHttp 就无法定义新的密码套件。通过此更改，它现在是一个带有类似枚举常量的常规 Java 类。使用密码套件的枚举方法（ordinal(), name() 等）的应用程序代码将因这一更改而中断。

• 修复：CertificatePinner 现在匹配规范化后的主机名。此前是区分大小写的。此更改也应该使国际化域名（internationalized domain names）的证书锁定配置更容易。

• 修复：不因非 ASCII 的 ETag 头部而崩溃。此前，OkHttp 在验证缓存响应时会拒绝这些头部。
• 修复：不允许远程对等方任意调整 HPACK 解码器的动态表大小。
• 修复：遵循 Android 的网络安全配置中的每主机配置。此前，禁用任何主机的明文通信会禁用所有主机的明文通信。请注意，此设置仅在 Android 24+ 上可用。
• 新增：HPACK 压缩现在是动态的。这应该能提高通过 HTTP/2 传输请求头部的性能。
• 新增：可以使用 Dispatcher.setIdleCallback() 来表示没有正在进行的调用。这对于 使用 Espresso 进行测试 非常有用。

• 新增：升级到 Okio 1.9.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.9.0</version>
  </dependency>
  

版本 3.3.1

2016-05-28

• 修复：HttpLoggingInterceptor 中的明文检查错误地将换行符分类为控制字符。这已修复。
• 修复：在读取 HTTP/2 头部或缓存的 HTTP 头部中的非 ASCII 字符时不会崩溃。
• 修复：当尝试打开 WebSocket 返回非 101 响应码时，保留响应正文。

版本 3.3.0

2016-05-24

• 新增：Response.sentRequestAtMillis() 和 receivedResponseAtMillis() 方法跟踪发出网络调用时的系统本地时间。它们取代了 OkHttp 早期版本中存在的 OkHttp-Sent-Millis 和 OkHttp-Received-Millis 头部。
• 新增：在 OkHttpClient.Builder 中接受用户提供的信任管理器。这允许 OkHttp 直接满足其 TLS 要求。否则，OkHttp 将使用反射从 SSLSocketFactory 中提取 TrustManager。
• 新增：支持预发布版 Java 9。这使得 ALPN 从平台获取，而不是依赖 alpn-boot bootclasspath 覆盖。
• 新增：HttpLoggingInterceptor 现在记录连接失败。

• 新增：升级到 Okio 1.8.0。

  <dependency>
    <groupId>com.squareup.okio</groupId>
    <artifactId>okio</artifactId>
    <version>1.8.0</version>
  </dependency>
  

• 修复：优雅地从重建缓存日志失败中恢复。

• 修复：当缓存条目在更新时被逐出时，不会损坏缓存条目。
• 修复：使 OkHttp 中的日志记录更一致。
• 修复：仅记录明文正文。这使用简单的启发式方法区分文本和其他数据。
• 修复：从 HTTP/2 中的 REFUSED_STREAM 错误中恢复。这应该能改善与 Nginx 1.10.0 的互操作性，Nginx 1.10.0 拒绝 在 HTTP/2 设置尚未确认之前创建的流。
• 修复：改进从失败路由中恢复。
• 修复：适应在认证质询后关闭连接的隧道代理。
• 修复：在认证 HTTP 代理时使用代理认证器。此回归在 OkHttp 3.0 中引入。
• 修复：如果网络拦截器转换响应正文，使其关闭时未能同时关闭底层流，则快速失败。我们存在一个错误，OkHttp 会尝试重用连接，但由于被先前的请求持有而无法重用。
• 修复：确保网络拦截器始终能访问底层连接。
• 修复：在 Android 17+ 上使用 X509TrustManagerExtensions。
• 修复：在 MockWebServer 关闭时解除阻塞等待中的调度器。

版本 3.2.0

2016-02-25

• 修复：更改证书锁定器，使其始终构建完整链。这防止了在使用证书锁定与 Google Play 服务安全提供程序时可能发生的崩溃。
• 修复：使 IPv6 请求行与 Firefox 和 Chrome 保持一致。
• 修复：在修剪响应缓存失败时优雅地恢复。
• 新增：在 HttpUrl.Builder 中使用单个字符串添加多个路径段。
• 新增：在证书锁定器中支持 SHA-256 图钉。

版本 3.1.2

2016-02-10

• 修复：在 Robolectric 上查找信任管理器时不会崩溃。我们尝试检测主机平台，但由于 Robolectric 看似 Android 但不是 Android 而感到困惑！
• 修复：更改 CertificatePinner，在没有锁定证书时跳过清理证书链。这避免了在不安全的“信任所有人”配置（例如与自签名证书的开发 HTTPS 服务器通信时）中的 SSL 失败。

版本 3.1.1

2016-02-07

• 修复：如果安装了 Play 服务（GMS）安全提供程序，则在查找信任管理器时不会崩溃。
• 修复：上一个版本引入了 Android 上的性能回归，原因是查找 CA 证书。这现已修复。

版本 3.1.0

2016-02-06

• 新增：WebSockets 现在延迟一些写入。这应该能提高某些应用程序的性能。
• 新增：在我们的新 cookie 类中覆盖 equals() 和 hashCode()。此类现在通过值而不是通过引用定义相等性。
• 新增：通过重试请求处理 408 响应。这允许服务器指示客户端重试而不是永久失败。
• 新增：在 Connection 中暴露帧协议。此前它会返回应用层协议（HTTP/1.1 或 HTTP/1.0）；现在它总是返回线层协议（HTTP/2、SPDY/3.1 或 HTTP/1.1）。
• 修复：允许可信 CA 根证书被 CertificatePinner 锁定。
• 修复：静默忽略未知的 HTTP/2 设置。此前这会导致整个连接失败。
• 修复：在日志拦截器中遇到意外字符集时不会崩溃。
• 修复：为了便于 mocking 框架，OkHttpClient 现在是非 final 的。Mocking 像 OkHttpClient 这样的复杂类是不稳定的，您不应该这样做。但如果您想这样生活，我们不会阻碍您！

版本 3.0.1

2016-01-14

• 回滚 OSGi 支持。这导致库 jar 包含超出预期的类，从而干扰了 Gradle 构建。

版本 3.0.0

2016-01-13

此版本致力于稳定的 3.0 API。请阅读 3.0.0-RC1 的更改，获取从 2.x 升级到 3.x 的建议。

• Callback 接口现在接受一个 Call。 这使得在回调中检查调用是否被取消更容易。将异步调用迁移到这个新 API 时，Call 现在是 onResponse() 和 onFailure() 的第一个参数。
• 修复：在 Android 的 JavaNetCookieJar 中处理多个 cookie。
• 修复：改进 MockWebServer 响应中的默认 HTTP 消息。
• 修复：当条件 GET 抛出异常时，不会泄漏文件句柄。
• 修复：在 OkHttp 的日志拦截器中使用请求正文内容类型指定的字符集。
• 修复：在缓存命中时不急于释放连接池。
• 新增：使 OkHttp 准备好支持 OSGi。
• 新增：向缓存添加已实现的接口 Closeable 和 Flushable。

版本 3.0.0-RC1

2016-01-02

OkHttp 3 是一个主要版本，专注于 API 的简洁性和一致性。API 更改很多，但大多数是外观上的。应用程序应该能够机械地、无风险地从 2.x API 升级到 3.x API。

由于此版本包含破坏性的 API 更改，我们将项目的包名从 com.squareup.okhttp 更改为 okhttp3。这应该使得大型应用程序能够增量迁移。Maven group ID 现在是 com.squareup.okhttp3。有关此策略的解释，请参阅 Jake Wharton 的文章 Java Interoperability Policy for Major Version Updates。

此版本废弃了 OkHttp 2.x，所有使用 OkHttp 的 com.squareup.okhttp 包的代码都应该升级到 okhttp3 包。依赖 OkHttp 的库应该尽快升级，以防止应用程序滞留在旧版本。

• 不再存在全局单例连接池。 在 OkHttp 2.x 中，所有 OkHttpClient 实例默认共享一个公共连接池。在 OkHttp 3.x 中，每个新的 OkHttpClient 都有自己的私有连接池。应用程序应避免创建许多连接池，因为这样做会阻止连接重用。每个连接池都保持其自身的连接处于活动状态，因此拥有许多连接池的应用程序也可能面临内存耗尽的风险！

  OkHttp 3 的最佳实践是创建一个单一的 OkHttpClient 实例并在整个应用程序中共享它。需要自定义客户端的请求应该在该共享实例上调用 OkHttpClient.newBuilder()。这可以在不带来独立连接池缺点的情况下进行自定义。

• OkHttpClient 现在是无状态的。 在 2.x API 中，OkHttpClient 有 getter 和 setter 方法。在内部，每个请求都被迫生成 OkHttpClient 实例的完整快照，以防御竞态配置更改。在 3.x 中，OkHttpClient 现在是无状态的，并且有一个 builder。请注意，此类并非严格意义上的不可变，因为它包含连接池和缓存等有状态成员。

• 现在避免使用 Get 和 Set 前缀。 由于 OkHttp 中普遍存在 builder，这些访问器前缀不再必要。此前 OkHttp 不规律地使用了 get 和 set 前缀，这使得 API 不一致且难以探索。

• OkHttpClient 现在实现了新的 Call.Factory 接口。 此接口将使您的代码更容易测试。在测试发起 HTTP 请求的代码时，您可以使用此接口将真实的 OkHttpClient 替换为您自己的 mock 或 fake 实现。

  该接口还允许您将 OkHttp 的 API 与另一个 HTTP 客户端的实现一起使用。这在 Google App Engine 等沙盒环境中非常有用。

• OkHttp 现在处理 cookie。 我们已经将 java.net.CookieHandler 替换为一个新接口 CookieJar，并添加了我们自己的 Cookie 模型类。这个新 cookie 遵循最新的 RFC，并支持现代 Web 浏览器相同的 cookie 属性。

• Form 和 Multipart 正文现在被模型化。 我们已经将不透明的 FormEncodingBuilder 替换为更强大的 FormBody 和 FormBody.Builder 组合。类似地，我们将 MultipartBuilder 升级为 MultipartBody, MultipartBody.Part 和 MultipartBody.Builder。

• Apache HTTP 客户端和 HttpURLConnection API 已被弃用。 它们仍然像以前一样工作，但我们正在将所有内容迁移到新的 OkHttp 3 API。okhttp-apache 和 okhttp-urlconnection 模块仅应用于加速向 OkHttp 的请求/响应 API 的过渡。这些已弃用的模块将在即将发布的 OkHttp 3.x 版本中移除。

• 批量取消调用现在是应用程序的责任。 按标签取消调用的 API 已被移除，并替换为更通用的机制。调度器现在通过其 runningCalls() 和 queuedCalls() 方法暴露所有正在进行的调用。您可以编写代码，按标签、主机或任何您想要的条件选择调用，并在不再需要的调用上调用 Call.cancel()。

• OkHttp 默认不再使用全局的 java.net.Authenticator。 我们更改了 Authenticator 接口，通过一个方法认证 Web 和代理认证失败。在 okhttp-urlconnection 模块中提供了旧认证器的适配器。

• 修复：在调用 ResponseBody.contentLength() 或 close() 时不抛出 IOException。

• 修复：将 HttpUrl 转换为 java.net.URI 时绝不抛出异常。这将更改 uri() 方法，使其能处理格式错误的百分号转义和 URI 禁止的字符。
• 修复：当连接超时时，尝试备用路由。此前，在区分失败时，路由选择效率较低。
• 新增：Response.peekBody() 允许您在不消耗响应正文的情况下访问它。这对于拦截器可能很方便！
• 新增：HttpUrl.newBuilder() 将链接解析为 builder。
• 新增：向 Handshake 添加 TLS 版本。
• 新增：移除 Request.uri() 和 Request#urlString()。只需使用 Request.url().uri() 和 Request.url().toString()。
• 新增：向 HTTP 响应日志添加 URL。
• 新增：将 HttpUrl 设置为 Request 中首选的 URL 方法。

版本 2.x

更新日志