KMM 入门处理 HTTP 网络请求

Posted 袁国正_yy

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了KMM 入门处理 HTTP 网络请求相关的知识,希望对你有一定的参考价值。

背景

与 Server 的数据交互已经成为 App 必不可少的一个重要部分,常用的方式即 HTTP(S),当然也有 WebSocket、TCP、UDP 等等

在 KMM 模块中,为保证双端逻辑一致,且对 JVM、Native 进行统一兼容,可以使用官方推荐的 Ktor 进行网络通信,Kotlinx.Serialization 来进行数据解析

这篇文章就来介绍在 KMM 中如何发起并处理网络请求,后面的文章再详细介绍 kotlinx.serialization 的使用

Ktor 是什么?

Ktor 是由 JetBrains 开发的一套用于解决各类应用中网络连接的框架,不仅可以用在发起请求的各类客户端(不是所谓的 App),还可以构建微服务

针对客户端能力,通过一系列插件,可以支持 HTTP 的各类特性,如:Cookies、重定向、代理、UA、WebSocket 等,在一定程度上,还可以支持一些简单的 TCP 或 UDP 通信

另外,Ktor 还支持为不同的平台配置不同的 HTTP 引擎,如:为 android 配置 OkHttp 或 HttpURLConnection,为 ios 配置 NSURLSession,或者为 JVM 配置 Apache HttpClient、为 javascript (Node.js) 配置 node-fetch,以便使用同一套代码逻辑处理网络请求

由于现在的 RESTful API 通常会以 JSON 作为通信数据格式,在 JVM 平台上,Ktor 还支持与 Gson、Jackson 协同工作,而对于 Kotlin Multiplatform(当然包括 KMM)可以与 kotlinx.serialization 进行协作

由于 Ktor 适用的平台广泛,本文只对 KMM 平台上的使用进行说明

为 KMM 模块配置 Ktor

如果你使用的 IDE 是 IntelliJ IDEA Ultimate 版本,可以考虑安装 Ktor 插件,但基于 Community 版本的 Android Studio 等 IDE 并不支持该插件,当然它对实际使用影响不大

对于 KMM 模块,首先需要在 Common 的依赖中加入 Ktor 的核心依赖

由于 Ktor 底层依赖协程一些核心功能,同时 Ktor 需要使用基于 Kotlin Native 且实现多线程版本的协程库,所以还需要加入对协程的依赖

// build.gradle.kts

// 2022 年 4 月,Ktor 正式发布了 2.0.0 版本
val ktor_version = "2.0.2"

// ...

val commonMain by getting 
    dependencies 
        implementation("io.ktor:ktor-client-core:$ktor_version")
    

Android 模块中加入 Ktor Android 端默认引擎(使用 HttpURLConnection)的依赖

// build.gradle.kts

androidMain 
    dependencies 
        implementation("io.ktor:ktor-client-android:$ktor_version")
    

如果需要使用 OkHttp 来作为 HTTP 能力的引擎,可以使用如下的依赖

// build.gradle.kts

androidMain 
    dependencies 
        implementation("io.ktor:ktor-client-okhttp:$ktor_version")
    

另外,Android 端也可以使用 CIO(Coroutine(协程) based I/O 实现)引擎,但 CIO 目前还不支持 HTTP/2

对于 iOS,则加入 iOS 的引擎依赖,由于 iOS 的 HTTP 网络请求都是使用 NSURLSession(包括著名的 AFNetworking,NSURLConnection 早已经不用了),所以也就不像 Android 上有多种选择

// build.gradle.kts

iosMain 
    dependencies 
        implementation("io.ktor:ktor-client-darwin:$ktor_version")
    

由于 Ktor 是 Kotlin 团队主要负责开发和维护,所以对 Kotlin 相关技术栈支持的比较友好,且部分技术应用的也比较激进,比如 Kotlin Native 的 New Memory Management,所以官方建议大家使用 Kotlin 协程,这就要求在宿主 App(Android 端)中添加协程相关的依赖

dependencies 
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.1")

