Kotlin Ktor客户端使用 - 摩柯技术社区

1. Ktor 客户端简介

Kotlin 的 Ktor 框架不仅提供了强大的服务器端开发能力，其客户端部分也同样功能丰富。Ktor 客户端允许开发者轻松地与各种 HTTP 服务器进行交互，无论是 RESTful API 还是其他类型的 HTTP 服务。它支持异步操作，这对于现代应用开发中处理网络请求非常关键，能够避免阻塞主线程，提升应用的响应性。

Ktor 客户端的设计理念是简洁且灵活。它基于 Kotlin 的协程，使得异步代码编写变得直观和易于理解。开发者可以使用流畅的 DSL（Domain - Specific Language）来构建 HTTP 请求，设置请求头、参数、请求体等，并且能够方便地处理响应。

2. 引入 Ktor 客户端依赖

要在项目中使用 Ktor 客户端，首先需要在项目的构建文件中引入相关依赖。如果使用 Gradle，在 build.gradle.kts 文件中添加以下依赖：

dependencies {
    implementation("io.ktor:ktor - client - core:2.3.3")
    implementation("io.ktor:ktor - client - android:2.3.3") // 如果你是 Android 项目
    implementation("io.ktor:ktor - client - okhttp:2.3.3") // 使用 OkHttp 作为引擎，这是常用的选择
}

在 Maven 项目中，在 pom.xml 文件中添加：

<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor - client - core</artifactId>
    <version>2.3.3</version>
</dependency>
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor - client - android</artifactId>
    <version>2.3.3</version>
</dependency>
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor - client - okhttp</artifactId>
    <version>2.3.3</version>
</dependency>

这里引入了 ktor - client - core 核心库，ktor - client - android 用于 Android 项目（如果适用），以及 ktor - client - okhttp，它使用 OkHttp 作为底层的 HTTP 引擎，OkHttp 是一个高性能的 HTTP 客户端库，被广泛应用于 Android 和其他 Kotlin 项目中。

3. 创建 Ktor 客户端实例

创建 Ktor 客户端实例是发起 HTTP 请求的第一步。通常，我们会使用 HttpClient 类来创建客户端实例。

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp) {
        // 可以在这里配置客户端，比如设置连接超时等
        engine {
            config {
                connectTimeout(15, java.util.concurrent.TimeUnit.SECONDS)
                readTimeout(20, java.util.concurrent.TimeUnit.SECONDS)
            }
        }
    }
    launch {
        // 在这里使用 client 发起请求
    }
    client.close()
}

在上述代码中，通过 HttpClient(OkHttp) 创建了一个使用 OkHttp 引擎的客户端实例。在 engine 块中，可以对 OkHttp 的配置进行自定义，这里设置了连接超时为 15 秒，读取超时为 20 秒。

4. 发起 GET 请求

发起 GET 请求是最常见的 HTTP 操作之一。使用 Ktor 客户端发起 GET 请求非常简单。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1")
        val todo = response.body<String>()
        println(todo)
    }
    client.close()
}

在这段代码中，通过 client.get 方法发起了一个 GET 请求到 https://jsonplaceholder.typicode.com/todos/1。response.body<String>() 方法用于将响应体解析为字符串类型并返回。如果 API 返回的是 JSON 数据，我们通常会将其解析为 Kotlin 对象。假设我们有一个表示待办事项的 Kotlin 数据类：

data class Todo(
    val userId: Int,
    val id: Int,
    val title: String,
    val completed: Boolean
)

可以这样解析 JSON 响应：

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1")
        val todo = response.body<Todo>()
        println(todo.title)
    }
    client.close()
}

这里 response.body<Todo>() 会自动将 JSON 响应解析为 Todo 对象，前提是 JSON 结构与 Todo 数据类的结构相匹配。

5. 发起 POST 请求

POST 请求通常用于向服务器提交数据。以下是如何使用 Ktor 客户端发起 POST 请求的示例：

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

