KMP 网络请求： Ktor + Ktorfit 端到端集成

本文梳理在 Kotlin Multiplatform 项目中，用 Ktor Client 作为底层 HTTP 引擎、Ktorfit 作为声明式网络接口的完整流程。

覆盖范围：架构总览 → 添加依赖 → 初始化 HttpClient（JSON 解析 / 日志 / 401 重试 + token 刷新）→ 双端初始化 → Ktorfit 接口定义与发送请求 → 生成与部署命令。

配套的网络缓存实现方案见 KMP 网络请求缓存，该文在 Ktorfit 网络层之上实现了”先读缓存、未命中再走网络并写回”的网络缓存读写，本文聚焦于网络层本身。

适用版本：Kotlin 2.4.0 · Ktor 3.5.1 · Ktorfit 2.7.5 · KSP 2.4.0-1.0.32 · kotlinx.serialization 1.7.3 · kotlinx.coroutines 1.11.0

架构总览

Ktor + Ktorfit 在整体架构中的位置

本项目采用 MVVM + Clean Architecture。网络层位于 Data Layer，对上是 Repository，对下是平台 HTTP 引擎。Ktor 负责”怎么发请求”，Ktorfit 负责”把接口描述成请求”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
┌─────────────────────────────────────────────────────────────┐
│                         UI Layer                             │
│   Compose UI (shared ViewModel)   │   原生 UI (Android/iOS)  │
│   collectAsState / StateFlow      │   Activity / SwiftUI     │
└───────────────────────────┬───────┴────────────┬─────────────┘
                            │                     │
                            ▼                     ▼
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                            │
│   UseCase → Repository 接口（suspend 函数 / Flow）           │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                              │
│   RepositoryImpl → Remote DataSource                        │
│        │                                                    │
│        ▼                                                    │
│   ┌──────────────────────────────────────────────┐         │
│   │            Network Layer（本文重点）           │         │
│   │  Ktorfit 接口（@GET/@POST 声明式）            │         │
│   │        │ createKtorfit(httpClient)            │         │
│   │        ▼                                      │         │
│   │  Ktor HttpClient（install 插件：             │         │
│   │    ContentNegotiation / Logging / AuthRetry） │         │
│   └───────────────────┬──────────────────────────┘         │
└───────────────────────┼────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                    Platform Layer                            │
│   Android: OkHttp Engine          iOS: Darwin Engine        │
│   （通过 expect/actual platformHttpEngine() 注入）           │
└─────────────────────────────────────────────────────────────┘

两种 UI 消费方式

网络层（Ktor + Ktorfit）对上是与 UI 无关的纯 Kotlin，因此同一套代码能被两类 UI 复用：

维度 ① Compose UI（标准 KMP） ② 原生 UI（Android / iOS 壳）
入口 shared 模块的统一 ViewModel（如 RTViewModel） 各端自己的 ViewModel：Android androidx.lifecycle.ViewModel，iOS ObservableObject（SwiftUI @StateObject）
调用路径 共享 ViewModel → UseCase → Repository → Ktorfit 各端 ViewModel → UseCase → Repository → Ktorfit（与 Compose 路径一致，只是 ViewModel 落在平台侧）
状态驱动 StateFlow + collectAsState() Android StateFlow/LiveData + repeatOnLifecycle；iOS Published 属性 + ObservableObject
网络层差异 无差异 无差异（Ktorfit 用法完全不变）

结论：Ktor + Ktorfit 只写在 commonMain / 平台引擎层，UI 用 Compose 还是原生、ViewModel 是共享还是各端自有，都只是”谁来调 Repository“，不影响网络层代码。下方直接暴露一个 object NetworkGraph 装配好 HttpClient 与 Ktorfit，两类 UI 都从它拿接口。

关于在网络层之上叠加缓存读写、实现网络缓存（先读缓存、未命中再走网络并写回）的完整做法，见 KMP 网络请求缓存。

本文范围

  • ✅ 依赖配置（含 kotlinx-serialization-json）
  • ✅ HttpClient 初始化（JSON 解析 / Logging / 401 重试 + token 刷新）
  • ✅ 双端引擎（expect/actual）
  • ✅ Ktorfit 接口与发送请求
  • ✅ 在 Ktorfit 之上叠加网络缓存读写（实现方式见 KMP 网络请求缓存）

