KMP网络层分层设计：Android/iOS/桌面端统一网络请求架构

1. 项目概述：为什么KMP成了Android网络层的新基建？

“AndroidKMP之网络请求”——这六个字背后，不是又一个“Kotlin Multiplatform + Retrofit”的简单拼接，而是一次对Android工程架构底层逻辑的重新校准。我从2019年第一批在生产环境落地KMP的团队开始跟进，到2023年主导三个跨端App的KMP网络模块重构，踩过的坑比写过的代码还多。今天说的不是“怎么用KMP发个HTTP请求”，而是：当业务模块要同时跑在Android、iOS、桌面端甚至未来可能的车载系统上时，网络请求这一最基础的能力，该如何设计才能既不重复造轮子，又不被平台差异拖垮交付节奏？

核心关键词“Android”“KMP”“网络请求”必须放在一起理解——它不是Android专属技术，也不是纯Kotlin语法糖，更不是把Java代码改成Kotlin就完事。真正的难点在于：如何让一套网络逻辑，在Android上能无缝接入OkHttp拦截器链、支持WorkManager后台重试、适配Android 12+的网络权限变更；在iOS上又能调用原生NSURLSession配置TLS证书钉扎、处理后台唤醒限制；同时还要让桌面端（Compose Desktop）不因缺少Context而崩溃，让Web端（WASM）不因CORS被拦死。这不是功能复用，是能力抽象。

我见过太多团队把KMP网络层做成“Retrofit接口定义+Ktor客户端实现”的缝合怪，结果Android侧加个Cookie持久化要改三处，iOS侧加个自签名证书信任要重编译整个模块，最后发现所谓“共享”只剩50%的DTO类。真正稳定的KMP网络方案，必须从协议层就开始分层：数据协议（JSON/Protobuf）、传输协议（HTTP/HTTPS/gRPC）、平台协议（Android Intent广播通知、iOS Notification Center回调、Desktop Tray弹窗）。这三层里，只有数据协议能100%共享，传输协议需按平台定制，平台协议则完全隔离。

适合谁读？如果你正面临这些场景：

• 团队刚引入KMP，但网络模块还在各端各自为政，每次接口变更都要同步改四套代码；
• App已上线，但用户投诉“iOS上传失败率比Android高3倍”，排查发现是iOS后台任务超时策略没对齐；
• 架构师在评审新需求时，被问“这个网络错误提示要不要加埋点”，结果发现Android有Crashlytics、iOS用Firebase、桌面端连日志都没统一入口；
• 或者你只是个Android开发者，想搞懂为什么同事写的KMP网络层在真机调试时总报error: 上传失败:网络请求错误，而模拟器却一切正常。

这篇文章不讲KMP环境搭建（网上教程够多），不堆砌API文档（官方文档更全），只聚焦一件事：把“AndroidKMP之网络请求”从一个标题，变成你能立刻抄作业、能预判风险、能说服团队的技术方案。后面所有内容，都来自我们给某电商App做KMP网络层重构时的真实日志、抓包记录和灰度数据——包括那个让测试同学连续三天睡不着觉的async upload fail error: 代码包大小超过限制问题，根源根本不在网络层，而在KMP模块的Gradle依赖树里混进了两个版本的okio。

2. 整体架构设计：分层不是选择题，是生存必需

2.1 为什么必须放弃“一套代码打天下”的幻想？

先说结论：KMP网络层的终极目标不是代码行数减少，而是故障域隔离。我见过最典型的反面案例，是某金融App的KMP网络模块——他们把所有逻辑（包括OkHttp拦截器、CookieJar、SSL配置）全写在commonMain里，用expect/actual强行桥接平台差异。结果上线后出现诡异问题：Android端某些机型上传大文件必失败，iOS端偶发TLS握手超时，而桌面端根本无法启动。

根因分析后发现：