data class NewTodo(
    val title: String,
    val completed: Boolean,
    val userId: Int
)

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val newTodo = NewTodo("Learn Ktor", false, 1)
        val response = client.post("https://jsonplaceholder.typicode.com/todos") {
            contentType(ContentType.Application.Json)
            setBody(newTodo)
        }
        val createdTodo = response.body<String>()
        println(createdTodo)
    }
    client.close()
}

在这个例子中，首先定义了一个 NewTodo 数据类，用于表示要提交的新待办事项数据。然后通过 client.post 方法发起 POST 请求，在请求块中，使用 contentType(ContentType.Application.Json) 设置请求体的内容类型为 JSON，setBody(newTodo) 将 newTodo 对象作为请求体发送。

6. 设置请求头

在很多情况下，需要在请求中设置特定的请求头。Ktor 客户端提供了简单的方式来设置请求头。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import io.ktor.http.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1") {
            headers {
                append(HttpHeaders.Authorization, "Bearer your_token_here")
                append(HttpHeaders.ContentType, ContentType.Application.Json.toString())
            }
        }
        val todo = response.body<String>()
        println(todo)
    }
    client.close()
}

在 headers 块中，使用 append 方法添加了 Authorization 和 Content - Type 请求头。Authorization 头通常用于身份验证，Content - Type 头用于告知服务器请求体的数据类型。

7. 处理响应状态码

处理响应状态码是确保请求成功的重要步骤。Ktor 客户端允许我们轻松获取和处理响应状态码。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import io.ktor.http.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1")
        if (response.status == HttpStatusCode.OK) {
            val todo = response.body<String>()
            println(todo)
        } else {
            println("Request failed with status: ${response.status}")
        }
    }
    client.close()
}

在上述代码中，通过 response.status 获取响应状态码，并与 HttpStatusCode.OK 进行比较。如果状态码是 200（OK），则处理响应体；否则，打印错误信息。

8. 处理重定向

Ktor 客户端默认会自动处理重定向。但在某些情况下，我们可能需要自定义重定向策略。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import io.ktor.http.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = HttpClient(OkHttp) {
        followRedirects = false
    }
    launch {
        val response = client.get("http://example.com/redirect - to - somewhere")
        if (response.status == HttpStatusCode.Redirect) {
            val newUrl = response.headers[HttpHeaders.Location]
            // 手动处理重定向
            val newResponse = client.get(newUrl ?: "")
            val result = newResponse.body<String>()
            println(result)
        } else {
            val result = response.body<String>()
            println(result)
        }
    }
    client.close()
}

在 HttpClient 的配置中，通过 followRedirects = false 禁用了自动重定向。然后在获取响应后，检查状态码是否为 HttpStatusCode.Redirect，如果是，则从响应头中获取重定向的 URL，并手动发起新的请求。

9. 上传文件

上传文件也是常见的网络操作。Ktor 客户端可以方便地实现文件上传。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import io.ktor.http.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.io.File

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val file = File("path/to/your/file.txt")
        val response = client.post("https://example.com/upload") {
            contentType(ContentType.MultiPart.FormData)
            setBody(
                MultiPartFormDataContent(
                    formData {
                        append("file", file.readBytes(), Headers.build {
                            append(HttpHeaders.ContentDisposition, "form - data; name=\"file\"; filename=\"${file.name}\"")
                            append(HttpHeaders.ContentType, ContentType.Application.OctetStream.toString())
                        })
                    }
                )
            )
        }
        val result = response.body<String>()
        println(result)
    }
    client.close()
}

在这个例子中，首先创建了一个 File 对象指向要上传的文件。然后在 post 请求中，设置内容类型为 ContentType.MultiPart.FormData，并使用 MultiPartFormDataContent 构建请求体，将文件作为表单数据的一部分进行上传。

10. 下载文件

下载文件同样可以使用 Ktor 客户端实现。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.io.File

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    launch {
        val response = client.get("https://example.com/download/file.txt")
        val file = File("path/to/save/file.txt")
        file.writeBytes(response.body())
    }
    client.close()
}

这里通过 client.get 发起下载请求，然后使用 response.body() 获取响应体的字节数组，并将其写入到本地文件中。

11. 并发请求

Kotlin 的协程使得并发请求变得非常容易。我们可以同时发起多个请求并等待所有请求完成。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