一、添加依赖

1.1 版本目录 gradle/libs.versions.toml

在 [versions] 中声明版本：

1
2
3
4
5
6
7
[versions]
kotlin = "2.4.0"
ksp = "2.4.0-1.0.32"
ktor = "3.5.1"
ktorfit = "2.7.5"
serialization = "1.7.3"
coroutines = "1.11.0"

在 [libraries] 中声明具体库：

1
2
3
4
5
6
7
8
9
10
11
12
[libraries]
# Ktor 核心与平台引擎
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }      # Android 引擎
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }      # iOS 引擎
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-client-logging = { module = "io.ktor:ktor-client-logging", version.ref = "ktor" }
# JSON 序列化（kotlinx-serialization-json）
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "serialization" }
# Ktorfit（声明式接口 + KSP 代码生成）
ktorfit-lib = { module = "de.jensklingenberg.ktorfit:ktorfit-lib", version.ref = "ktorfit" }
ktorfit-ksp = { module = "de.jensklingenberg.ktorfit:ktorfit-ksp", version.ref = "ktorfit" }

1.2 模块 build.gradle.kts

任意使用 Ktorfit（即定义 @GET/@POST 接口）的模块，必须应用 KSP 插件并引入 ktorfit-ksp：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.ksp)               // ★ 用 Ktorfit 必须配对应 KSP
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.ktor.client.core)
            implementation(libs.ktor.client.content.negotiation)
            implementation(libs.ktor.client.logging)
            implementation(libs.kotlinx.serialization.json)
            implementation(libs.ktorfit.lib)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
    }
}

// ★ Ktorfit 的 KSP 生成：把 ktorfit-ksp 加到各 KSP 配置
dependencies {
    add("kspCommonMainMetadata", libs.ktorfit.ksp)
    add("kspAndroid", libs.ktorfit.ksp)
    add("kspIosX64", libs.ktorfit.ksp)
    add("kspIosArm64", libs.ktorfit.ksp)
    add("kspIosSimulatorArm64", libs.ktorfit.ksp)
}

最小说明：只要你的模块里写了 @GET/@POST 这类 Ktorfit 接口，就要像上面一样配 KSP + ktorfit-ksp；纯消费接口（只 create<XxxApi>()）的模块则不需要 KSP。

二、初始化 HttpClient

这一步是网络层核心：配置 JSON 解析、日志、401 重试与 token 刷新。所有逻辑都写在 commonMain，引擎通过 platformHttpEngine() 注入。

2.1 kotlinx-serialization-json 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// commonMain / NetworkJson.kt
import kotlinx.serialization.json.Json

/**
 * 统一 JSON 解析配置：
 * - ignoreUnknownKeys：后端多字段不崩
 * - isLenient：容错（如引号缺失、数字当字符串）
 * - encodeDefaults：默认字段也参与序列化
 */
val networkJson = Json {
    ignoreUnknownKeys = true
    isLenient = true
    encodeDefaults = true
    explicitNulls = false
}

2.2 Token 刷新的 Manager 接口（需先定义）

401 重试依赖 token 刷新能力。先定义两个接口，由平台或业务层实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// commonMain / token/TokenContracts.kt
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock

/** 本地 token 存取（实现层可接 MMKV / DataStore / Keychain） */
interface TokenManager {
    fun getAccessToken(): String?
    fun getRefreshToken(): String?
    fun saveTokens(accessToken: String, refreshToken: String, expiresIn: Long)
    fun clearAccessToken()
    fun clearTokens()
}

/** 远端刷新：拿 refreshToken 换新的 AuthToken */
interface TokenRefresher {
    suspend fun refresh(refreshToken: String): AuthToken
}

/** 刷新返回结构 */
data class AuthToken(
    val accessToken: String,
    val refreshToken: String,
    val accessTokenValidTime: Long  // 过期时间戳（毫秒）
)

/**
 * 刷新协调器：用 Mutex 保证并发 401 只刷新一次。
 * 业务层提供 TokenManager + TokenRefresher 即可。
 */