• Android侧用了OkHttpClient.Builder().cookieJar(CookieJar)，但KMP commonMain里定义的CookieJar接口，actual实现里漏写了androidx.startup.Initializer初始化逻辑，导致首次请求时CookieJar为空；
• iOS侧的actual实现调用了NSURLSessionConfiguration.default，但没设置timeoutIntervalForResource，而金融业务要求上传超时必须≤30秒，系统默认值是60秒；
• 桌面端用Compose Desktop，但commonMain里引用了kotlinx-coroutines-android，导致JVM运行时找不到Dispatchers.Main。

这些问题单看都不难解，但它们暴露了一个致命设计缺陷：把平台强相关逻辑塞进共享层，等于把所有平台的故障概率乘在一起。就像把三台不同型号的发动机硬装进同一辆汽车底盘——表面能跑，但任何一台出问题都会让整车抛锚。

所以我们的架构第一原则：严格分层，物理隔离。不是用文件夹命名区分，而是用Gradle模块强制约束：

• :network:api：纯数据协议层，只含DTO、Request/Response契约、序列化器（Json/Protobuf），100% Kotlin/JVM/JS/WASM兼容；
• :network:transport：传输协议层，按平台拆分为androidMain、iosMain、jvmMain，各自封装OkHttp、NSURLSession、Apache HttpClient；
• :network:platform：平台协议层，完全不共享，Android用BroadcastReceiver监听网络状态，iOS用NWPathMonitor，桌面端用SystemTray。

提示：别被“KMP共享”这个词带偏。KMP的价值不在于“写一次到处跑”，而在于“改一处，所有平台自动受益”。比如修改订单DTO字段，确实只需改api模块；但若要加个全局请求头（如X-App-Version），就必须在每个transport模块里分别实现——这恰恰是好事，因为Android需要从BuildConfig.VERSION_NAME取值，iOS要从Bundle.main.object(for: "CFBundleShortVersionString")读，桌面端则可能从System.getProperty("app.version")获取，强行统一反而增加耦合。

2.2 分层后的模块依赖关系与Gradle配置

实际项目中，模块依赖必须用Gradle的api/implementation精准控制，否则会出现“本该隔离的代码意外泄露”。以下是我们在电商App中验证过的最小可行配置：

// :network:api/build.gradle.kts kotlin { jvm() iosX64() iosArm64() js(IR) { browser() } // 注意：这里不声明android()，因为Android-specific代码在transport模块 sourceSets { val commonMain by getting { dependencies { implementation("io.ktor:ktor-client-content-negotiation:2.3.10") implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.10") } } } }

// :network:transport/build.gradle.kts kotlin { androidTarget { // 显式声明Android target，避免被commonMain的jvm()误用 compilations.all { kotlinOptions { jvmTarget = "17" } } } iosX64() iosArm64() jvm() // 为Compose Desktop准备 sourceSets { val androidMain by getting { dependencies { // 只允许Android特有依赖 implementation("com.squareup.okhttp3:okhttp:4.12.0") implementation("androidx.work:work-runtime-ktx:2.9.0") } } val iosMain by getting { dependencies { // iOS专用依赖，如Apple官方Network框架封装 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") } } val jvmMain by getting { dependencies { implementation("org.apache.httpcomponents:httpclient:4.5.14") } } } }

关键细节说明：

• :network:api模块绝不声明任何平台target（如android()），因为它必须保持纯Kotlin语义，连androidx.annotation都不能引用；
• :network:transport模块的androidMain里，可以放心使用OkHttpClient，但禁止直接new OkHttpClient()——必须通过工厂模式创建，工厂接口定义在api层，actual实现在transport层，这样上层业务代码（如ViewModel）只依赖api，完全感知不到OkHttp存在；
• 所有模块的commonMain必须禁用@OptIn注解，这是KMP的黄金法则：一旦某个API需要@OptIn(ExperimentalSerializationApi::class)，它就不能出现在commonMain里，必须下沉到具体平台实现。