fun main() = runBlocking {
    val client = HttpClient(OkHttp)
    val requests = listOf(
        async { client.get("https://jsonplaceholder.typicode.com/todos/1").body<String>() },
        async { client.get("https://jsonplaceholder.typicode.com/todos/2").body<String>() },
        async { client.get("https://jsonplaceholder.typicode.com/todos/3").body<String>() }
    )
    val results = requests.awaitAll()
    results.forEach { println(it) }
    client.close()
}

在这段代码中，使用 async 函数创建了三个并发请求，awaitAll 方法会等待所有请求完成，并返回所有请求的结果。

12. 自定义拦截器

Ktor 客户端允许我们自定义拦截器，用于在请求发送前和响应接收后执行一些通用的逻辑，比如日志记录、添加通用请求头等。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.features.json.*
import io.ktor.client.features.json.serializer.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.coroutines.*
import kotlinx.serialization.json.Json

class LoggingInterceptor : HttpClientPlugin<Unit, LoggingInterceptor.Config> {
    override val key: AttributeKey<Config> = AttributeKey("LoggingInterceptor")
    override fun prepare(block: Unit.() -> Config): Config = block()

    class Config {
        var logLevel: LogLevel = LogLevel.ALL
    }

    enum class LogLevel {
        ALL,
        REQUEST,
        RESPONSE
    }

    override fun install(plugin: Config, scope: HttpClient) {
        scope.intercept(HttpRequestPipeline.Before) {
            if (plugin.logLevel == LogLevel.ALL || plugin.logLevel == LogLevel.REQUEST) {
                println("Request: ${url}")
                headers.forEach { println("Header: ${it.key}: ${it.value}") }
                if (body is OutgoingContent.ByteArrayContent) {
                    println("Body: ${(body as OutgoingContent.ByteArrayContent).readBytes().decodeToString()}")
                }
            }
        }
        scope.intercept(HttpResponsePipeline.After) { response ->
            if (plugin.logLevel == LogLevel.ALL || plugin.logLevel == LogLevel.RESPONSE) {
                println("Response: ${response.status}")
                response.headers.forEach { println("Header: ${it.key}: ${it.value}") }
                if (response is HttpResponseContainer<*>) {
                    println("Body: ${response.readText()}")
                }
            }
        }
    }
}

fun main() = runBlocking {
    val client = HttpClient(OkHttp) {
        install(LoggingInterceptor) {
            logLevel = LoggingInterceptor.LogLevel.ALL
        }
    }
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1")
        val todo = response.body<String>()
        println(todo)
    }
    client.close()
}

在上述代码中，定义了一个 LoggingInterceptor 拦截器。在 install 方法中，通过 scope.intercept 分别在请求管道的 Before 和响应管道的 After 阶段添加了日志记录逻辑。在 HttpClient 的配置中，安装了这个拦截器并设置了日志级别。

13. 与 JSON 序列化库集成

Ktor 客户端可以与各种 JSON 序列化库集成，如 Kotlinx Serialization。

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.features.json.*
import io.ktor.client.features.json.serializer.*
import io.ktor.client.request.*
import kotlinx.serialization.Serializable
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

@Serializable
data class Todo(
    val userId: Int,
    val id: Int,
    val title: String,
    val completed: Boolean
)

fun main() = runBlocking {
    val client = HttpClient(OkHttp) {
        install(JsonFeature) {
            serializer = KotlinxSerializer(Json {
                prettyPrint = true
                isLenient = true
            })
        }
    }
    launch {
        val response = client.get("https://jsonplaceholder.typicode.com/todos/1")
        val todo = response.body<Todo>()
        println(todo.title)
    }
    client.close()
}

在这个例子中，首先定义了一个 @Serializable 注解的 Todo 数据类。然后在 HttpClient 的配置中，安装了 JsonFeature，并设置 serializer 为 KotlinxSerializer，同时对 Json 进行了一些配置，如 prettyPrint 使 JSON 输出更易读，isLenient 使解析更宽松。这样就可以方便地将 JSON 响应解析为 Kotlin 对象。

14. 处理 HTTPS 证书