Ktor 已经适配了 New Memory 技术,如果还需要开启 New Memory,则需要根据 New Memory 官方的文档要求,在 gradle.properties 文件中,添加以下的配置项

kotlin.native.binary.memoryModel=experimental

创建 Ktor 的 HttpClient

Ktor 中的 HttpClient 与其他 HTTP 框架类似,都是对发送和接收网络请求的一系列资源、配置的封装,请求与响应的操作方法,以 Extension 的形式表现,调用也非常简洁

在 Common 代码中,首先需要创建一个 HttpClient 的实例

val httpClient by lazy  HttpClient() 

如果不需要对 HttpClient 默认的引擎(根据 Gradle 中的依赖自动设置)进行特殊配置,以上代码足矣

为保障多平台的一致,在 Common 中的 HttpClient,对 engine 的可配置项非常有限,只有下面的 Proxy 和线程数量可配,同时可以支持一些公共的请求配置,写在 defaultRequest 闭包中即可,具体内容见下面一节

HttpClient 
    engine 
        proxy = ProxyBuilder.http("http://127.0.0.1:8888")
        threadsCount = 4
    
    defaultRequest 
        // 可配置公共的 Cookies、Headers、Params
    

如果需要针对不同的平台和不同的引擎的特性,进行一些自定义配置,则需要用到 expect/actual 的方式来实现 HttpClient

比如在 Android 代码中,针对 OkHttp 进行一些定制

actual val httpClient by lazy 
    HttpClient(OkHttp) 
        engine 
            config 
                // 禁止重定向
                followRedirects(false)
            

            // 加入 Stetho 方便 Debug
            addNetworkInterceptor(StethoInterceptor())
        
    

或者对 iOS 的 NSURLSession 进行一些配置

actual val httpClient by lazy 
    HttpClient(Ios) 
        engine 
            configureRequest 
                // 如果 HttpClient 需要在后台进行上传、下载
                NSURLSessionConfiguration.backgroundSessionConfiguration("xxx").apply 
                    // 添加统一的 Headers
                    HTTPAdditionalHeaders = mapOf("a" to "b")
                
            
        
    

完成 HttpClient 的创建和配置以后,我们就可以在 Common 目录中的 Kotlin 代码中发起网络请求了

发送一个简单的 HTTP 请求

代码非常简单,只需要一行,但因为 Ktor 中大量使用了协程的开发理念,所以需要符合 Kotlin 协程的基本思想和写法,可以参考:https://kotlinlang.org/docs/coroutines-basics.html

// 写法1:
fun sendGet() 
    GlobalScope.launch(Dispatchers.Default) 
        val res: HttpResponse = httpClient.get("https://www.baidu.com")
    


// 写法2:
suspend fun sendGetAsync() 
    val res: HttpResponse = httpClient.get("https://www.baidu.com")

这里需要注意的是,由于 iOS 并不支持协程,所以在 iOS 代码中,如果不使用默认的 CoroutineContext,则需要使用 GCD 单独实现一个 CoroutineDispatcher 实例并作为 launch 方法的参数传入,如下面代码所示:

internal actual val ApplicationDispatcher: CoroutineDispatcher = NsQueueDispatcher(dispatch_get_main_queue())

internal class NsQueueDispatcher(
    private val dispatchQueue: dispatch_queue_t
) : CoroutineDispatcher() 
    override fun dispatch(context: CoroutineContext, block: Runnable) 
        dispatch_async(dispatchQueue) 
            block.run()
        
    

最后在实际的 Android 和 iOS 工程当中,调用 sendGet() 即可发送网络请求,完成请求之后,别忘记调用 close() 来关闭和释放 HttpClient 实例,以免造成内存泄露

如果 HttpClient 的实例只做一次网络请求,也可以使用 use 语法,在结束时自动进行 close 操作

val status = HttpClient().use  client ->
    // ...

由于我们还没有处理网络请求的响应,所以需要使用 Charles 或 Fiddler 抓包才能看到发送的网络请求

自定义请求

众所周知,一条 HTTP 请求报文,包含几个重要部分:Method、Host、Path 及 Query、HTTP 版本、Headers、Body(主要是 POST、PUT)