我们曾因疏忽在api模块用了@Serializable修饰嵌套泛型类，导致iOS编译失败——Kotlin/Native对泛型序列化的支持比JVM晚两个大版本。后来改成用sealed interface替代泛型，问题迎刃而解。这个教训告诉我们：KMP的“共享”不是语法层面的自由，而是平台能力交集的谨慎求解。

2.3 网络请求的生命周期管理：比Retrofit更底层的思考

传统Android开发中，网络请求生命周期绑定Activity/Fragment，靠lifecycleScope或viewLifecycleOwner.lifecycleScope自动取消。但KMP里没有Activity概念，也没有LifecycleOwner。如果沿用“请求随UI销毁”的思路，就会掉进陷阱：iOS的ViewController销毁时，网络请求未必结束；桌面端窗口关闭，后台上传任务可能还在进行。

我们的解决方案是：将网络请求生命周期与业务语义而非UI组件绑定。具体分三级：

1. 会话级（Session）：对应用户登录态，如JWT Token刷新。只要用户未登出，所有请求都应自动携带Token，并在401时触发全局刷新流程。这部分逻辑放在api层，用expect fun refreshToken(): Result<Token>定义，各平台actual实现自己的刷新机制（Android用WorkManager保活，iOS用Background Task API）；
2. 任务级（Task）：对应具体业务操作，如“上传商品图片”。这类请求必须支持手动取消、进度回调、失败重试。我们在transport层定义UploadTask接口，Android实现用OkHttp Call.cancel()，iOS用URLSessionTask.cancel()，桌面端用Thread.interrupt()；
3. 连接级（Connection）：对应底层TCP连接复用。这部分完全由各平台网络库管理，KMP层只提供配置入口（如maxIdleConnections、keepAliveDuration），不干预具体实现。

实操心得：真机调试时遇到error: 上传失败:网络请求错误，90%的情况不是网络本身问题，而是生命周期管理错位。比如Android端在Activity销毁后，仍试图更新ProgressBar的进度——因为UploadTask的回调被持有在ViewModel里，而ViewModel没及时清理监听器。解决方案是在UploadTask接口里强制要求onProgress回调必须接受CoroutineScope参数，由调用方传入lifecycleScope，确保协程随UI自动取消。

3. 核心细节解析：从协议设计到错误处理的硬核实践

3.1 数据协议层（api模块）的设计铁律

:network:api模块是KMP网络层的基石，也是最容易被轻视的部分。很多人以为“DTO就是data class”，结果在真实项目中栽了大跟头。以下是我们在电商App中总结的三条铁律：

铁律一：DTO必须不可变且无副作用
错误示范：

// ❌ 危险！data class含可变属性和业务逻辑 data class Order( var id: String = "", var status: String = "pending", var items: List<Item> = emptyList() ) { fun markAsPaid() { // 业务逻辑混入DTO！ status = "paid" } }

正确做法：

// ✅ DTO纯数据载体，状态变更由Service层处理 @Serializable data class Order( val id: String, val status: OrderStatus, // 枚举类型，非字符串 val items: List<OrderItem> ) @Serializable enum class OrderStatus { PENDING, PAID, SHIPPED, CANCELLED } // 业务逻辑放在独立Service interface OrderService { suspend fun updateStatus(orderId: String, newStatus: OrderStatus): Result<Unit> }

为什么重要？Kotlin/Native对可变对象的序列化支持极差，iOS端若DTO含var属性，JSON反序列化后可能丢失值；而markAsPaid()这种方法，在KMP多平台下根本无法保证各端行为一致（Android用反射，iOS用Objective-C runtime，结果可能不同）。

铁律二：枚举必须显式指定序列化值
错误示范：

// ❌ 依赖默认序号，iOS和Android可能映射错乱 enum class NetworkError { TIMEOUT, SERVER_ERROR, NETWORK_UNAVAILABLE }

正确做法：

// ✅ 显式绑定字符串值，确保跨平台一致 @Serializable enum class NetworkError(val code: String) { TIMEOUT("timeout"), SERVER_ERROR("server_error"), NETWORK_UNAVAILABLE("network_unavailable"); companion object { fun fromCode(code: String): NetworkError? = values().firstOrNull { it.code == code } } }

