OkHttp for Kotlin：完整指南及示例

什么是 OkHttp，为什么需要它？

OkHttp 是由 Square 公司开发的一款功能强大且高效的 HTTP 库，适用于 JVM（Java 虚拟机）、Android 和 Kotlin/Native。它提供了便捷的 API 用于执行 HTTP 请求和处理响应。OkHttp 是 Android 生态系统中网络通信的事实标准，并广泛应用于服务器端 Kotlin 应用程序。

为什么使用 OkHttp 而不是 Java 的标准工具（HttpURLConnection）？

\n
• 简单便捷： 清晰流畅的 API，易于阅读和编写。
\n
• 高性能： 内置支持 HTTP/2、自动响应压缩（gzip）、连接池和缓存。
\n
• 高可靠性： 网络故障时自动重试请求，对 DNS 和 TLS 错误具有容错性。
\n
• 灵活性： 可轻松配置拦截器，用于日志记录、身份验证、修改请求和响应。
\n
• 可测试性： 可通过 MockWebServer 替换网络层。
\n

OkHttp 非常适合 Android 应用程序、REST API 客户端、微服务以及任何需要可靠且快速 HTTP 通信的 Kotlin 项目。

安装

OkHttp 通过 Maven Central 分发。要在项目中添加，请使用 Gradle 构建系统（Kotlin 最常用）。

对于 Android / Kotlin/JVM 项目（build.gradle.kts）：

dependencies {\n    implementation("com.squareup.okhttp3:okhttp:4.12.0")\n    // 用于日志记录（可选）\n    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")\n}

对于 Android / Kotlin/JVM 项目（build.gradle）：

dependencies {\n    implementation 'com.squareup.okhttp3:okhttp:4.12.0'\n    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'\n}

对于 Maven（pom.xml）：

<dependency>\n    <groupId>com.squareup.okhttp3</groupId>\n    <artifactId>okhttp</artifactId>\n    <version>4.12.0</version>\n</dependency>

重要提示： 请确保 OkHttp 版本与您的 Kotlin 版本兼容。最新版本始终可以在 MVNRepository 上找到。

快速入门

最简单的示例是执行 GET 请求并以字符串形式获取响应体。

import okhttp3.OkHttpClient\nimport okhttp3.Request\nimport java.io.IOException\n\nfun main() {\n    // 1. 创建客户端（通常整个应用共享一个实例）\n    val client = OkHttpClient()\n\n    // 2. 构建请求\n    val request = Request.Builder()\n        .url("https://api.github.com/users/octocat")\n        .build()\n\n    // 3. 同步执行请求（阻塞当前线程）\n    client.newCall(request).execute().use { response ->\n        if (!response.isSuccessful) {\n            throw IOException("Unexpected code $response")\n        }\n        // 4. 获取响应体\n        println(response.body?.string())\n    }\n}

说明：

\n
1. OkHttpClient() — 创建客户端实例。它是线程安全的，因此建议创建一个实例并重复使用。
\n
2. Request.Builder() — 使用构建器模式配置请求。
\n
3. client.newCall(request) — 创建一个新的调用，可以同步执行（execute()）或异步执行（enqueue()）。
\n
4. response.use { ... } — 确保响应资源（响应体、连接）在使用后关闭。
\n
5. response.body?.string