这些内容,Ktor 也都支持定义,封装在 HttpRequestBuilder 当中,并在 HttpClient 的初始化闭包中的 defaultResult 子闭包,以及 HttpClient 的各个扩展方法中,作为最后一个参数的 Block 参数返回,即:可在 HttpClient.request 或 get、post 等扩展方法调用的后的闭包中操作

如果需要添加统一的公共参数,或者 Headers(包括 Cookies、User-Agent),可以在 HttpClient 初始化时,添加 defaultRequest 闭包,并利用其 HttpRequestBuilder 类型的参数进行配置,这样就是可以使所有使用当前 HttpClient 实例的发送的网络请求,保持统一配置

HttpClient 
    defaultRequest 
        header("CommonHeader", "KMM")
        parameter("CommonParam", "666")
        cookie("USER_ID", "123456")
        // ...
    

如果只是给某一个请求添加自定义的配置,只需要在 request 方法调用后的闭包中处理即可

fun sendGet() 
    GlobalScope.launch(Dispatchers.Default) 
        val res: HttpResponse = httpClient.request ("https://www.baidu.com") 
            method = HttpMethod.Get
            header("TestHeader", "1")
            header("MyHeader", "2")
            userAgent("KMM Http Client")
            cookie("USER_ID", "123456")

            formData 
                // 示例写法,实际需要处理字节流
                append("image", ByteArray(256))
            
        
    

通过 Charles 抓包,就可以看到经过自定义配置后,通过 Ktor 发出的 HTTP 请求

处理响应

和常见的 HTTP 请求框架(如:OkHttp、AFNetworking)类似,Ktor 也支持获取多种类型的返回数据,具体为以下三种:

  • 原始响应 Body:

    获取原始的 HTTP 响应体内容,比如 HTML、纯文本字符串、二进制数据等

  • JSON 对象:

    如果响应内容为纯 JSON 字符串,Ktor 可以在返回响应之前直接解析成你需要的对象,但是需要配置 JSON 插件,并结合 kotlinx.serialization 进行使用

  • 流式数据:

    如文件下载这种数据量比较大,或是异步、非阻塞式返回形式的数据,可能会用到流式的 HTTP 响应接收模式

下面使用几段示例代码,来实现以上几种响应类型的处理

获取原始类型

  • 获取 String 类型(纯文本)的 Body
val httpResponse: HttpResponse = client.get("https://ktor.io/")
val stringBody: String = httpResponse.body()
  • 获取 ByteArray 类型(二进制)的 Body
val httpResponse: HttpResponse = client.get("https://ktor.io/")
val byteArrayBody: ByteArray = httpResponse.body()

进行类型自动转换

如果你配置了 Kotlinx.serialization 插件,并且声明了对应数据结构的实体类,则 Ktor 可以自动进行 JSON 解析

首先需要添加 Ktor 用于进行类型转换的依赖,也被称为 ContentNegotiation

implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")

其次需要添加 Kotlinx.serialization 依赖

implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")

注意:这里添加以后,会将 Kotlinx.Serialization 相关的依赖传递进来,建议显式指定版本

然后在 HttpClient 初始化的时候,install 这个类型插件 ContentNegotiation,并把 JSON 插件配置在里面

val client = HttpClient() 
    install(ContentNegotiation) 
        json()
    

熟悉 Kotlinx.Serialization 的同学可以使用 Json 语法来和直接使用 Kotlin.Serialization 一样进行全局解析配置

这里定义一个和请求结果 JSON 结构一致的 data class,并配置好解析规则

@Serializable
data class Student(
    @SerialName("user_id")
    val id: String,
    @SerialName("user_name")
    val name: String,
    @SerialName("age")
    val age: Int,
)
val httpResponse: HttpResponse = client.get("https://api.xxx.com/student?id=xxx")
val xxx: Student = httpResponse.body()
println(xxx.name)  // 张三

流式数据

如果需要下载文件,择需要用到流式数据的形式,来处理 HTTP 响应