实测案例：某次灰度发布，Android端返回{"error":"timeout"}，iOS端解析成SERVER_ERROR，因为枚举序号在不同平台编译时发生了偏移。加了code字段后问题消失。

铁律三：集合类型必须明确空安全
错误示范：

// ❌ nullable List在Kotlin/Native中行为异常 data class Product( val name: String, val tags: List<String>? // iOS端可能为null，Android端为emptyList() )

正确做法：

// ✅ 统一用非空集合，默认值明确 data class Product( val name: String, val tags: List<String> = emptyList() )

Kotlin/Native对List<String>?的处理与JVM不同，有时会将JSON中的"tags": null解析为null，有时解析为emptyList()，导致空指针异常。强制非空并设默认值，是最稳妥的方案。

3.2 传输协议层（transport模块）的平台适配要点

:network:transport模块是KMP网络层的“肌肉”，各平台实现差异极大。以下是各平台最关键的适配点：

Android平台（androidMain）

• OkHttp拦截器链的顺序必须严格：我们固定为LoggingInterceptor → AuthInterceptor → RetryInterceptor → CookieInterceptor。特别注意RetryInterceptor不能放在AuthInterceptor之前，否则重试时Token可能已过期；
• Cookie持久化必须用androidx.webkit.WebViewDatabase：KMP commonMain无法访问CookieManager，因此在androidMain中，我们用WebViewDatabase.getInstance(context).getCookieManager()获取CookieManager，再通过CookieSyncManager.createInstance(context)同步；
• Android 12+网络权限适配：<uses-permission android:name="android.permission.INTERNET"/>已不够，必须在AndroidManifest.xml中添加android:usesCleartextTraffic="true"（仅调试用），生产环境强制HTTPS，并在OkHttp中配置CertificatePinner。

iOS平台（iosMain）

• NSURLSessionConfiguration必须用.ephemeral模式：KMP的iosMain无法访问UserDefaults，因此不能用.default配置（会自动保存Cookie到磁盘），改用.ephemeral并在内存中手动管理Cookie；
• 后台上传必须用beginBackgroundTask：iOS对后台任务有严格时限（30秒），我们封装了BackgroundUploadTask类，在beginBackgroundTask内执行上传，并监听UIApplication.willResignActiveNotification确保任务完成；
• TLS证书钉扎（Certificate Pinning）：用Swift的SecTrustEvaluate实现，KMP层只暴露expect fun pinCertificate(certificateData: ByteArray): Boolean接口。

桌面端（jvmMain）

• 代理配置必须支持系统级代理：Compose Desktop默认不读取系统代理，我们在jvmMain中调用java.net.ProxySelector.getDefault()获取系统代理，并注入到HttpClient；
• 大文件上传必须分块：JVM的HttpClient对大文件上传内存占用高，我们实现ChunkedUpload，将文件切分为1MB块，每块单独请求，避免OOM。

注意事项：所有平台的transport模块，禁止在构造函数中初始化网络客户端。必须用object单例+延迟初始化：

// ✅ 正确：延迟初始化，避免类加载时触发平台API object NetworkClient { private var _client: HttpClient? = null val client: HttpClient get() = _client ?: synchronized(this) { _client ?: createClient().also { _client = it } } }

错误做法是val client = createClient()，这会导致Android模块在类加载时就尝试创建OkHttpClient，而此时Application Context可能还未初始化，引发IllegalStateException。

3.3 错误处理与重试机制：超越“try-catch”的工程化设计

KMP网络层的错误处理，绝不是简单地try { request() } catch (e: Exception) { handleError(e) }。我们设计了三级错误分类体系：

第一级：网络层错误（NetworkError）
对应HTTP状态码和底层异常：

• 4xx系列：CLIENT_ERROR（如400 Bad Request、401 Unauthorized）；
• 5xx系列：SERVER_ERROR（如500 Internal Server Error、503 Service Unavailable）；
• 连接异常：TIMEOUT、NETWORK_UNAVAILABLE、SSL_HANDSHAKE_FAILED。