当与 HTTPS 服务器进行通信时，可能会遇到证书相关的问题。Ktor 客户端可以通过配置来处理证书。

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import io.ktor.client.request.*
import java.security.SecureRandom
import java.security.cert.X509Certificate
import javax.net.ssl.*

fun main() = runBlocking {
    val trustAllCerts = arrayOf<TrustManager>(
        object : X509TrustManager {
            override fun checkClientTrusted(chain: Array<out X509Certificate>?, authType: String?) {}
            override fun checkServerTrusted(chain: Array<out X509Certificate>?, authType: String?) {}
            override fun getAcceptedIssuers(): Array<X509Certificate> = arrayOf()
        }
    )
    val sslContext = SSLContext.getInstance("SSL").apply {
        init(null, trustAllCerts, SecureRandom())
    }
    val client = HttpClient(OkHttp) {
        engine {
            sslSocketFactory(sslContext.socketFactory, trustAllCerts[0] as X509TrustManager)
            hostnameVerifier { _, _ -> true }
        }
    }
    launch {
        val response = client.get("https://example.com")
        val result = response.body<String>()
        println(result)
    }
    client.close()
}

在这段代码中，创建了一个信任所有证书的 TrustManager，并使用它初始化了 SSLContext。在 HttpClient 的 engine 配置中，设置了 sslSocketFactory 和 hostnameVerifier，这样可以绕过证书验证（不建议在生产环境中使用，仅用于测试或特定场景）。如果在生产环境中，应该使用合法的证书并正确配置证书验证。

15. 高级配置与优化

连接池：Ktor 客户端使用的 OkHttp 引擎默认支持连接池。连接池可以复用已有的 HTTP 连接，减少连接建立的开销。可以通过 OkHttp 的配置进一步优化连接池的参数，比如最大空闲连接数、连接存活时间等。

val client = HttpClient(OkHttp) {
    engine {
        config {
            connectionPool(ConnectionPool(5, 5, java.util.concurrent.TimeUnit.MINUTES))
        }
    }
}

这里设置了连接池最大有 5 个空闲连接，连接存活时间为 5 分钟。

缓存策略：对于一些不经常变化的数据，可以设置缓存策略。OkHttp 支持缓存，Ktor 客户端可以通过配置 OkHttp 来启用缓存。

val cacheDir = File(context.cacheDir, "http - cache")
val cacheSize = 10 * 1024 * 1024L // 10MB
val cache = Cache(cacheDir, cacheSize)
val client = HttpClient(OkHttp) {
    engine {
        config {
            cache(cache)
        }
    }
}

在这个例子中，创建了一个 10MB 的缓存，并将其配置到 OkHttp 引擎中。

线程池配置：Ktor 客户端的异步操作依赖于 Kotlin 协程和底层引擎的线程池。在一些高性能场景下，可能需要自定义线程池配置。例如，可以通过 OkHttp 的 Dispatcher 来设置线程池。

val executor = Executors.newFixedThreadPool(10)
val dispatcher = ExecutorCoroutineDispatcher(executor)
val client = HttpClient(OkHttp) {
    engine {
        config {
            dispatcher(dispatcher)
        }
    }
}

这里创建了一个固定大小为 10 的线程池，并将其作为 OkHttp 的 Dispatcher 使用，以满足特定的性能需求。

通过以上这些高级配置和优化，可以使 Ktor 客户端在不同的应用场景下表现得更加高效和稳定。无论是处理高并发请求、优化网络资源使用还是提升响应速度，都能通过合理的配置来实现。同时，在实际应用中，还需要根据具体的业务需求和服务器端的情况进行适当的调整和优化。

在处理复杂的业务逻辑时，可能需要结合 Ktor 客户端与其他 Kotlin 库或框架。例如，与 Room 数据库集成，将从服务器获取的数据存储到本地数据库；或者与 RxJava 集成，以一种更响应式的方式处理异步操作。总之，Ktor 客户端作为 Kotlin 生态中强大的 HTTP 客户端工具，为开发者提供了丰富的功能和灵活的配置选项，使得网络编程变得更加轻松和高效。