KMP 网络请求缓存：使用MMKV实现缓存读写

本文梳理 Kotlin Multiplatform 中网络请求缓存的读写方案：在 Ktor + Ktorfit 网络层之上，叠加”先读缓存、未命中再走网络、响应透明写回”的能力。代码与工程结构以 kmpDev 项目（com.ctrip.flight.mmkv + Ktor/Ktorfit）为准。

配套文档：KMP 中 Ktor + Ktorfit 端到端集成（网络层初始化与本文化缓存的 Ktorfit / HttpClient / 401 重试共用）。

架构总览

缓存位于 Data Layer 的 Repository 与 Ktorfit 之间，对上层（UseCase / ViewModel）透明。底层依赖两个能力：网络层（:core/network，见 dev-ktor.md）与存储层（:core/cache，封装 MMKV_KMP）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌──────────────────────────────────────────────────────────────────┐
│                  ViewModel / UseCase（调用方，不感知缓存）            │
└───────────────────────────┬──────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│   CacheThenNetworkStrategy（:core/network/strategy）               │
│    ├─ 读：cacheManager.getRawJson(key) 命中 → emit FromCache      │
│    └─ 写：CacheWriteConfig.wrap { fetcher() } → HttpCachePlugin   │
│         onResponse 透明写入 cache:body:<key>                      │
└───────────────────────────┬──────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│   CacheManager / MMKVCacheManagerImpl（:core/cache）               │
│   ├─ putRawJson / getRawJson（零转换原始 JSON）                   │
│   └─ 依赖 MMKV_KMP（com.ctrip.flight.mmkv）                       │
└───────────────────────────┬──────────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│   Ktorfit 网络层（:core/network）NetworkGraph.api<T>()            │
└──────────────────────────────────────────────────────────────────┘

模块归属一览

模块 职责 本文涉及
:core/cache MMKV 封装、CacheManager 接口与实现 initMMKV、CacheManager、MMKVCacheManagerImpl
:core/network Ktor 客户端、CacheThenNetworkStrategy 缓存读写策略、透明写插件
:shared / :feature:* Repository / UseCase 调用策略
:androidApp / :iosApp 平台壳层 应用入口 initMMKV

iOS 代码在 kmpDev 设计阶段已就绪（Windows 下无法编译 iOS target，但源码存在，下述 iosMain 与 AppDelegate 均为真实代码）。

一、添加依赖

kmpDev 使用 com.ctrip.flight.mmkv:mmkv-kotlin，仅需在 commonMain 添加一个依赖，Android / iOS 实现自动包含：

1
2
3
4
5
6
# gradle/libs.versions.toml
[versions]
mmkv = "1.3.2"

[libraries]
mmkv-kotlin = { module = "com.ctrip.flight.mmkv:mmkv-kotlin", version.ref = "mmkv" }
1
2
3
4
5
6
7
8
// :core/build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.mmkv.kotlin)
        }
    }
}

iOS 额外要求：在 core/build.gradle.kts 的 cocoapods 块中集成 MMKV 原生库：

1
2
3
cocoapods {
    pod("MMKV") { version = "2.4.0" }
}

二、初始化

2.1 平台初始化入口（expect/actual）

各平台初始化 MMKV 的参数不同：Android 传 Context，iOS 传目录路径字符串。

1
2
3
4
5
// :core/cache/CacheInit.kt（commonMain）
package com.example.kmpdev.core.cache

// 各平台初始化 MMKV（参数不同：Android → Context, iOS → String 路径）
expect fun initMMKV(param: Any)
1
2
3
4
5
6
7
8
9
10
11
// :core/cache/CacheInit.android.kt（androidMain）
package com.example.kmpdev.core.cache

import android.content.Context
import com.ctrip.flight.mmkv.initialize

actual fun initMMKV(param: Any) {
    val context = param as Context
    val rootDir = initialize(context)
    // rootDir 即 MMKV 文件存储路径，可用于调试
}
1
2
3
4
5
6
7
8
9
// :core/cache/CacheInit.ios.kt（iosMain）
package com.example.kmpdev.core.cache

import com.ctrip.flight.mmkv.initialize

actual fun initMMKV(param: Any) {
    val rootDir = param as String    // e.g. NSSearchPathForDirectoriesInDomains 结果
    initialize(rootDir)
}

2.2 缓存抽象层（CacheManager 接口 + 元数据）