第二级：业务层错误（BusinessError）
由服务端返回的{"code": "ORDER_NOT_FOUND", "message": "订单不存在"}解析而来，定义在api模块：

@Serializable data class BusinessError( val code: String, val message: String, val details: Map<String, Any> = emptyMap() )

第三级：平台层错误（PlatformError）
各平台特有错误，如Android的SecurityException（网络权限被拒）、iOS的NSURLErrorNotConnectedToInternet。

重试机制采用指数退避+熔断器组合：

• 默认重试3次，间隔为1s, 2s, 4s；
• 若连续5次请求失败，触发熔断，10分钟内拒绝所有请求，返回CIRCUIT_BREAKER_OPEN；
• 熔断期间，所有请求转为本地缓存读取（若缓存存在）。

关键实现细节：

• 重试逻辑必须在transport层实现，因为各平台重试策略不同：Android可用OkHttp的Interceptor，iOS需在URLSessionDelegate中判断error.code；
• 熔断状态必须跨进程持久化：Android用SharedPreferences，iOS用UserDefaults，桌面端用java.util.prefs.Preferences。

常见问题：async upload fail error: 代码包大小超过限制。这根本不是网络错误，而是Android打包时，KMP模块的okio依赖版本冲突，导致APK体积暴增。解决方案：在androidMain的build.gradle.kts中强制指定okio版本，并排除传递依赖：

implementation("com.squareup.okhttp3:okhttp:4.12.0") { exclude(group = "com.squareup.okio", module = "okio-jvm") }

4. 实操过程：从零搭建可落地的KMP网络模块

4.1 初始化KMP项目与模块划分

我们以Android Studio Giraffe（2023.2.1）为例，演示完整搭建流程。跳过所有“Hello World”式教程，直奔生产环境必需步骤：

步骤1：创建KMP项目

• File → New Project → Empty Activity → Next；
• 在“Configure project”页面，勾选**“Kotlin Multiplatform Mobile”**（不是“Kotlin Multiplatform”），这是Android Studio专为移动优化的模板；
• 命名项目为ShopApp，包名com.example.shop，点击Finish。

步骤2：创建网络模块

• 右键项目根目录 → New → Module → Kotlin Multiplatform Library；
• 命名模块为network-api，Package name填com.example.shop.network.api；
• 同样方式创建network-transport模块，Package name为com.example.shop.network.transport；

步骤3：配置模块依赖
在app/build.gradle.kts中添加：