val client = HttpClient(CIO)
val file = File.createTempFile("files", "index")

runBlocking 
    client.prepareGet("https://ktor.io/").execute  httpResponse ->
        val channel: ByteReadChannel = httpResponse.body()
        while (!channel.isClosedForRead) 
            val packet = channel.readRemaining(DEFAULT_BUFFER_SIZE.toLong())
            while (!packet.isEmpty) 
                val bytes = packet.readBytes()
                file.appendBytes(bytes)
                println("Received $file.length() bytes from $httpResponse.contentLength()")
            
        
        println("A file saved to $file.path")
    

Ktor 的其他功能

Server 能力

Ktor 是个很强大的网络库,不但提供了 HTTP 客户端所需要的各种常见功能,也提供了 HTTP Server 的能力,虽不能与 nginx 这种专业的 HTTP Server 相提并论,但用作测试还是不错的

文档:https://ktor.io/docs/intellij-idea.html

WebSocket

除了常见的 HTTP API,Ktor 对 WebSocket 的支持相当友好,Chat ServerChat Client

以上关于 Ktor 的介绍就不再详细展开了,有需要的话,可以参考 Ktor 官网的文档:https://ktor.io/docs/welcome.html,内容也十分详细!

KMM 网络能力建设

直接使用 Ktor 建设网络能力,所带来的影响

  • 主要优点
    • 整体性好,API 统一
    • 可借助 Ktor 的所有新增能力
    • 友好支持协程、Kotlinx.Serialization 等 Kotlin 工具链
    • 没有历史包袱
  • 部分缺点
    • 无法再利用 App 已有网络组件的能力
    • 公共参数、Headers 等需要从 0 开始重新建设
    • 在一定程度上导致包体积增大(尤其是 iOS)
    • 存在一些不稳定因素(New Memory、协程等)

综合 Ktor 在 KMM 项目中集成的一些优点和缺点,个人认为如果你需要使用 KMM 从零开始开发一个 App,且不太过分在意 iOS 平台的包体积影响,可以优先考虑使用 Ktor,这样 API 和各种网络请求流程会更加统一,也能够结合 Ktor 的各类插件,在一定程度上提升开发效率。

但是如果你需要在原有已经非常成熟的 App 中应用 KMM 技术,重构或新开发某些功能,使用 Ktor 往往不会带来更多的收益。这些 App 大多已经拥有非常完善的网络库了,无论是业务上的公参、统计、异常处理、免流量,还是 HTTP/3、IP 直通、HTTP DNS、SSL 等技术迭代,可谓是遍地开花。所以在这种情况下,个人认为应当尽可能充分地利用现有网络库的能力,在 KMM 层进行 API 和流程的抹平!

推荐的网络能力建设方式

结合实际开发过程中的情况,个人更推荐使用 expect/actual 模式来桥接双端真正的 API。

且由于 HTTP 请求这种业务逻辑,各平台都比较接近,也不存在直接操作 UI 的需求,所以也非常适合使用 KMM 去做逻辑统一。

/**
 * HTTP 请求公共接口
 * 
 * @param method 请求方法 [HttpMethod]
 * @param url URL
 * @param headers 请求 Header,Key-Value
 * @param params 参数,Key-Value
 * @param bodyType POST 请求的 Body 类型,可能为 JSON 或 URLParams
 * @param succeedCallback 成功回调,在状态码为 200 时回调 Header 和 Body
 * @param failedCallback 失败回调,回调错误码和信息
 */
expect fun commonHttpRequest(
    method: HttpMethod,
    url: String,
    headers: Map<String, Any?>?,
    params: Map<String, Any>?,
    bodyType: HttpPostBodyTypes = HttpPostBodyTypes.URL_PARAMS,
    succeedCallback: (resHeaders: Map<String, Any>?, body: String?) -> Unit,
    failedCallback: (errCode: Int, errMsg: String?) -> Unit
)

如上面的代码片段所示,可以在 KMM 的 commonMain 目录中定义类似的 HTTP 请求接口,后续在 KMM 代码中即可使用该方法发送并处理 HTTP 请求。