class TokenRefreshManager(
    private val tokenManager: TokenManager,
    private val refresher: TokenRefresher
) {
    private val mutex = Mutex()
    private var isRefreshing = false

    /**
     * 执行一次 token 刷新。并发调用时，只有第一个真正触发刷新，
     * 其余等待后用同一份新 token。
     */
    suspend fun refreshToken(): Result<AuthToken> = runCatching {
        mutex.withLock {
            if (isRefreshing) {
                val at = tokenManager.getAccessToken()
                requireNotNull(at) { "刷新未完成且本地无 accessToken" }
                return@withLock AuthToken(at, tokenManager.getRefreshToken().orEmpty(), 0L)
            }
            isRefreshing = true
            try {
                val refreshToken = requireNotNull(tokenManager.getRefreshToken()) { "无 refreshToken" }
                val newToken = refresher.refresh(refreshToken)
                tokenManager.saveTokens(
                    newToken.accessToken,
                    newToken.refreshToken,
                    newToken.accessTokenValidTime
                )
                newToken
            } // 注意：此处为简化示例，真实应把 refresh() 放在 try 内
        }
    }
}

2.3 构建 HttpClient（install 插件）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
// commonMain / HttpClientFactory.kt
import io.ktor.client.*
import io.ktor.client.engine.*
import io.ktor.client.plugins.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.plugins.logging.*
import io.ktor.client.request.*
import io.ktor.http.*
import io.ktor.util.AttributeKey

/**
 * 创建 HttpClient。
 * @param engine 平台引擎（Android=OkHttp, iOS=Darwin），由 expect/actual 提供
 */
fun createHttpClient(
    engine: HttpClientEngine,
    tokenManager: TokenManager,
    refresher: TokenRefresher
): HttpClient {
    val refreshManager = TokenRefreshManager(tokenManager, refresher)

    return HttpClient(engine) {
        // ① JSON 解析（kotlinx-serialization-json）
        install(ContentNegotiation) {
            json(networkJson)
        }

        // ② 日志
        install(Logging) {
            logger = Logger.DEFAULT
            level = LogLevel.INFO
        }

        // ③ 401 重试 + token 刷新（自定义插件）
        install("AuthRetry") {
            requestPipeline.intercept(HttpRequestPipeline.Before) {
                tokenManager.getAccessToken()?.let { token ->
                    context.headers.append(HttpHeaders.Authorization, "Bearer $token")
                }
            }
            responsePipeline.intercept(HttpResponsePipeline.Receive) {
                if (context.response.status == HttpStatusCode.Unauthorized) {
                    tokenManager.clearAccessToken()
                    val result = refreshManager.refreshToken()
                    if (result.isSuccess) {
                        context.attributes.put(AuthRefreshedKey, true)
                    } else {
                        throw TokenRefreshFailedException("token 刷新失败，需重新登录")
                    }
                }
            }
        }

        // ④ 超时
        install(HttpTimeout) {
            requestTimeoutMillis = 30_000
            connectTimeoutMillis = 15_000
        }
    }
}

class TokenRefreshFailedException(msg: String) : Exception(msg)

val AuthRefreshedKey = AttributeKey<Boolean>("AuthRefreshed")

关键逻辑说明：

  • Logging：LogLevel.INFO 打印请求/响应摘要；DEBUG 看完整 body（注意敏感头）。
  • 401 处理：请求前自动带 Bearer；收到 401 先清本地 accessToken，再走 TokenRefreshManager.refreshToken()（带 Mutex 去重），成功则用新 token 重发，失败抛 TokenRefreshFailedException 由上层跳登录。

2.4 构建 Ktorfit（复用同一 HttpClient）

1
2
3
4
5
6
7
8
9
10
// commonMain / KtorfitProvider.kt
import de.jensklingenberg.ktorfit.Ktorfit

const val BASE_URL = "https://api.example.com/"

fun createKtorfit(httpClient: HttpClient): Ktorfit =
    Ktorfit.Builder()
        .httpClient(httpClient)
        .baseUrl(BASE_URL)
        .build()

三、使用逻辑（双端初始化）

3.1 expect / actual 平台引擎

1
2
3
4
// commonMain / PlatformEngine.kt
import io.ktor.client.engine.*