dependencies { implementation(project(":network-api")) implementation(project(":network-transport")) // 注意：不要直接implementation("io.ktor:...")，所有依赖由transport模块管理 }

步骤4：删除无用模板代码

• 删除network-api/src/commonMain/kotlin下的Greeting.kt；
• 删除network-transport/src/commonMain/kotlin下的Greeting.kt；
• 在network-api/src/commonMain/kotlin新建model/包，存放DTO；
• 在network-api/src/commonMain/kotlin新建service/包，存放Service接口。

提示：Android Studio的KMP模板会自动生成commonMain、androidMain、iosMain等源集，但不要相信它的默认配置。检查network-transport/build.gradle.kts，确认androidTarget已启用，且iosX64()和iosArm64()都存在——这是iOS真机调试的前提。

4.2 实现一个真实的商品列表请求

以电商App的“获取首页商品列表”为例，展示从DTO定义到Android端调用的全流程：

Step 1：定义DTO（network-api）

// network-api/src/commonMain/kotlin/model/Product.kt @Serializable data class Product( val id: String, val name: String, val price: Double, val imageUrl: String, val tags: List<String> = emptyList() ) @Serializable data class ProductListResponse( val products: List<Product>, val total: Int, val page: Int )

Step 2：定义Service接口（network-api）

// network-api/src/commonMain/kotlin/service/ProductService.kt interface ProductService { suspend fun getHomeProducts(page: Int = 1, pageSize: Int = 20): Result<ProductListResponse> }

Step 3：实现Android端Transport（network-transport/androidMain）

// network-transport/src/androidMain/kotlin/transport/AndroidProductTransport.kt class AndroidProductTransport : ProductService { private val client = NetworkClient.client override suspend fun getHomeProducts(page: Int, pageSize: Int): Result<ProductListResponse> { return try { val response = client.get("https://api.shop.com/products") { parameter("page", page) parameter("size", pageSize) // 自动添加Authorization header header("Authorization", "Bearer ${getToken()}") } val data = response.bodyAsText() Result.success(Json.decodeFromString<ProductListResponse>(data)) } catch (e: Exception) { // 将平台异常转为统一NetworkError val error = when (e) { is IOException -> NetworkError.NETWORK_UNAVAILABLE is TimeoutCancellationException -> NetworkError.TIMEOUT else -> NetworkError.SERVER_ERROR } Result.failure(Exception(error.name)) } } private fun getToken(): String { // 从Android SharedPreferences读取Token return PreferenceManager.getDefaultSharedPreferences(App.instance) .getString("auth_token", "") ?: "" } }

Step 4：在Android App中调用

// app/src/main/java/com/example/shop/MainActivity.kt class MainActivity : AppCompatActivity() { private val productService: ProductService by lazy { AndroidProductTransport() // KMP层实例化 } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) lifecycleScope.launch { val result = productService.getHomeProducts(1) when (result) { is Result.Success -> { // 更新UI updateProductList(result.value.products) } is Result.Failure -> { // 统一错误处理 showError(result.exception.message ?: "未知错误") } } } } }

实操心得：第一次运行时，Android端可能报Unresolved reference: Json，这是因为network-api模块没声明kotlinx-serialization依赖。解决方案：在network-api/build.gradle.kts的commonMain中添加：

implementation("io.ktor:ktor-client-content-negotiation:2.3.10") implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.10")

注意版本必须与network-transport中Ktor版本严格一致，否则编译失败。

4.3 真机调试与常见问题定位

KMP网络层真机调试的痛点，远超纯Android开发。以下是我们在小米13（Android 14）、iPhone 14（iOS 17）、MacBook M1（Compose Desktop）上验证的调试清单：

Android真机调试

• 问题：error: 上传失败:网络请求错误，Logcat显示java.net.UnknownHostException；
• 排查：检查AndroidManifest.xml是否遗漏<uses-permission android:name="android.permission.INTERNET"/>；
• 进阶排查：用adb shell ping api.shop.com确认DNS解析正常，若失败，可能是企业WiFi拦截了HTTPS请求，需在OkHttp中添加hostnameVerifier { true }（仅调试用）。

iOS真机调试

• 问题：Xcode控制台输出[connection] nw_socket_handle_socket_event [C1.1:2] Socket SO_ERROR [61: Connection refused]；
• 排查：检查Info.plist是否添加NSAppTransportSecurity配置，允许HTTP请求（仅调试）；
• 关键点：iOS真机必须用iosArm64()构建，模拟器用iosX64()，两者不能混用。

桌面端调试

• 问题：Compose Desktop启动后，网络请求无响应；
• 排查：检查JVM版本，Compose Desktop 1.5.0要求JDK 17+，若用JDK 11会静默失败；
• 验证方法：在jvmMain中添加println("JVM version: ${System.getProperty("java.version")}")。

独家技巧：为快速定位KMP网络问题，我们在network-transport模块中添加了DebugLogger：

// network-transport/src/commonMain/kotlin/DebugLogger.kt expect object DebugLogger { fun logRequest(url: String, method: String, headers: Map<String, String>) fun logResponse(url: String, statusCode: Int, body: String) }

Android端actual实现用Log.d()，iOS端用print()，桌面端用System.out.println()。开启后，所有请求/响应明文打印，比抓包更直观。

5. 常见问题与排查技巧实录：那些让你熬夜的坑

5.1 “上传失败”类错误的根因分析表

error: 上传失败:网络请求错误是KMP网络层最高频报错，但原因千差万别。我们整理了真实项目中的12种根因及对应解法：

注意事项：所有“上传失败”错误，第一步必须确认文件是否真的被读取。我们在Android端加了校验：

val file = File(filePath) if (!file.exists()) { return Result.failure(Exception("File not found: $filePath")) } if (file.length() == 0L) { return Result.failure(Exception("File is empty: $filePath")) }

这个简单检查，帮我们避开了70%的“文件路径错误”类问题。

5.2 KMP网络层性能瓶颈与优化方案

KMP网络层的性能问题，往往藏在看似无关的细节里。以下是三个真实案例：

案例1：JSON序列化慢

• 现象：Android端列表页加载耗时2.3秒，其中1.8秒花在Json.decodeFromString()；
• 根因：DTO中用了@Serializable修饰的嵌套泛型类，Kotlin/Native序列化器生成效率低；
• 解法：将嵌套结构扁平化，或改用Parcelable（Android端）+Codable（iOS端）双实现，KMP层只传原始JSON字符串。

案例2：OkHttp连接池泄漏

• 现象：App长时间运行后，内存占用持续上涨，MAT分析显示RealConnection对象堆积；
• 根因：OkHttpClient单例未设置connectionPool最大空闲连接数；
• 解法：在androidMain中配置connectionPool.maxIdleConnections(5, 5, TimeUnit.MINUTES)。

案例3：iOS后台上传中断

• 现象：iOS用户切换到后台，上传任务在30秒后被系统终止；
• 根因：未调用beginBackgroundTask申请后台执行时间；
• 解法：在iosMain中封装BackgroundUploadTask，在upload方法开头调用UIApplication.shared.beginBackgroundTask。

5.3 KMP网络层的安全加固 checklist

安全不是附加功能，而是架构设计的一部分。以下是生产环境必须落实的10项安全措施：

1. HTTPS强制：所有transport模块的客户端，必须配置followRedirects = false，并手动处理301/302跳转，防止HTTP中间人攻击；
2. 证书钉扎：Android用CertificatePinner，iOS用SecTrustEvaluate，桌面端用javax.net.ssl.SSLContext；
3. 敏感Header过滤：在LoggingInterceptor中，过滤Authorization、Cookie等Header，避免日志泄露；
4. Token存储：Android用EncryptedSharedPreferences，iOS用Keychain，桌面端用java.util.prefs.Preferences加密；
5. 输入校验：所有DTO字段加@Validate注解（自定义），在decodeFromString后执行校验；
6. 错误脱敏：服务端返回的BusinessError.message，在KMP层统一替换为“请求失败，请稍后重试”；
7. 速率限制：在transport层实现令牌桶算法，防止单个用户暴力刷接口；
8. DNS劫持防护：Android端用Conscrypt替换默认SSLProvider，iOS端用NSURLSession的tlsPolicy；
9. 内存安全：大文件上传时，用InputStream流式读取，避免ByteArray内存溢出；
10. 审计日志：所有网络请求，记录url、method、status、duration，不记录body（隐私合规）。

最后分享一个小技巧：在network-api模块中，我们定义了一个SecurityAudit接口：

interface SecurityAudit { fun auditRequest(url: String, headers: Map<String, String>): Boolean fun auditResponse(statusCode: Int, body: String): Boolean }

各平台actual实现自己的审计逻辑，比如Android端检查headers["User-Agent"]是否包含设备指纹，iOS端验证body是否含敏感词。这让我们在GDPR审计时，能快速出具合规报告。

我在实际项目中发现，KMP网络层最大的价值，不是节省了多少行代码，而是让团队从“救火队员”变成了“架构守护者”。当iOS同事说“这个接口改了，我这边不用动”，当Android同学说“上传失败的问题终于定位到服务端了”，当测试同学不再抱怨“为什么iOS的错误提示和Android不一样”——那一刻，你就知道，分层设计的苦，值了。