CacheManager 区分”通用 KV”与”网络缓存”。网络缓存以零转换原始 JSON 存进 MMKV，配合 CacheMeta（写入时间、TTL、版本号）做过期与升级清理。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// :core/cache/CacheManager.kt（commonMain）
interface CacheManager {
    companion object {
        const val MAX_CACHEABLE_JSON_BYTES = 500 * 1024
        const val MAX_CACHE_BYTES = 50L * 1024 * 1024     // 缓存最大占用 50MB
    }

    // ═══ 通用 KV（非网络缓存数据，不会被 trimCache 清理）═══
    suspend fun put(key: String, data: Any)
    suspend fun getString(key: String): String?
    suspend fun putInt(key: String, value: Int)

    // ═══ 网络缓存（MMKV，零转换原始 JSON）═══
    suspend fun putRawJson(key: String, rawJson: String, ttlSeconds: Long)
    suspend fun getRawJson(key: String): String?

    // ═══ 通用 ═══
    suspend fun remove(key: String)
    suspend fun clearAll()
    suspend fun evictExpired()
    suspend fun trimCache()
}
1
2
3
4
5
6
7
// :core/cache/CacheMeta.kt（commonMain）
@Serializable
data class CacheMeta(
    val cachedAt: Long,        // 写入时间戳（epoch millis）
    val ttlSeconds: Long,      // 过期时长（秒）
    val versionCode: Int       // 写入时的应用 versionCode（升级时全局清空）
)

2.3 实现（MMKVCacheManagerImpl）

body 与 meta 分离存储：cache:body:<key> 存原始 JSON，cache:meta:<key> 存元数据。读时校验版本号与 TTL。

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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
// :core/cache/MMKVCacheManagerImpl.kt（commonMain）
import com.ctrip.flight.mmkv.MMKV_KMP
import kotlin.math.ceil
import kotlinx.serialization.json.Json

class MMKVCacheManagerImpl(
    private val mmkv: MMKV_KMP,
    private val versionCode: Int,
    private val maxCacheBytes: Long = CacheManager.MAX_CACHE_BYTES
) : CacheManager {

    private val keyPrefixMeta = "cache:meta:"
    private val keyPrefixBody = "cache:body:"
    private fun metaKey(key: String) = "$keyPrefixMeta$key"
    private fun bodyKey(key: String) = "$keyPrefixBody$key"

    override suspend fun putRawJson(key: String, rawJson: String, ttlSeconds: Long) {
        if (rawJson.encodeToByteArray().size > MAX_CACHEABLE_JSON_BYTES) return
        val meta = CacheMeta(
            cachedAt = Clock.System.now().toEpochMilliseconds(),
            ttlSeconds = ttlSeconds, versionCode = versionCode
        )
        mmkv.set(metaKey(key), Json.encodeToString(meta))
        mmkv.set(bodyKey(key), rawJson)
    }

    override suspend fun getRawJson(key: String): String? {
        val metaRaw = mmkv.getString(metaKey(key)) ?: return null
        val meta = try { Json.decodeFromString<CacheMeta>(metaRaw) } catch (_: Exception) {
            remove(key); return null
        }
        if (meta.versionCode != versionCode) { remove(key); return null }
        if ((Clock.System.now().toEpochMilliseconds() - meta.cachedAt) / 1000 > meta.ttlSeconds) return null
        return mmkv.getString(bodyKey(key))
    }

    override suspend fun remove(key: String) {
        mmkv.removeValueForKey(metaKey(key))
        mmkv.removeValueForKey(bodyKey(key))
    }

    override suspend fun clearAll() {
        mmkv.clearAll()
        mmkv.set("cache:version", versionCode)
    }

    override suspend fun evictExpired() {
        val now = Clock.System.now().toEpochMilliseconds()
        mmkv.allKeys().orEmpty().filter { it.startsWith(keyPrefixMeta) }.forEach { k ->
            val metaRaw = mmkv.getString(k) ?: return@forEach
            try {
                if ((now - Json.decodeFromString<CacheMeta>(metaRaw).cachedAt) / 1000 > 0)
                    remove(k.removePrefix(keyPrefixMeta))
            } catch (_: Exception) { remove(k.removePrefix(keyPrefixMeta)) }
        }
    }

    override suspend fun trimCache() {
        val totalSize = mmkv.totalSize
        if (totalSize <= maxCacheBytes) return
        val allMetaKeys = mmkv.allKeys().orEmpty().filter { it.startsWith(keyPrefixMeta) }
        if (allMetaKeys.isEmpty()) return
        val entries = allMetaKeys.mapNotNull { k ->
            val json = mmkv.getString(k, "")
            if (json.isEmpty()) { mmkv.removeValueForKey(k); null }
            else try { k.removePrefix(keyPrefixMeta) to Json.decodeFromString<CacheMeta>(json).cachedAt }
            catch (_: Exception) { mmkv.removeValueForKey(k); null }
        }
        val keepCount = ceil(entries.sortedBy { it.second }.size / 2.0).toInt()
        entries.sortedBy { it.second }.dropLast(keepCount).forEach { remove(it.first) }
        mmkv.trim()
    }

    // ═══ KV 通用方法 ═══
    override suspend fun put(key: String, data: Any) = putRawJson(key, Json.encodeToString(data), 0)
    override suspend fun getString(key: String): String? = mmkv.getString(key)
    override suspend fun putInt(key: String, value: Int) = mmkv.set(key, value)
}