但其 actual 的实现应当考虑的相对周全一些,例如:Android 端可以桥接 [OkHttp](square/okhttp: Square’s meticulous HTTP client for the JVM, Android, and GraalVM. (github.com)),iOS 端可以桥接 [AFNetworking](AFNetworking/AFNetworking: A delightful networking framework for iOS, macOS, watchOS, and tvOS. (github.com))。当然,如果项目中有基于系统或第三方库 API 进行二次开发的网络能力,应当桥接二次开发后的 API。

例如,淘宝客户端内部的 ANetwork 网络框架等等……

以 OkHttp(4.0 以上版本)的基本使用为例,Android 端的 actual 实现可以参考下面的代码:

actual fun commonHttpRequest(
    method: HttpMethod,
    url: String,
    headers: Map<String, Any?>?,
    params: Map<String, Any>?,
    bodyType: HttpPostBodyTypes = HttpPostBodyTypes.URL_PARAMS,
    succeedCallback: (resHeaders: Map<String, Any>?, body: String?) -> Unit,
    failedCallback: (errCode: Int, errMsg: String?) -> Unit
) 
    val request = Request.Builder().apply 
        val httpUrl = url.toHttpUrlOrNull() ?: return@apply
        headers?.keys?.forEach  key ->
            val value = headers[key] ?: return@forEach
            header(key, value.toString())
        
        if (method == HttpMethod.POST) 
            val reqBodyBuilder = FormBody.Builder()
            params?.keys?.forEach  key ->
                val value = params[key] ?: return@forEach
                reqBodyBuilder.addEncoded(key, value)
            
            method("POST", reqBodyBuilder.build())
            url(httpUrl)
         else 
            val urlBuilder = httpUrl.newBuilder().apply 
                params?.keys?.forEach  key ->
                    val value = params[key] ?: return@forEach
                    addEncodedQueryParameter(key, value)
                
            
            url(urlBuilder.build())
        
    .build()
    val call = okHttpClient.newCall(request)
    call.enqueue(object : Callback 
        override fun onFailure(call: Call, e: IOException) 
            failedCallback(e.message)
        

        override fun onResponse(call: Call, response: Response) 
            try 
                if (response.code == 200) 
                    succeedCallback(response.headers.toMap(), response.body?.string() ?: "")
                    response.body?.closeQuietly()
                 else 
                    failedCallback.invoke(ERR_CODE_FAILED, "Response is not 200!")
                
             catch (e: Exception) 
                e.printStackTrace()
                failedCallback.invoke(ERR_CODE_FAILED, "Response is not 200!")
            
        
    )

使用 URLSession 的示例代码:

actual fun commonHttpRequest(
    method: HttpMethod,
    url: String,
    headers: Map<String, Any?>?,
    params: Map<String, Any>?,
    bodyType: HttpPostBodyTypes,
    succeedCallback: (resHeaders: Map<String, Any>?, body: String?) -> Unit,
    failedCallback: (errCode: Int, errMsg: String?) -> Unit
) 
    // 伪代码,不保证能运行
    val req = NSMutableURLRequest.requestWithURL(NSURL.URLWithString(url)!!)
    req.setHTTPMethod(if (method == HttpMethod.GET) "GET" else "POST")
    req.setAllHTTPHeaderFields(headers as Map<Any?, *>)
    val session = NSURLSession.sharedSession
    session.dataTaskWithRequest(req)  data, res, err ->
        // handle response
    

总结

由于网络请求是业务逻辑代码中使用非常频繁的功能,所以在 KMM 中,建设一套适合项目使用的网络能力尤为重要,需要根据项目实际情况选择合理的实现方案,以便实现网络请求开发的效率最大化。

以上是关于KMM 入门处理 HTTP 网络请求的主要内容,如果未能解决你的问题,请参考以下文章

KMM 入门处理 HTTP 网络请求

KMM 入门处理多线程

KMM 入门处理多线程

KMM 入门处理多线程

KMM 入门在现有工程中集成 KMM

KMM 入门在现有工程中集成 KMM