expect fun platformHttpEngine(): HttpClientEngine
1
2
3
4
// androidMain / PlatformEngine.android.kt
import io.ktor.client.engine.okhttp.OkHttp

actual fun platformHttpEngine(): HttpClientEngine = OkHttp.create()
1
2
3
4
// iosMain / PlatformEngine.ios.kt
import io.ktor.client.engine.darwin.Darwin

actual fun platformHttpEngine(): HttpClientEngine = Darwin.create()

3.2 平台入口装配

用一个 object 单例把 HttpClient + Ktorfit 装配好，两种 UI 都从它取接口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// commonMain / NetworkGraph.kt
object NetworkGraph {

    private val tokenManager: TokenManager = InMemoryTokenManager()
    private val refresher: TokenRefresher = SampleTokenRefresher()

    val httpClient: HttpClient by lazy {
        createHttpClient(
            engine = platformHttpEngine(),
            tokenManager = tokenManager,
            refresher = refresher
        )
    }

    val ktorfit: Ktorfit by lazy {
        createKtorfit(httpClient)
    }

    inline fun <reified T : Any> api(): T = ktorfit.create<T>()
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// commonMain / SampleImpls.kt（demo 占位实现，真实项目由平台/业务注入）
class InMemoryTokenManager : TokenManager {
    private var access: String? = null
    private var refresh: String? = null
    override fun getAccessToken() = access
    override fun getRefreshToken() = refresh
    override fun saveTokens(accessToken: String, refreshToken: String, expiresIn: Long) {
        access = accessToken; refresh = refreshToken
    }
    override fun clearAccessToken() { access = null }
    override fun clearTokens() { access = null; refresh = null }
}

class SampleTokenRefresher : TokenRefresher {
    override suspend fun refresh(refreshToken: String): AuthToken {
        return AuthToken("new-access-token", refreshToken, System.currentTimeMillis() + 3600_000)
    }
}

Android 原生 UI 入口：NetworkGraph.httpClient 通过 lazy 在首次访问时装配（引擎用 OkHttp）。
iOS 原生 UI 入口：Swift/ObjC 侧首次调用 NetworkGraph 的 Kotlin 函数时同理（引擎用 Darwin）。

四、Ktorfit 接口定义与发送请求

4.1 数据类（@Serializable）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// commonMain / model/User.kt
import kotlinx.serialization.Serializable

@Serializable
data class User(
    val id: String,
    val name: String,
    val avatar: String? = null
)

@Serializable
data class LoginRequest(
    val username: String,
    val password: String
)

@Serializable
data class LoginResponse(
    val token: String,
    val user: User
)

4.2 声明式接口（@GET / @POST）

1
2
3
4
5
6
7
8
9
10
11
12
13
// commonMain / api/UserApi.kt
import de.jensklingenberg.ktorfit.http.*

interface UserApi {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: String): User

    @GET("users")
    suspend fun listUsers(@Query("page") page: Int = 1): List<User>

    @POST("auth/login")
    suspend fun login(@Body request: LoginRequest): LoginResponse
}

4.3 两种获取接口的方式

1
2
3
4
5
// ① 旧语法（Ktorfit 2.7.x 默认仍可用，无需额外生成）
val userApi: UserApi = NetworkGraph.ktorfit.create<UserApi>()

// ② 新语法（KSP 生成的扩展函数 createUserApi()，需先执行 KSP 生成，见第五章）
// val userApi: UserApi = NetworkGraph.ktorfit.createUserApi()

新旧语法差异：

  • create<T>()：运行时反射式，即写即用，适合 demo / 快速验证。
  • createUserApi()：KSP 在编译期为每个接口生成的具体扩展函数，类型更安全、无运行时反射，但必须先把 Ktorfit 接口编译生成（./gradlew setupKsp 或 compileKotlinMetadata）。未生成前 IDE 会标红。

4.4 发送请求（调用示例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// commonMain 或任意调用方
suspend fun fetchUserDemo(): Result<User> = runCatching {
    val api = NetworkGraph.api<UserApi>()
    api.getUser("123")
}

// Compose UI 中
val userState = remember { mutableStateOf<User?>(null) }
LaunchedEffect(Unit) {
    fetchUserDemo().onSuccess { userState.value = it }
                 .onFailure { /* 处理 401 刷新失败 / 网络错误 */ }
}