淘汰策略：不逐条 LRU。写入零开销；启动时 trimCache() 检查 mmkv.totalSize，超限扫描 cache:meta:* 按 cachedAt 排序删一半最旧的。trimCache() 建议 App 启动延迟 2s 后调用（不阻塞冷启动）。版本升级 → clearAll() 清空旧版本缓存。

三、双端初始化（平台壳层）

initMMKV 必须在任何 MMKV 读写之前调用。

Android（androidApp/.../App.kt）：

1
2
3
4
5
6
7
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        initMMKV(applicationContext)   // ★ 传入 Application Context
        // initLogStorage(filesDir) / startKoin { ... } 紧随其后
    }
}

iOS（iosApp/AppDelegate.swift）：

1
2
3
4
5
6
7
8
9
import shared

func application(_ application: UIApplication, ...) -> Bool {
    let docDir = NSSearchPathForDirectoriesInDomains(
        .documentDirectory, .userDomainMask, true
    ).first!
    AppKt.doInitMMKV(param: docDir)
    return true
}

调用顺序：① initMMKV → ② initLogStorage → ③ startKoin（Koin 注入 CacheManager 后可被业务使用）。

四、使用逻辑（从声明到调用）

4.1 缓存参数传递（CacheWriteConfig）

缓存写通过协程上下文在策略层 → 插件间传递，避免逐层透传参数。

1
2
3
4
5
6
7
8
9
10
11
12
13
// :core/network/plugin/CacheWriteConfig.kt（commonMain）
import io.ktor.client.plugins.*
import kotlinx.coroutines.*

class CacheWriteConfig(
    val cacheKey: String,
    val ttlSeconds: Long
) : AbstractCoroutineContextElement(CacheWriteConfig) {
    companion object Key : CoroutineContext.Key<CacheWriteConfig>

    suspend fun <T> wrap(block: suspend () -> T): T =
        withContext(this) { block() }
}

4.2 透明缓存写插件（HttpCachePlugin）

网络响应成功时，由插件把原始 JSON 透明写入 CacheManager。业务代码无感知。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// :core/network/plugin/HttpCachePlugin.kt（commonMain）
fun createHttpCachePlugin(cacheManager: CacheManager) = createClientPlugin("HttpCachePlugin") {
    onResponse { response ->
        val config = coroutineContext[CacheWriteConfig.Key]
        if (config != null && response.status.isSuccess()) {
            val bodyBytes = response.body<ByteArray>()
            cacheManager.putRawJson(
                key = config.cacheKey,
                rawJson = bodyBytes.decodeToString(),
                ttlSeconds = config.ttlSeconds
            )
        }
    }
}

4.3 缓存读写策略（CacheThenNetworkStrategy）