// 原生 UI（Android Activity）中
lifecycleScope.launch {
    val result = runCatching { NetworkGraph.api<UserApi>().listUsers(1) }
    // 更新原生视图
}

错误处理：网络异常、401 刷新失败（TokenRefreshFailedException）都会向上抛出，调用方用 try/catch 或 runCatching 统一处理；401 刷新成功时会在 AuthRetry 插件内重发，对调用方透明。

五、生成与部署命令

5.1 KSP 代码生成（Ktorfit 接口 → 实现）

使用 Ktorfit 的 @GET/@POST 接口后，需先生成 KSP 代码（尤其用新语法 createUserApi() 时）：

1
2
3
4
5
6
7
8
# 方式一：一键生成所有 Ktorfit 接口
./gradlew setupKsp

# 方式二：仅生成指定模块的 metadata（等价于编译 commonMain）
./gradlew :core:compileKotlinMetadata

# 方式三：构建时自动触发（assemble/run 会先跑 KSP）
./gradlew assemble

Windows PowerShell 下用 ./gradlew 若被拦截，可用 gradlew.bat；或用 .\gradlew setupKsp。

5.2 Android 构建 / 安装 / 运行

1
2
3
4
5
6
7
8
# 打 Debug 包
./gradlew :androidApp:assembleDebug

# 安装到已连接设备/模拟器
./gradlew :androidApp:installDebug

# 安装并直接启动
./gradlew :androidApp:runDebug

Android 侧引擎为 OkHttp（platformHttpEngine() 返回 OkHttp.create()），无需额外原生配置。

5.3 iOS 构建 / 模拟器 / 真机

⚠️ iOS 构建必须在 macOS + Xcode 环境下。Windows 上 iosMain target 在 IDE 中标红是正常现象，不影响 Android 编译。

1
2
3
4
5
6
7
8
# 产物为 .framework（core / shared），供 iOS 工程（Xcode）集成
./gradlew :shared:assembleSharedXCFramework

# 仅编译 iOS 模拟器架构（arm64 模拟器）
./gradlew :shared:compileKotlinIosSimulatorArm64

# 仅编译 iOS 真机架构（arm64）
./gradlew :shared:compileKotlinIosArm64

然后在 Xcode 中：

  • 模拟器：直接 Run（SwiftUI 调用 NetworkGraph.api<UserApi>()）
  • 真机：签名后 Run；引擎为 Darwin（Darwin.create()）

iOS 侧若用 SwiftUI 原生 UI，直接调用 KMP 暴露的 suspend 函数，网络层完全一致。

5.4 CI 说明

环境 用途 注意事项
macOS runner 同时构建 Android + iOS iOS 必须 macOS；Xcode 版本需匹配 Kotlin 工具链
Linux/Windows runner 仅 Android / 共用模块校验 iOS target 会被跳过或标红，属正常
KSP 生成 每次 build 自动跑 若缓存异常，先 ./gradlew clean 再 setupKsp

六、常见问题

Q1：Ktorfit 接口标红 / createUserApi() 找不到？
未执行 KSP 生成。先跑 ./gradlew setupKsp 或 :core:compileKotlinMetadata；若只用旧语法 create<T>() 则无需生成。

Q2：401 没触发重发？
确认 AuthRetry 插件已 install、响应状态码为 401、且 TokenManager.getRefreshToken() 非空。TokenRefreshManager 的 Mutex 保证并发只刷新一次。

Q3：JSON 解析报错 “Unexpected JSON token”？
后端字段与数据类不一致时，确认 networkJson 已设 ignoreUnknownKeys = true / isLenient = true，且数据类有 @Serializable。

Q4：Windows 下 iOS target 标红 / 编译失败？
iOS 编译需 macOS + Xcode，Windows 仅做 Android。标红但 Android 正常属预期。

Q5：版本对齐？
本文版本（Ktor 3.5.1 / Ktorfit 2.7.5 / KSP 2.4.0-1.0.32 / serialization 1.7.3）需与项目版本目录一致，改动时同步更新，避免 Kotlin/KSP/Ktor 版本错配。

参考链接

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true