这是网络请求缓存的核心。读缓存由策略直接调 cacheManager.getRawJson()；写缓存通过 CacheWriteConfig.wrap { fetcher() } 注入上下文，由 4.2 的 HttpCachePlugin 在 onResponse 透明完成。

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
// :core/network/strategy/CacheThenNetworkStrategy.kt（commonMain）
class CacheThenNetworkStrategy(
    private val cacheManager: CacheManager,
    private val authRetryHandler: AuthRetryHandler,   // ★ 401→刷新→重试（见 dev-ktor.md）
    private val json: Json = Json { ignoreUnknownKeys = true; isLenient = true }
) {
    private val inFlight = mutableMapOf<String, Boolean>()
    private val inFlightMutex = Mutex()

    suspend inline fun <reified T> execute(
        policy: CachePolicy,
        cacheKey: String,
        ttlSeconds: Long = 300,
        noinline fetcher: suspend () -> T
    ): Flow<RequestResult<T>> = flow {

        // —— 读缓存：NO_CACHE 策略直接走网络 ——
        if (policy == CachePolicy.NO_CACHE) {
            try {
                val data = authRetryHandler.execute { fetcher() }
                emit(RequestResult.FromNetwork(data))
            } catch (e: Exception) {
                if (e is AuthException) return@flow
                emit(RequestResult.Error(classifyError(e)))
            }
            return@flow
        }

        // —— 读缓存：命中则立即 emit FromCache（UI 秒开）——
        var hasCache = false
        val rawJson = cacheManager.getRawJson(cacheKey)
        if (rawJson != null) {
            hasCache = true
            try { emit(RequestResult.FromCache(json.decodeFromString(rawJson))) }
            catch (_: Exception) { cacheManager.remove(cacheKey) }
        }

        // —— 单飞控制：同 key 并发只发起一次网络 ——
        val isDuplicate = inFlightMutex.withLock {
            if (inFlight[cacheKey] == true) true else { inFlight[cacheKey] = true; false }
        }
        if (isDuplicate) { Logger.d("CacheThenNetwork", "Duplicate: $cacheKey"); return@flow }

        // —— 写缓存：wrap 注入上下文 → HttpCachePlugin 透明写回 ——
        try {
            val data = CacheWriteConfig(cacheKey, ttlSeconds).wrap {
                authRetryHandler.execute { fetcher() }   // ★ 401→刷新→重试原始请求
            }
            emit(RequestResult.FromNetwork(data))
        } catch (e: Exception) {
            if (e is AuthException) return@flow
            val networkError = classifyError(e)
            if (hasCache) {
                emit(RequestResult.NetworkErrorWithCache(networkError, "网络异常，显示的是上次数据"))
            } else {
                emit(RequestResult.Error(networkError))
            }
        } finally {
            inFlightMutex.withLock { inFlight.remove(cacheKey) }
        }
    }
}

配套的数据类：CachePolicy（NO_CACHE / CACHE_THEN_NETWORK）、RequestResult（FromCache / FromNetwork / NetworkErrorWithCache / Error）均位于 :core/cache 与 :core/network/model，详见 kmpDev 阶段文档。

4.4 Repository / UseCase 调用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// :shared/data/UserRepository.kt（commonMain）
class UserRepository(
    private val api: UserApi = NetworkGraph.api(),          // 来自 dev-ktor.md
    private val strategy: CacheThenNetworkStrategy = CacheThenNetworkStrategy(get(), get())
) {
    fun getUserFlow(id: String): Flow<RequestResult<User>> =
        strategy.execute(
            policy = CachePolicy.CACHE_THEN_NETWORK,
            cacheKey = "user:$id",
            ttlSeconds = 300
        ) {
            api.getUser(id)                                // Ktorfit 原始调用
        }
}

4.5 ViewModel 收集

1
2
3
4
5
6
7
8
9
// :feature:user/UserViewModel.kt（commonMain）
class UserViewModel(
    private val repo: UserRepository = UserRepository()
) : ViewModel() {
    val userState = repo.getUserFlow("me")
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), RequestResult.Error(NetworkError.Unknown(Exception())))

    // UI 中按 FromCache / FromNetwork / Error 分别渲染
}

至此形成完整闭环：NetworkGraph.api<T>() 提供 Ktorfit 接口 → CacheThenNetworkStrategy 包裹（读 getRawJson / 写由 HttpCachePlugin 透明完成）→ UserRepository 对外暴露带缓存 Flow → UserViewModel 收集。缓存逻辑全部在 commonMain，与 UI 形态无关。

五、生成与部署命令

缓存不引入额外 KSP，构建命令与 dev-ktor.md 一致：

1
2
3
4
5
6
# Android
./gradlew :androidApp:assembleDebug
./gradlew :androidApp:installDebug

# iOS（缓存层编译进 shared .xcframework）
./gradlew :shared:assembleSharedXCFramework
环境 说明
macOS 同时构建 Android + iOS
Windows 仅 Android；iOS target 标红不影响 Android

六、常见问题

Q1：缓存与 401 刷新冲突吗？
不冲突。401 由 AuthRetryHandler（见 dev-ktor.md）拦截刷新并重试原始请求；缓存写由 HttpCachePlugin 在成功响应后透明完成，重试后的新响应也会写入。

Q2：为什么缓存写要放在 Ktor 插件里、而不是在策略中手动 put？
写缓存通过 CacheWriteConfig 协程上下文传递，由 HttpCachePlugin.onResponse 自动写回，避免在每个 fetcher 里手写写缓存逻辑，也与 401 重试后的新响应自动对齐。

Q3：敏感数据能缓存吗？
NO_CACHE 策略用于登录/支付等安全敏感接口；token 等走 SecureStorage（见 kmpDev 阶段三），不进网络缓存。

参考链接

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