07.2.3.1 KMP 工程、expect/actual 与共享层
所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.2 跨平台移动开发 / 07.2.3 Kotlin Multiplatform
版本前提:Kotlin 2.x、Ktor Client 3.x、AGP 8.x;iOS 目标与互操作行为属快速演进内容,版本敏感项标注「待确认」并给出验证点。
本节要解决的问题
本节围绕 KMP 工程组织展开:source set 与 target 矩阵、expect/actual 的规则与限制、共享层依赖选择、线程与协程模型、Swift/Objective-C 互操作、测试与打包集成。面试常考的是「哪些代码能进 commonMain、平台差异如何收敛、跨语言边界有哪些坑」。版本基线为 Kotlin 2.x,具体 target 稳定性以官方文档为准。
07.2.3.1-001 Kotlin Multiplatform 是什么,与单端 Kotlin 工程有何区别?
一句话结论
KMP 让一份 Kotlin 代码同时编译到 JVM、Android、iOS、桌面、Web(Wasm)等多个目标,差异部分由 expect/actual 按平台收敛;单端工程只面向一个运行时,不需要维护跨平台 source set 矩阵。
概念解释
单端 Kotlin 工程(如纯 Android 模块)直接依赖 JVM/Android API,编译产物是 dex 或 JVM 类。KMP 工程把代码拆成 commonMain 与各平台 main:commonMain 只写不绑定具体运行时的逻辑,平台相关部分放在对应源集。KMP 不要求 UI 也跨平台,业务层、数据层、领域模型是最常见的共享部分。
原理流程
- Gradle 插件在
kotlin { }块中声明需要编译的 target。 - 编译器为每个 target 选择对应 source set 与依赖集,独立产出目标二进制。
- commonMain 代码被各 target 复用;平台 main 只覆盖 expect 声明与平台特有逻辑。
代码或图示
// commonMain:不引用任何平台 API
data class User(val id: Long, val name: String)
interface UserRepository {
suspend fun fetch(): List<User>
}
常见误区
- 以为 KMP 等于「一套代码跑所有端、UI 也共享」:默认只共享逻辑层,UI 可原生也可走 Compose Multiplatform。
- 以为 KMP 是把 Kotlin 编译成解释型字节码再跨端:各 target 走各自原生编译链路。
追问
- KMP 与 Kotlin/Native 是什么关系?答:Kotlin/Native 是面向 iOS、桌面、Wasm 等非 JVM 目标的编译器后端,KMP 在工程层组织多个 target,底层复用该后端。
07.2.3.1-002 KMP 共享什么、不共享什么?
一句话结论
可跨运行时复用的领域模型、网络/数据层、业务规则、状态机、序列化与校验逻辑适合共享;直接绑定平台 SDK、线程模型、UI 框架、系统服务的代码通常留在平台侧。
概念解释
判断标准是「这段代码是否只依赖 Kotlin 标准库与多平台库」。纯算法、数据结构、DTO、用例编排、错误模型天然可共享。调用 Android Context、iOS UserDefaults、文件系统、传感器、相机等平台能力的部分,需要通过 expect/actual 或接口注入在平台侧实现。
原理流程
- 先列出模块内所有类型与函数,标注依赖的 API 来源。
- 只依赖 Kotlin stdlib 与多平台库的部分下沉到 commonMain。
- 平台能力抽成 common 接口,平台 main 提供实现,通过 DI 注入。
代码或图示
// commonMain:接口定义在共享层
interface KeyValueStore {
fun put(key: String, value: String)
fun get(key: String): String?
}
常见误区
- 为了「最大化共享」把平台调用硬塞进 commonMain,编译期才发现 API 不可见。
- 反过来把纯业务规则也写在平台侧,导致双端重复实现。
追问
- 共享层里能不能放 UI 状态?答:可以放与框架无关的状态模型与状态机;绑定 Compose/View/SwiftUI 的视图状态与渲染代码留在平台侧。
07.2.3.1-003 commonMain 与各平台 main 的分工是什么?
一句话结论
commonMain 存放跨平台可复用代码与 expect 声明;androidMain、iosMain、jvmMain 等平台源集存放 actual 实现与平台特有代码,平台源集之间默认不可互相引用。
概念解释
source set 是 Gradle 中一组源码与资源的集合。commonMain 是所有 target 的公共父源集;每个平台 target 有自己的 main 源集,例如 androidMain、iosArm64Main、iosX64Main。平台源集只能向上依赖 commonMain 与中间层级源集,不能横向引用另一个平台的实现。
原理流程
- 公共代码与 expect 声明写在 commonMain。
- 平台差异在对应平台 main 中写 actual 实现。
- 编译某 target 时,编译器合并 commonMain 与该 target 源集及其依赖链。
代码或图示
commonMain
├── androidMain
├── iosMain
│ ├── iosArm64Main
│ ├── iosX64Main
│ └── iosSimulatorArm64Main
└── jvmMain
常见误区
- 在 iosMain 里写 Android API,或在 androidMain 里写 iOS API,期望另一平台能复用。
- 把平台实现直接写进 commonMain,靠注释区分平台。
追问
- 平台源集里能不能写 common 侧没有声明的辅助类?答:可以,但该类只对本 target 可见,其他平台无法访问;若需要跨端复用应上移到 commonMain。
07.2.3.1-004 target 是什么,Android、iOS、JVM 各有哪些常见 target?
一句话结论
target 是一次编译的目标运行环境,决定编译器后端、产物格式与可用平台 API;常见有 androidTarget、iosArm64、iosX64、iosSimulatorArm64、jvm、desktop(JVM 桌面)、wasmJs 等。
概念解释
Android target 产出 dex;iOS 的三个架构 target 分别对应真机 arm64、模拟器 x86_64(旧 Mac)、模拟器 arm64(Apple Silicon);jvm target 产出 JVM 字节码;wasmJs 面向浏览器。同一业务模块可以同时挂多个 target,编译器为每个 target 独立编译。
原理流程
- 在
kotlin { }块用androidTarget()、iosArm64()等函数声明 target。 - 插件为每个 target 生成对应的编译任务与源集。
- 打包阶段把各 target 产物组装进 APK、XCFramework 或其他分发物。
代码或图示
kotlin {
androidTarget()
iosArm64()
iosSimulatorArm64()
jvm()
}
常见误区
- 以为只写一个
ios()就能覆盖全部 iOS 架构:实际需要按架构声明对应 target,再由 iosMain 聚合。 - 漏掉模拟器 arm64 target,导致 Apple Silicon 模拟器无法运行。
追问
- iosX64 现在是否还需要?答:仅在 Intel Mac 上跑模拟器时需要;Apple Silicon 环境用 iosSimulatorArm64。是否保留以团队开发机架构为准,属可裁剪项。
07.2.3.1-005 commonTest 与平台测试源集如何组织?
一句话结论
commonTest 存放各 target 都要执行的多平台单元测试;平台特有测试放在 androidTest、iosTest 等平台测试源集,测试框架统一用 kotlin-test。
概念解释
测试源集与源码源集对称:commonTest 依赖 commonMain,编写与平台无关的断言与用例;平台测试源集覆盖需要真实平台 API、UI 或集成环境的用例。kotlin-test 提供跨平台的断言与测试注解,各 target 执行时映射到 JUnit、kotlin-test 框架等对应运行器。
原理流程
- 在 commonTest 写用例,断言使用 kotlin-test 的
assertEquals等。 - 平台专属用例下沉到对应平台测试源集。
- 执行
test任务时,Gradle 为每个 target 跑各自测试集合并汇总结果。
代码或图示
// commonTest
import kotlin.test.Test
import kotlin.test.assertEquals
class CalculatorTest {
@Test
fun addTwoNumbers() {
assertEquals(3, 1 + 2)
}
}
常见误区
- 在 commonTest 里调用平台 API,导致非 JVM target 编译失败。
- 把需要 UI 或数据库实例的集成测试放进 commonTest。
追问
- 共享层的 expect 声明如何在 commonTest 验证?答:commonTest 只能验证公共逻辑;平台实现的正确性在平台测试源集补充,必要时在 common 侧用接口注入测试替身。
07.2.3.1-006 hierarchy template 解决什么问题?
一句话结论
hierarchy template 按平台族自动创建中间层级 source set(如 iosMain 聚合三个 iOS 架构),避免为每个架构重复声明共享代码与依赖。
概念解释
如果不用模板,iosArm64Main、iosX64Main、iosSimulatorArm64Main 各自独立,公共的 iOS 代码要复制三份。模板在 commonMain 与具体架构之间插入 iosMain 这样的中间源集,所有 iOS 架构共享它。模板还会自动配置源集依赖关系。
原理流程
- 插件根据已声明的 target 识别平台族。
- 自动生成 iosMain、macosMain 等中间源集并把架构源集挂到其下。
- 公共 iOS 代码放入 iosMain,三个架构 target 同时复用。
代码或图示
commonMain
└── iosMain
├── iosArm64Main
├── iosX64Main
└── iosSimulatorArm64Main
常见误区
- 手动在三个架构源集里各写一份相同实现,后续改一处漏两处。
- 误以为 iosMain 能被 Android 或 JVM 复用:它只服务 iOS 族 target。
追问
- 模板生成的源集能否自定义?答:可以通过
sourceSets { iosMain { ... } }补充依赖与配置;具体模板规则随 Kotlin 版本演进,自定义前核对当前版本文档(待确认)。
07.2.3.1-007 androidMain 对 commonMain 的可见性规则是什么?
一句话结论
androidMain 可以访问 commonMain 的全部公开声明,反过来 commonMain 看不到 androidMain 的任何类型;平台源集之间横向不可见。
概念解释
源集依赖是单向的:平台 main dependsOn commonMain,因此平台侧能向上看到公共代码,公共侧向下看不到平台实现。可见性还受 Kotlin 访问修饰符约束:internal 只在同一模块内可见,private 只在源集内可见。
原理流程
- 编译 androidTarget 时,编译器按 commonMain → androidMain 顺序合并。
- commonMain 的公开类在 androidMain 可直接引用。
- androidMain 新增的类型仅对 Android target 可见,其他 target 编译时不可见。
代码或图示
// commonMain
expect fun platformName(): String
// androidMain
actual fun platformName(): String = "Android"
常见误区
- 在 commonMain 引用 androidMain 中定义的工具类,编译报 unresolved reference。
- 用
internal暴露给平台侧,却期望其他模块或 target 访问。
追问
- 平台侧需要向 common 侧暴露额外能力怎么办?答:在 commonMain 定义接口或 expect 声明,平台 main 提供实现,而不是反向依赖平台类型。
07.2.3.1-008 iosMain 如何聚合 iosArm64、iosX64、iosSimulatorArm64?
一句话结论
hierarchy 把三个 iOS 架构 target 挂到同一个 iosMain 下,架构级特有代码放各架构源集,iOS 公共代码放 iosMain,产物层面再由 XCFramework 合并多架构。
概念解释
iosMain 是中间源集,不是独立 target;它内部的代码会被三个架构 target 各自编译。真机用 iosArm64,模拟器按 CPU 架构分 iosX64 与 iosSimulatorArm64。如果某个实现只在特定架构不同,才需要下沉到对应架构源集,绝大多数情况下差异只在真机与模拟器之间。
原理流程
- 声明三个 iOS target 后,模板生成 iosMain 聚合关系。
- iOS 公共 actual 实现写在 iosMain。
- 链接阶段把架构产物打成 XCFramework,供 Xcode 按目标架构选择。
代码或图示
kotlin {
iosArm64()
iosX64()
iosSimulatorArm64()
}
常见误区
- 把 iosMain 当成可独立运行的 target,尝试单独打包。
- 为模拟器和真机分别维护两套 iosMain 代码,实际并无必要。
追问
- 不声明 iosX64 会不会影响交付?答:若团队全部使用 Apple Silicon Mac,可省略 iosX64;需要支持 Intel Mac 模拟器时保留。裁剪前确认 CI 与开发机架构(待确认)。
07.2.3.1-009 jvmMain 与 desktopMain 何时使用?
一句话结论
jvmMain 服务于通用 JVM target(后端、桌面库);desktopMain 是 Compose Desktop 等桌面 JVM 场景的平台源集,需要桌面专属代码时使用。
概念解释
同一个 JVM target 既可能跑在后端服务,也可能跑在桌面应用。jvmMain 放纯 JVM 共享代码;desktopMain 面向桌面应用,常与 Compose Multiplatform 桌面目标配合,存放窗口、菜单、文件对话框等桌面特有逻辑。两者的选择取决于模块定位而非 Kotlin 语法差异。
原理流程
- 模块只做 JVM 库时用 jvmMain。
- 引入 Compose Desktop 后,桌面专属能力下沉 desktopMain。
- 编译 jvm/desktop target 时合并对应源集与依赖。
代码或图示
kotlin {
jvm("desktop")
}
sourceSets {
val desktopMain by getting
// 桌面专属依赖与代码挂在 desktopMain
}
常见误区
- 把 Swing/JavaFX 代码放进 jvmMain,导致非桌面 JVM 使用者被迫引入桌面依赖。
- 混淆 jvm 后端模块与桌面模块的依赖边界。
追问
- 桌面与后端能否共用一个 KMP 模块?答:可以共享纯逻辑部分;桌面 UI 与窗口相关代码应拆到 desktopMain 或独立桌面模块,避免后端依赖被桌面库污染。
07.2.3.1-010 source set 之间的 dependsOn 如何声明?
一句话结论
通过 sourceSets { ... } 显式建立源集依赖:平台 main 依赖 commonMain,自定义中间源集用 dependsOn(...) 挂到父源集,依赖方向只能向上。
概念解释
dependsOn 表达源码复用关系:父源集的公开代码对子源集可见,依赖也会传递。模板已经配好默认层级;自定义源集(如按业务分组的中间层)需要手动声明父子关系,否则编译器无法解析跨源集引用。
原理流程
- 在
sourceSets块中获取源集引用。 - 对子源集调用
dependsOn(父源集)。 - 检查依赖方向无环、无横向平台依赖。
代码或图示
sourceSets {
val commonMain by getting
val customMain by creating {
dependsOn(commonMain)
}
val androidMain by getting {
dependsOn(customMain)
}
}
常见误区
- 让两个平台 main 互相 dependsOn,形成循环或跨平台泄漏。
- 自定义源集忘记 dependsOn commonMain,导致 stdlib 之外的公共类型不可见。
追问
- 源集依赖与 Gradle 模块依赖是一回事吗?答:不是。源集依赖是源码复用关系;模块依赖是
api/implementation引入外部库,两者在dependencies块中分别配置。
07.2.3.1-011 资源文件在 commonMain 与平台源集如何放置?
一句话结论
纯文本、JSON、通用图片等可复用资源放 commonMain 的资源目录;平台专属资源放对应平台源集;跨平台 UI 资源在 Compose Multiplatform 中走 composeResources。
概念解释
KMP 共享模块的资源加载比单端复杂:JVM 读 classpath 资源,Kotlin/Native 把资源打进二进制,Web 目标又有自己的加载方式。纯数据资源(配置、文案模板)可以在 commonMain 用平台无关接口访问;直接操作文件路径或系统资源目录的代码留在平台侧。UI 图片、字符串等由 CMP 的资源机制统一管理。
原理流程
- 识别资源是否被所有 target 复用。
- 公共资源放 commonMain 资源目录,平台资源下沉平台源集。
- 通过 common 侧定义的加载接口访问,平台实现负责本端读取。
代码或图示
src/
├── commonMain/
│ └── resources/
├── androidMain/
│ └── res/
└── iosMain/
└── resources/
常见误区
- 在 commonMain 用
File(...)直接读资源路径,iOS/Wasm 目标行为不一致。 - 把平台字体、分辨率切图混进公共资源目录。
追问
- 共享模块里读取打包的 JSON 配置推荐怎么做?答:在 commonMain 定义读取接口,平台 main 分别从 classpath、Native 资源包或 Web 资源加载;UI 字符串与图片优先使用 CMP
composeResources。
07.2.3.1-012 库模块与 app 模块在 KMP 工程中如何划分?
一句话结论
共享逻辑做成纯 KMP 库模块(无 Application 插件),各端 app 模块作为 target 工程消费该库;平台 UI 与启动装配留在各端 app 模块。
概念解释
库模块只暴露 Kotlin 类型与接口,不持有应用入口;Android app 模块、iOS 工程分别依赖该库。这样共享代码可以被多个产品复用,也便于单独跑 commonTest。把初始化、导航、SDK 配置等装配逻辑放在 app 模块,共享层只提供可组合的能力。
原理流程
- 新建 KMP 库模块,声明需要的 target。
- 公共数据层、领域层代码入库。
- Android app 与 iOS 工程作为消费者,在各自入口注入实现并组装依赖图。
代码或图示
shared/ # KMP 库模块
├── commonMain
├── androidMain
└── iosMain
androidApp/ # Android 应用,依赖 shared
iosApp/ # Xcode 工程,链接 shared 产物
常见误区
- 在共享库里直接初始化全局单例或读平台上下文,把库模块变成 app 模块。
- 一个模块同时承担 UI、网络、设备能力,职责边界过宽。
追问
- 共享库能不能暴露 Android 类型给 Android app?答:androidMain 中的类型只对 Android target 可见;Android app 可以直接依赖该库的 Android 产物,但 common 侧接口才是跨端契约。
07.2.3.1-013 单模块多 target 与多模块拆分怎么取舍?
一句话结论
小型试点先用单模块多 target 降低结构成本;随着业务增长,按网络层、数据层、领域层、设备能力拆成多个 KMP 库,避免单模块依赖膨胀与编译变慢。
概念解释
单模块多 target 配置简单,commonMain 内集中管理所有共享代码;缺点是所有 target 一起编译,依赖耦合后裁剪困难。多模块拆分后,纯逻辑模块可以被独立复用,平台依赖隔离在对应模块。模块边界应与业务分层一致,而不是按 target 拆分。
原理流程
- 试点期:一个 shared 模块覆盖网络、模型、业务规则。
- 出现依赖混乱或编译变慢后,识别稳定的下层能力(模型、序列化、网络)。
- 逐层拆分为独立 KMP 库,app 模块按需依赖。
代码或图示
core-model/ # 数据类与枚举
core-network/ # Ktor Client 封装
core-database/ # SQLDelight 封装
feature-account/ # 业务用例层
常见误区
- 按 target 拆模块(android-shared、ios-shared),common 代码无法复用。
- 一开始就拆十几个模块,配置与版本对齐成本压过收益。
追问
- 怎么判断该拆模块了?答:commonMain 中出现按平台分组的大块代码、某层改动触发全量编译、或需要在产品间复用部分能力时,就是拆分信号。
07.2.3.1-014 Kotlin/Native 编译产物有哪些类型?
一句话结论
常见产物包括库(klib)、Objective-C 框架(framework)、可执行程序,以及用于多架构分发的 XCFramework;JVM target 产出字节码,Android 产出 dex。
概念解释
klib 是 Kotlin/Native 的库格式,类似 JVM jar,供其他 Native target 链接。framework 是给 iOS/Objective-C 工程消费的二进制框架,包含头文件与编译产物。XCFramework 把多架构 framework 打包成一个 bundle,解决真机与模拟器架构混放问题。Web 目标产出 Wasm 与 JS 资源。
原理流程
- 编译期:源码 → 对应 target 中间表示 → 目标后端产物。
- 库链接:klib 在 Native 模块间复用。
- 分发:iOS 侧打 framework 或 XCFramework,Xcode 链接后随 App 打包。
代码或图示
klib Kotlin/Native 库,模块间复用
framework 单架构 ObjC 框架,含 .h 与二进制
XCFramework 多架构 framework 集合,支持真机+模拟器
exe Native 可执行程序
常见误区
- 把 klib 直接拖进 Xcode:iOS 工程需要 framework/XCFramework,klib 是编译期库格式。
- 在同一个 framework 目录混放真机与模拟器二进制,触发链接告警。
追问
- framework 里的头文件包含哪些类型?答:导出的 Kotlin 公开类型、函数与属性;internal/private 类型不导出。头文件可读性与命名受导出规则约束,后续题目展开。
07.2.3.1-015 XCFramework 解决什么问题?
一句话结论
XCFramework 把真机 arm64 与模拟器 x86_64/arm64 的 framework 合并为一个 bundle,Xcode 链接时按当前目标架构取对应二进制,避免传统 fat framework 的架构冲突与上架限制。
概念解释
传统 fat framework 把多架构二进制塞进同一个 framework,App Store 对模拟器架构进包有检查限制,且不同架构符号容易冲突。XCFramework 按架构分目录存放,Xcode 与链接器按需选择。KMP 的 CocoaPods/SPM 集成与手动链接都围绕该产物组织。
原理流程
- 各架构 target 分别编译出 framework。
- 打包任务把多架构 framework 合并为
.xcframework。 - Xcode 在编译 App 时按设备/模拟器架构选择对应 slice。
代码或图示
Shared.xcframework/
├── ios-arm64/
│ └── Shared.framework
├── ios-arm64_x86_64-simulator/
│ └── Shared.framework
└── Info.plist
常见误区
- 把模拟器 slice 随 Release 包一起提交审核,触发架构校验问题。
- 更新 KMP 产物后没有清理 DerivedData,链接到旧 framework。
追问
- 手动集成时 XCFramework 需要加入 Xcode 哪里?答:加入「Frameworks, Libraries, and Embedded Content」并按需设置 Embed & Sign;具体选项随 Xcode 版本调整,配置前核对当前 Xcode 文档(待确认)。
07.2.3.1-016 KMP 共享模块如何与既有 Android 模块共存?
一句话结论
Android app 模块通过 implementation(project(":shared")) 依赖 KMP 库,库的 androidMain 直接复用既有 Android 能力,无需把现有 Android 工程改造成全 KMP。
概念解释
KMP 可以渐进接入:存量 Android 模块保留,新业务或抽取出来的公共逻辑进 shared 库。Android target 编译时把 commonMain 与 androidMain 合并,androidMain 仍可使用 Context、Jetpack 等 Android API。既有业务代码不需要一次性迁移。
原理流程
- 新建 shared KMP 模块并配置 androidTarget。
- 把可复用逻辑逐步移入 commonMain,平台调用留在 androidMain。
- Android app 模块依赖 shared,新旧代码在同工程共存。
代码或图示
// app 模块 build.gradle.kts
dependencies {
implementation(project(":shared"))
}
常见误区
- 要求存量 Android 代码全部重写为 KMP 后再接入。
- 在 shared 的 androidMain 里耦合 app 级 Context,导致库无法被其他 Android 应用复用。
追问
- 既有 Android 业务如何抽取进 commonMain?答:先剥离平台依赖,把规则、模型、用例下沉;平台调用通过 common 接口暴露,androidMain 提供实现,按用例逐个迁移。
07.2.3.1-017 编译期 target 与 Gradle 任务命名有什么规则?
一句话结论
每个 target 对应一组编译、测试、打包任务,任务名通常含 target 名称(如 compileKotlinIosArm64、linkDebugFrameworkIosArm64),运行 tasks 可查完整列表。
概念解释
Gradle 为多平台工程按 target 生成任务:编译源码、打 klib/framework、跑测试。JVM/Android 任务名沿用既有约定,Native target 名作为后缀。理解任务命名有助于定位「某个平台编译失败」的任务入口。
原理流程
- 配置阶段插件注册各 target 任务。
- 执行某平台构建时,只触发对应 target 的编译与打包链。
- 汇总任务(如
assemble)串联所有已声明 target 的产物。
代码或图示
compileKotlinAndroid Android 源码编译
compileKotlinJvm JVM 字节码编译
compileKotlinIosArm64 iOS 真机编译
linkDebugFrameworkIosArm64 链接调试 framework
常见误区
- 只跑
build没注意某 Native target 被跳过,以为全部产物已生成。 - 在错误的任务日志里排查,找不到对应平台的报错位置。
追问
- 怎么只构建 iOS 真机产物?答:执行对应 link/assemble 任务(如
linkReleaseFrameworkIosArm64);任务名以当前 Gradle 版本插件生成结果为准,可用./gradlew tasks过滤确认。
07.2.3.1-018 多平台依赖应声明在 commonMain 还是平台 main?
一句话结论
库本身支持多平台时声明在 commonMain;只服务特定平台的依赖下沉到对应平台 main,避免其他 target 引入不可用的库。
概念解释
commonMain 的依赖必须在所有 target 上都有对应实现,否则编译失败。Ktor Client、kotlinx.serialization、SQLDelight 等多平台库放 commonMain;Android 专属库(如某 Jetpack 组件)放 androidMain,iOS 专属库放 iosMain。平台依赖只对本 target 可见。
原理流程
- 查依赖库是否提供多平台构件。
- 多平台依赖写进 commonMain 的
dependencies。 - 平台专属依赖写进对应源集的
dependencies。
代码或图示
sourceSets {
val commonMain by getting {
dependencies {
implementation("io.ktor:ktor-client-core:3.0.0")
}
}
val androidMain by getting {
dependencies {
implementation("io.ktor:ktor-client-okhttp:3.0.0")
}
}
}
常见误区
- 把 JVM 专属库加进 commonMain,iOS 编译期解析不到构件。
- 平台库也声明在 commonMain,导致其他平台被迫引入无用依赖。
追问
- 版本号统一在哪里管理?答:多平台库版本在版本目录统一声明,平台引擎依赖同版本;具体坐标与版本对齐以各库官方发布说明为准(待确认)。
07.2.3.1-019 版本目录在 KMP 模块中有哪些写法要点?
一句话结论
版本目录统一管理库坐标与版本,多平台库只写一次主坐标,平台引擎作为单独条目;插件版本与 Kotlin 版本对齐,避免依赖解析冲突。
概念解释
libs.versions.toml 按 [versions]、[libraries]、[plugins] 分组。KMP 场景下,core 构件与平台引擎是不同坐标,需要分别声明。Kotlin 编译器插件版本与 Kotlin Gradle 插件版本必须一致,跨平台库版本之间也有兼容矩阵。
原理流程
- 在
[versions]固化 Kotlin、AGP、CMP、各库版本。 [libraries]拆分 core 与平台引擎条目。- 模块
dependencies用libs.*引用,避免各处硬编码版本。
代码或图示
[versions]
ktor = "3.0.0"
[libraries]
ktor-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
常见误区
- core 与平台引擎版本不一致,运行期出现 NoSuchMethodError 类问题。
- 在版本目录混入本机路径或私有仓库地址,团队环境无法复现。
追问
- 怎么查跨平台库的兼容版本?答:以各库官方 README 与发布说明为准,重点核对 Kotlin 版本与 target 支持范围;不确定的组合在试点工程先做依赖解析验证(待确认)。
07.2.3.1-020 典型 source set 配置错误如何定位?
一句话结论
按「编译报错源集 → 依赖方向 → 平台 API 可见性 → 构件是否存在」顺序排查:unresolved reference 多为源集依赖或平台 API 放错层级,解析失败多为库不支持该 target。
概念解释
KMP 编译报错信息会标明 target 与源集。常见错误:commonMain 引用了平台类型、平台源集横向引用、多平台库漏配平台引擎、target 名拼写错误。先看报错来自哪个 target,再回查源码放在哪个源集,比全局搜索效率高。
原理流程
- 从报错任务名确认失败 target。
- 打开报错文件,判断其所在源集与引用类型的来源。
- 平台 API 下沉平台 main;缺构件则补平台引擎依赖或更换库。
代码或图示
unresolved reference: Context → androidMain 误用或 commonMain 引用 Android API
Could not find io.ktor:...iosX64 → 漏配 iOS 引擎或库不支持该架构
e: Source set ... dependsOn cycle → 源集依赖成环
常见误区
- 看到报错就在 commonMain 加平台依赖,越改越乱。
- 忽略报错中的 target 后缀,在错误的平台上下文排查。
追问
- 同一代码在 JVM 编译通过、iOS 失败说明什么?答:通常该代码依赖了 JVM/Android 可见的 API 或类库,需要下沉平台实现或抽取公共接口。
07.2.3.1-021 expect/actual 机制的核心思想是什么?
一句话结论
expect 在 commonMain 声明「需要一个平台实现」的契约,actual 在各平台 main 提供匹配实现;编译器保证每个 target 都有对应 actual,否则报错。
概念解释
expect/actual 是 KMP 收敛平台差异的主要手段:公共代码面向 expect 声明编程,不关心实现来自哪个平台。它不同于继承或接口注入:expect 声明本身不能在 common 侧提供默认实现,actual 由编译器按签名匹配到对应平台。
原理流程
- commonMain 写 expect 函数/类/属性声明。
- 各平台 main 写 actual 实现。
- 编译某 target 时,编译器为 expect 找到本平台 actual 并替换调用点。
代码或图示
// commonMain
expect fun currentPlatform(): String
// androidMain
actual fun currentPlatform(): String = "Android"
// iosMain
actual fun currentPlatform(): String = "iOS"
常见误区
- 把 expect/actual 当成普通多态:actual 不需要在 common 侧注册,编译器按签名静态匹配。
- 以为 expect 可以写默认实现再被 actual 覆盖:expect 声明无实现体。
追问
- expect/actual 与接口注入怎么选?答:纯平台能力映射用 expect/actual;需要可替换实现、测试替身或多套策略时,common 接口加平台注入更灵活。
07.2.3.1-022 expect 函数声明的语法要点是什么?
一句话结论
expect 函数以 expect fun 开头,只写签名与类型参数,不带函数体;可以声明参数默认值、返回类型与泛型,平台 actual 必须签名匹配。
概念解释
expect 函数本质是平台契约声明:参数名、类型、返回类型、泛型约束都参与匹配。默认值在 common 侧声明,actual 不需要重复;expect 不能有 { } 实现块,也不能写表达式体。
原理流程
- 在 commonMain 用
expect fun写签名。 - 标注可空性、泛型与返回类型。
- 各平台提供
actual fun,参数类型与返回类型一致。
代码或图示
// commonMain
expect fun <T> encode(value: T, charset: String = "UTF-8"): String
// androidMain
actual fun <T> encode(value: T, charset: String): String =
json.encodeToString(value)
常见误区
- expect 函数写了
= ...表达式体或函数体,编译器直接报错。 - actual 改了参数类型顺序或返回类型,匹配失败。
追问
- expect 函数可以声明 suspend 吗?答:可以,suspend 是签名的一部分,actual 同样必须是 suspend;导出到 Swift 后挂起函数以 completion handler 形式暴露。
07.2.3.1-023 actual 函数签名必须满足哪些匹配规则?
一句话结论
actual 的函数名、参数类型与顺序、返回类型、泛型参数与约束必须与 expect 一致;参数名可以不同,默认值由 common 侧保留,可见性不能放宽。
概念解释
编译器按签名做静态匹配:类型不匹配、泛型不一致、返回类型可空性不同都会导致 actual 无法绑定。参数名只影响调用处可读性,不参与匹配;actual 不能把 internal 改成 public 或改变类型参数边界。
原理流程
- 比对 expect 与 actual 的函数签名各组成部分。
- 类型、泛型、返回可空性逐项对齐。
- 匹配通过后,编译期把调用解析到本平台实现。
代码或图示
// commonMain
expect fun format(value: Double, locale: String?): String
// iosMain:返回类型与参数类型必须一致
actual fun format(value: Double, locale: String?): String =
locale?.let { value.toString() } ?: value.toString()
常见误区
- actual 把
String?写成String,可空性不匹配。 - 给 actual 增加 expect 没有的参数,导致无法绑定。
追问
- actual 能否包装一层再委托?答:可以在 actual 内部调用平台 API 或委托给其他类型,但对外签名必须保持一致;实现细节不影响匹配。
07.2.3.1-024 expect 声明为什么不能有实现体?
一句话结论
expect 表达的是「契约在各平台分别提供」,common 侧写死实现就失去跨平台意义;需要公共默认逻辑时,应抽到普通公共函数由 actual 调用。
概念解释
expect 声明的生命周期属于公共契约:如果 common 侧允许实现,平台差异就无法收敛,编译器也无法判断该代码是否绑定平台 API。需要跨平台复用的默认行为,放在普通公共函数里,各 actual 按需调用。
原理流程
- expect 只保留签名。
- 公共默认逻辑写成 commonMain 普通函数。
- actual 实现可以直接调用该公共函数,再补平台特有部分。
代码或图示
// commonMain
expect fun deviceName(): String
fun greeting(): String = "Hello, ${deviceName()}"
常见误区
- 在 expect 函数里写
= "default",期望平台覆盖。 - 为避免重复,把平台实现逻辑塞进 common 普通函数再反向调用平台 API。
追问
- 多个平台实现有 80% 相同逻辑怎么办?答:把相同部分抽成 commonMain 普通辅助函数,各 actual 调用它,只保留 20% 平台差异在平台 main。
07.2.3.1-025 expect class 的定位与限制是什么?
一句话结论
expect class 声明一个跨平台类型契约,平台提供 actual class;它不能在 common 侧声明需要平台实现的成员细节,能力边界比普通类窄。
概念解释
expect class 用于平台类型需要分别实现的场景,例如封装一个本端时钟、存储或设备能力。common 侧只能看到类型本身与声明的公共签名;构造、属性初始化、方法实现都在平台侧。expect class 的成员声明规则比 expect 函数严格,部分成员形态不允许在 common 侧声明。
原理流程
- commonMain 用
expect class写类型与必要成员签名。 - 平台 main 提供
actual class。 - 编译器保证每个 target 有匹配的 actual class 后再编译调用点。
代码或图示
// commonMain
expect class SessionStore() {
fun save(token: String)
fun read(): String?
}
常见误区
- 把 expect class 当成完整类模板,在 common 侧写初始化逻辑与成员实现。
- 误以为 expect class 可以继承任意平台父类并在 common 侧引用。
追问
- expect class 在 Kotlin 2.x 的状态如何?答:expect class 语法保留使用,但部分成员声明能力受限;推荐接口方案替代。具体可声明的成员形态以当前版本官方文档为准(待确认)。
07.2.3.1-026 expect class 不能在 common 侧声明哪些成员细节?
一句话结论
需要平台类型决定形态的成员(如基于平台父类的继承、成员初始化、委托、属性 backing 细节)不能在 common 侧写;common 侧只能声明跨平台一致的成员签名。
概念解释
平台 actual class 可能继承不同父类、用不同方式初始化属性,这些选择在 common 侧无法表达。因此 expect class 对成员的约束比普通类严格:可空类型、平台类型映射、构造参数等都受限制。遇到表达不了的成员,应改用接口加平台实现。
原理流程
- 列出类需要暴露给 common 的方法与属性。
- 跨平台签名部分写进 expect class。
- 依赖平台父类或初始化形态的部分移到平台实现,common 通过接口调用。
代码或图示
// 不推荐:common 侧强行描述成员细节
expect class PlatformLogger() {
// 平台父类/初始化方式差异无法在此表达
}
// 推荐:common 定义接口
interface Logger { fun log(message: String) }
常见误区
- 在 expect class 中声明带平台类型的属性,编译期类型映射失败。
- 用 expect class 强行包装平台父类层级,common 侧无法多态引用。
追问
- 怎么判断成员该不该进 expect class?答:成员参数与返回值都能用 Kotlin 跨平台类型表达、且不依赖平台父类时可以声明;否则下沉到平台实现并通过接口暴露。
07.2.3.1-027 actual class 与 expect class 的匹配约束有哪些?
一句话结论
actual class 的类名、构造参数、可见性、声明的成员签名必须与 expect class 匹配;平台父类、接口实现可以在 actual 侧补充,但不能改变 common 契约。
概念解释
actual class 是 expect class 在本平台的落地类型:构造函数参数列表、公共成员签名参与匹配。actual 可以选择继承平台父类、实现额外接口,这些平台细节对 common 调用方不可见。若 actual 成员签名与 expect 不一致,编译器报绑定错误。
原理流程
- 平台 main 写
actual class。 - 对齐构造参数与成员签名。
- 平台父类、平台接口在 actual 侧补充,不写入 common 契约。
代码或图示
// iosMain
actual class SessionStore actual constructor() {
actual fun save(token: String) { /* iOS 实现 */ }
actual fun read(): String? = null
}
常见误区
- actual 类改了构造参数数量或类型,匹配失败。
- 在 actual 侧新增 public 方法并期望 common 侧调用,common 看不到该方法。
追问
- actual class 可以是 data class 吗?答:可以按版本支持情况选择,但数据类的成员与导出行为受平台约束;需要跨平台一致的值语义时,优先在 commonMain 定义 data class,平台只做包装。
07.2.3.1-028 expect interface 与 expect class 如何选择?
一句话结论
优先用普通 interface 定义跨平台契约;expect interface 主要用于类型本身需要平台化的场景,expect class 用于需要平台构造与封装的类型,多数业务场景接口方案更灵活。
概念解释
普通 interface 完全定义在 commonMain,平台实现是普通类,通过 DI 注入,可替换、可 mock。expect 体系把类型本身做成平台契约,编译期静态绑定,替换空间小。新代码通常先用 interface,只有当类型构造、封装或平台父类必须平台化时才考虑 expect class。
原理流程
- 定义 common interface 与方法签名。
- 平台 main 写实现类,不使用 actual 绑定。
- 装配阶段把实现注入 common 层使用。
代码或图示
// commonMain
interface SessionStore {
fun save(token: String)
fun read(): String?
}
// iosMain
class IosSessionStore : SessionStore { /* ... */ }
常见误区
- 凡是平台能力就先上 expect class,导致 common 侧多态与测试替身难以落地。
- 把接口方法写成 expect 函数散落各处,契约不内聚。
追问
- 接口方案在 iOS 侧多了一个包装类,值得吗?答:换来可测试性、可替换性与更宽松的成员表达;只有类型必须直接暴露给 Swift 且封装不可替代时,expect class 的收益才更明显。
07.2.3.1-029 用接口加平台实现替代 expect class 怎么写?
一句话结论
commonMain 定义接口,平台 main 写实现类,共享层通过构造参数或 DI 接收实例;common 代码面向接口编程,不感知具体平台类型。
概念解释
这是 KMP 工程中最常用的平台差异收敛方式:接口在公共层固定契约,实现按平台提供。相比 expect class,接口方案允许同一平台有多套实现、测试时注入 mock,成员表达不受 expect class 限制。
原理流程
- commonMain 声明接口与数据模型。
- androidMain/iosMain 分别写实现类。
- app 入口装配实现并传入共享层,common 侧只依赖接口。
代码或图示
// commonMain
interface AuthGate {
suspend fun login(name: String, password: String): Result<Token>
}
// 共享层接收接口
class LoginViewModel(private val gate: AuthGate) {
suspend fun submit() = gate.login("u", "p")
}
常见误区
- 平台实现类在 common 侧被直接引用,退回平台耦合。
- 接口返回平台类型(如 Android Intent、iOS NSDictionary),跨端不可用。
追问
- 实现实例在哪里创建?答:在各端 app 入口(Application / App 启动期)创建,经 DI 传入共享层;共享库不自行构造平台实现。
07.2.3.1-030 expect object、expect enum、expect annotation 的支持情况如何?
一句话结论
Kotlin 支持按版本对 expect object、expect enum class、expect annotation class 做不同程度的约束;enum 与注解的平台化需求多数可改用普通 sealed/enum 或接口表达,具体支持形态以当前版本文档为准(待确认)。
概念解释
expect 不仅限于 class 与函数:对象、枚举、注解也有对应声明形式,但成员与构造约束比普通类型严格。业务中常见做法是把跨平台枚举直接定义在 commonMain,平台需要原生枚举映射时再做转换层。注解用于代码生成或平台元数据,不应承载业务逻辑。
原理流程
- 先判断该类型是否真的需要平台化。
- 可在 commonMain 定义的枚举/对象直接下沉公共层。
- 必须平台化的部分核对当前版本 expect 支持范围后再写 actual。
代码或图示
// 优先:跨平台枚举直接放 commonMain
enum class Platform { ANDROID, IOS, JVM, WEB }
常见误区
- 为了对齐原生枚举而把普通枚举做成 expect,增加维护成本。
- 在 expect 注解里写平台处理逻辑,注解只保留元数据。
追问
- 平台原生枚举需要与共享枚举互转怎么办?答:在平台 main 写映射函数,把共享枚举值转换为平台枚举;common 层只持有共享枚举。
07.2.3.1-031 expect 顶层属性与 actual 顶层属性有哪些规则?
一句话结论
顶层属性可用 expect val/var 声明契约,actual 顶层属性必须类型与可空性匹配;公共只读属性适合用 expect,可变属性的线程安全由平台实现负责。
概念解释
顶层 expect 属性用于暴露平台常量或环境信息(如平台名、系统版本)。actual 属性不能改变类型与可空性;expect var 同样需要 actual var。共享层若用可变顶层状态,跨线程安全需要自行保证,尤其在 Kotlin/Native 侧。
原理流程
- commonMain 用
expect val声明只读平台属性。 - 平台 main 提供
actual val,类型一致。 - 调用方通过公共属性读取,不感知实现来源。
代码或图示
// commonMain
expect val platformLabel: String
// iosMain
actual val platformLabel: String = "iOS"
常见误区
- expect 属性声明
var却在 actual 用val。 - 用顶层可变属性存放会话状态,跨端并发下出现竞态。
追问
- 顶层属性会延迟初始化吗?答:
val常量在编译期/加载期初始化;需要平台延迟初始化逻辑时,封装到类实例中管理生命周期,不要依赖顶层属性的初始化时机。
07.2.3.1-032 expect 构造函数参数与默认值怎么处理?
一句话结论
expect class 的构造参数列表参与匹配,默认值在 common 侧声明;actual 构造函数参数类型与数量必须对齐,平台可补充自身初始化逻辑。
概念解释
构造参数是类型契约的一部分:参数名参与可读性,类型与顺序参与匹配。默认值由 common 侧固定,actual 不重复标注。平台父类构造、属性注入等细节写在 actual 类体内,common 调用方只按公共构造参数创建类型。
原理流程
- commonMain 写
expect class与构造参数列表。 - actual 类用
actual constructor对齐参数。 - 平台初始化逻辑在 actual 类体内完成。
代码或图示
// commonMain
expect class HttpClient(baseUrl: String) {
fun get(path: String): String
}
// androidMain
actual class HttpClient actual constructor(val baseUrl: String) {
actual fun get(path: String) = /* OkHttp 实现 */ ""
}
常见误区
- actual 构造函数增加 expect 没有的参数,外部无法构造。
- 在 expect 构造参数里使用平台专属类型。
追问
- 构造需要异步初始化(如读取配置)怎么办?答:构造只做轻量赋值,异步加载由方法或生命周期回调完成;把重初始化移出构造函数,避免平台阻塞。
07.2.3.1-033 平台类型映射(Kotlin String 与 NSString)如何发生?
一句话结论
导出到 Objective-C/Swift 时,Kotlin 类型按平台规则映射:String 桥接到 NSString/Swift String,集合与可空性也有对应映射;平台类型在 common 侧仍以 Kotlin 类型书写。
概念解释
Kotlin/Native 互操作层在生成框架时做类型桥接:常见值类型有确定的映射规则,集合映射到 Foundation 类型,可空性标注进头文件。反过来,把 Swift/ObjC 对象传给 Kotlin 时也经同样映射。commonMain 代码不直接引用平台类型,映射只发生在导出边界。
原理流程
- commonMain 使用 Kotlin 标准类型。
- 导出框架时互操作层生成头文件类型映射。
- Swift/ObjC 侧按映射类型调用,边界转换由编译器与运行时桥接完成。
代码或图示
Kotlin String → NSString / Swift String
Kotlin List<T> → NSArray<T>(具体泛型形态受导出限制)
Kotlin Boolean? → Swift 可选 Bool
常见误区
- 在 commonMain 直接写
NSString,JVM/Android target 不可见。 - 以为所有 Kotlin 泛型集合都能无损导出为 Swift 强类型集合。
追问
- 导出的集合泛型受限怎么办?答:在 common 侧用具体数据类包装结果,避免直接暴露嵌套泛型集合;导出可读性与类型安全后续题目展开。
07.2.3.1-034 expect/actual 与 C/C++ 条件编译有何区别?
一句话结论
expect/actual 是类型安全的静态平台契约:编译器校验签名匹配并按 target 选择实现;条件编译是预处理文本裁剪,不做类型校验,两者定位不同。
概念解释
C/C++ 的 #ifdef 在编译前裁剪文本,类型检查发生在裁剪之后,容易出现平台分支签名不一致。expect/actual 在 Kotlin 类型系统内表达差异:签名参与编译期校验,未提供 actual 的 target 直接报错,公共代码不感知平台分支。
原理流程
- common 代码面向 expect 声明编译。
- 每个 target 独立解析对应 actual。
- 签名不匹配或缺 actual 在编译期暴露,而非运行期。
代码或图示
#ifdef ANDROID
...
#else
...
#endif
常见误区
- 把 expect/actual 当成运行期 if/else 分支:它是编译期静态绑定。
- 用条件编译思路在 commonMain 写平台判断字符串分支。
追问
- 运行期需要区分平台怎么办?答:通过 expect 属性或接口暴露平台标识,公共逻辑按注入值分支;编译期差异收敛仍由 expect/actual 负责。
07.2.3.1-035 同一个 expect 在多个 iOS target 上如何复用 actual?
一句话结论
iOS 公共 actual 实现写在 iosMain,三个 iOS 架构 target 自动复用;只有真机与模拟器存在实现差异时,才下沉到对应架构源集。
概念解释
iosMain 作为中间源集被所有 iOS 架构 target 共享,actual 写在这里即可同时服务真机与模拟器。架构间真正不同的情况很少(如调试符号、链接配置),业务 API 实现通常一致。Android、JVM 等其他平台在各自源集提供 actual。
原理流程
- 判断实现是否对所有 iOS 架构一致。
- 一致时写 iosMain,由模板聚合到各架构。
- 不一致时按架构源集分别写 actual。
代码或图示
// iosMain:三个 iOS 架构复用
actual fun platformLabel(): String = "iOS"
常见误区
- 在 iosArm64Main 与 iosSimulatorArm64Main 复制相同实现。
- 把仅真机可用的实现放进 iosMain,模拟器链接异常。
追问
- 三个 iOS target 都需要单独验证吗?答:业务实现一致性验证一次即可;打包与链接需分别覆盖真机、Apple Silicon 模拟器,Intel 模拟器按开发机情况纳入矩阵。
07.2.3.1-036 expect 声明带泛型时 actual 有哪些约束?
一句话结论
泛型参数数量、名称、上界约束必须与 expect 一致;actual 不能替换类型实参或放宽上界,调用处的类型推导由公共签名固定。
概念解释
泛型是签名契约的一部分:expect fun <T : Any> listOf(): List<T> 与 actual 中同名类型参数的上界必须对齐。actual 不能把 T : Any 改成无约束,也不能把返回类型写死成具体类。泛型协变/逆变标注同样需要一致。
原理流程
- 在 expect 签名中写清类型参数与上界。
- actual 复制泛型形参列表,保持约束。
- 编译器校验后,调用点按 common 侧泛型推导解析。
代码或图示
// commonMain
expect fun <T : Any> single(item: T): T
// androidMain
actual fun <T : Any> single(item: T): T = item
常见误区
- actual 把泛型返回写成具体类型,破坏契约。
- 给类型参数加 expect 没有的上界,匹配失败。
追问
- 泛型在 Swift 导出会受影响吗?答:会。嵌套泛型与复杂参数在 Objective-C 头文件中可能被擦除或包装,跨语言导出限制在互操作题目展开。
07.2.3.1-037 expect 函数返回平台类型时会带来什么问题?
一句话结论
expect 契约应只使用跨平台类型;若返回平台类型(如 ByteArray 尚可,平台对象不可),common 侧无法编写统一逻辑,且导出到其他语言时类型映射断裂。
概念解释
跨平台签名的可交换性取决于类型是否在所有 target 都有对应物。Kotlin 标准库的基本类型与标准集合多数可交换;平台专属对象(Android Bitmap、iOS UIImage)不能进入 common 契约。需要返回平台对象时,应在 common 定义抽象描述(如图片 ID、尺寸、占位模型),平台侧再转原生类型。
原理流程
- 审查 expect 签名的参数与返回类型。
- 平台类型替换为 common 数据模型或标识。
- 平台 main 完成 common 模型到原生类型的转换。
代码或图示
// commonMain:不返回 UIImage/Bitmap
data class ImageRef(val url: String, val width: Int, val height: Int)
常见误区
- 在 common 接口里暴露平台对象,编译期只在当前 target 通过,其他 target 报错。
- 为绕过限制把返回类型写成
Any,丢失类型安全。
追问
- 平台对象必须跨层传递怎么办?答:在 common 侧用不透明句柄(ID 或包装接口),平台层持有原生对象映射;不要把原生对象塞进共享层。
07.2.3.1-038 actual 声明缺失时编译器报什么错,如何处理?
一句话结论
某 target 缺少 actual 时,编译器在该 target 上报「actual declaration is missing」类错误;处理方式是在对应平台 main 补全 actual,或移除该 target 的 expect 依赖。
概念解释
expect 契约要求每个已声明 target 都有匹配 actual。报错会指明 target 与缺失声明。常见原因:新加了 target 没补平台实现、actual 签名不匹配被识别为未绑定、平台源集拼写错误。先按报错 target 定位源集,再核对签名。
原理流程
- 读报错中的 target 与 expect 声明位置。
- 检查对应平台 main 是否存在 actual、签名是否匹配。
- 补全实现或调整 target 列表后重新编译。
代码或图示
e: missing actual declaration for expect ...
target: iosArm64
常见误区
- 在另一个平台源集补 actual,报错 target 仍缺失。
- 签名微调后编译器识别为两个不匹配声明,误判为缺失。
追问
- 平台暂时不需要该能力能否跳过报错?答:不能在 common 侧跳过;可在该平台提供最小实现(如返回空结果或抛平台异常),或评估是否真的需要为该 target 编译。
07.2.3.1-039 expect/actual 在 commonTest 中的测试策略是什么?
一句话结论
commonTest 只验证面向 expect 契约编写的公共逻辑,平台实现的正确性放到平台测试源集;需要替身时在 common 侧用接口注入测试实现。
概念解释
expect 声明在 commonTest 编译时同样需要各 target 提供 actual,测试执行路径依赖平台实现。纯规则、模型、序列化用例可以在 commonTest 覆盖;涉及平台返回值、线程、UI 的用例无法在公共测试中断言,应下沉平台测试。
原理流程
- 把可脱离平台的逻辑写成纯函数或接口驱动。
- commonTest 注入测试替身验证编排与规则。
- 平台行为在 androidTest/iosTest 等源集补充断言。
代码或图示
// commonTest:注入假实现
class FakeStore : KeyValueStore {
private val map = mutableMapOf<String, String>()
override fun put(key: String, value: String) { map[key] = value }
override fun get(key: String) = map[key]
}
常见误区
- 在 commonTest 断言平台返回的具体原生对象。
- 把平台实现缺陷误判为公共逻辑问题,在 common 层反复修。
追问
- 公共用例如何在没有平台替身时跑通?答:为测试提供 common 侧假实现,通过构造注入;expect 直接绑定的平台能力难以替换,这也是接口方案更易测试的原因之一。
07.2.3.1-040 expect class 的成员函数能否在 common 侧调用?
一句话结论
只有在 expect class 中显式声明的成员签名才能在 common 侧调用;actual 类新增的成员对 common 不可见,未声明的属性与方法同样不可访问。
概念解释
common 侧持有的类型是 expect class 的契约视图,不是 actual 类的完整类型。编译器按 expect 声明解析成员;actual 侧为满足平台父类或内部实现新增的 public 方法,common 调用点看不到。需要暴露给 common 的能力必须补进 expect 契约。
原理流程
- 列出 common 调用方需要的方法与属性。
- 逐项写入 expect class 声明。
- actual 类实现对应成员,平台内部辅助方法不进契约。
代码或图示
// commonMain
expect class Counter() {
fun increment()
fun value(): Int
}
// 调用处只能用 increment() 与 value()
常见误区
- 在 actual 类加了 public 方法后直接在 common 调用,编译报 unresolved reference。
- 把平台内部状态通过 expect 属性暴露,污染公共契约。
追问
- 平台内部方法确实需要被 common 调用怎么办?答:在 expect class 补声明该方法,或改用接口方案把公共方法集中到 common 接口。
07.2.3.1-041 expect 与 lateinit、委托有哪些限制?
一句话结论
expect 声明不能依赖 common 侧无法表达的初始化形态;lateinit、属性委托、构造委托等需要平台初始化细节的写法应放在 actual 实现内部,common 契约只保留签名。
概念解释
expect class 的属性初始化方式由平台决定:延迟初始化、委托代理、父类注入都属于平台实现细节。common 侧声明的属性只描述类型与可空性,初始化责任在 actual。把 lateinit、by lazy、委托写进 expect 成员会受编译器约束。
原理流程
- common 契约只声明属性类型与读写可见性。
- 初始化策略(惰性、委托、延迟注入)写在 actual 类体内。
- common 代码通过契约属性访问,不关心初始化时机。
代码或图示
// actual 内部:平台选择初始化方式
actual class Logger {
private val delegate = PlatformDelegate()
actual fun log(message: String) = delegate.emit(message)
}
常见误区
- 在 expect class 中声明委托属性并期待 common 侧指定委托逻辑。
- 用顶层 lateinit 存放跨平台单例,平台初始化时序不可控。
追问
- 共享层需要延迟初始化的公共对象怎么组织?答:用普通类包装,在平台装配期注入实例;状态与生命周期由显式持有方管理,不依赖 expect 类型的内部初始化。
07.2.3.1-042 平台特定 API 走 expect/actual 还是接口注入?
一句话结论
能力形态固定、只做平台映射时用 expect/actual;需要多套实现、测试替身或策略切换时用 common 接口加平台注入;工程中常两者混用。
概念解释
expect/actual 适合「同一契约、各平台一份实现」的稳定映射,例如平台名、设备信息、原生存储包装。接口注入适合业务策略层:认证网关、推送通道、日志埋点等可能替换或 mock 的能力。判断依据是变化频率与可测试性要求。
原理流程
- 区分:纯平台映射 vs 可替换业务能力。
- 映射类收敛到 expect/actual。
- 策略类定义 common 接口,平台实现经 DI 注入。
代码或图示
// 映射类:expect/actual
expect fun deviceModel(): String
// 策略类:接口注入
interface Analytics { fun track(event: String) }
常见误区
- 所有平台能力都用 expect class,导致业务层难以测试与替换。
- 纯映射也写接口与注入类,装配代码变重。
追问
- 一个模块里两种方式并存会不会混乱?答:按职责分层即可:底层平台映射用 expect/actual,上层业务网关用接口;命名与模块边界保持清晰。
07.2.3.1-043 expect/actual 与依赖注入如何结合?
一句话结论
expect/actual 解决平台类型绑定,DI 解决实例装配与生命周期;共享层面向接口接收注入实例,平台实现可在装配期选择 expect 绑定类或普通实现类。
概念解释
DI 容器在各端入口组装:common 层声明依赖接口,平台 main 提供实现并注册。expect/actual 类型可以被 DI 持有,普通接口实现同样可以。共享库不负责创建平台对象,只消费注入进来的实例;这样平台实现可替换、可测试。
原理流程
- common 层定义接口与依赖声明。
- 平台入口创建实现(expect actual 类或普通类)并注册到容器。
- 共享层从容器取接口实例使用。
代码或图示
// commonMain
class SessionViewModel(private val store: KeyValueStore)
// 平台入口:注册实现
// val module = module { single<KeyValueStore> { IosStore() } }
常见误区
- 共享库内部
object单例自行 new 平台实现,绕过 DI。 - 把 expect 类型直接作为注入绑定类型,限制了后续替换空间。
追问
- KMP 常用哪些 DI 库?答:Koin 提供多平台模块,也可在 common 手写轻量工厂;具体库版本与 target 支持以官方发布说明为准(待确认)。
07.2.3.1-044 expect 声明跨模块时有什么可见性规则?
一句话结论
跨模块复用 expect 契约时,公共类型与声明必须是 public;internal 不跨模块可见,actual 绑定只在本模块内完成,下游模块消费的是导出类型而非 expect/actual 绑定关系。
概念解释
Gradle 模块边界上,下游依赖上游编译产物。上游的 expect 与 actual 在上游模块内绑定完成,下游拿到的是可用类型。跨模块暴露的接口、数据类、函数需要 public 可见性;expect 声明本身不作为跨模块 API 直接暴露给下游重新绑定。
原理流程
- 上游模块把公共契约标为 public。
- 上游各 target 内完成 expect/actual 绑定与编译。
- 下游模块依赖上游产物,按导出接口调用。
代码或图示
// 上游 commonMain
interface PublicGateway { suspend fun ping(): String }
// internal 类型不应对下游暴露
internal interface InternalHelper
常见误区
- 把 expect 契约做成 internal,下游模块无法引用。
- 期望下游模块为上游 expect 提供自己的 actual:绑定在上游编译期完成。
追问
- 下游需要差异化实现同一能力怎么办?答:在上游定义公共接口,下游注入自己的实现;不要把上游 expect 暴露成下游可重绑定的契约。
07.2.3.1-045 expect class 在 Kotlin 2.x 的当前状态如何?
一句话结论
expect class 语法继续保留可用,但成员表达受限、官方更推荐「common 接口 + 平台实现」方案;具体可声明成员与警告级别随版本变化,落地前核对当前 Kotlin 文档(待确认)。
概念解释
早期 KMP 文档大量使用 expect class 封装平台类型;随着工程实践沉淀,接口方案在可测试性、成员表达与导出可读性上更稳。Kotlin 2.x 没有删除该语法,但部分用法可能产生弃用或限制提示。新项目优先接口,存量 expect class 按场景逐步重构。
原理流程
- 查当前 Kotlin 版本官方文档对 expect class 的约束说明。
- 新平台能力优先定义 common 接口。
- 存量 expect class 在重构窗口迁移到接口或保留并标注限制。
代码或图示
// 趋势:common 接口而非 expect class
interface Clock { fun now(): Long }
常见误区
- 照搬早期教程大量创建 expect class,后期测试与导出受限。
- 断言 expect class 在未来一定会被移除:目前是保留使用状态。
追问
- 怎么验证当前版本对某 expect 用法是否告警?答:在试点工程编译,查看编译器提示;以 kotlinlang.org 对应版本文档与发行说明为准(待确认)。
07.2.3.1-046 commonMain 可依赖的库需要满足什么条件?
一句话结论
库必须提供覆盖所声明 target 的多平台构件(KMP 库或旧版多平台构件),且其 API 不绑定 JVM/Android 专属运行时;否则只能下沉平台 main 使用。
概念解释
commonMain 编译时要为每个 target 解析依赖。多平台库在 metadata 构件中声明公共 API,各平台构件提供实现。JVM 库即使源码是 Kotlin,也不能直接进 commonMain,因为 iOS/Web target 解析不到对应构件。判断方式:查库是否有 KMP 坐标、支持哪些 target。
原理流程
- 查库文档与 Maven 坐标,确认多平台构件与 target 列表。
- 支持的库写入 commonMain 依赖。
- 不支持的能力用平台 main 实现,或换多平台替代库。
代码或图示
io.ktor:ktor-client-core 多平台 core
io.ktor:ktor-client-okhttp Android/JVM 引擎(平台 main)
io.ktor:ktor-client-darwin iOS 引擎(iosMain)
常见误区
- 看到库是 Kotlin 写的就放进 commonMain,忽略其仍是 JVM 库。
- 为凑 commonMain 引入只做 JVM 适配的伪多平台库。
追问
- 怎么确认一个库支持哪些 target?答:查 Maven 上的构件列表与官方 README;在试点工程解析依赖,观察各 target 是否都能解析成功(待确认具体版本)。
07.2.3.1-047 Ktor Client 在共享层的定位是什么?
一句话结论
Ktor Client 是 KMP 共享层最常用的 HTTP 客户端:core API 在 commonMain 复用,各平台通过安装对应引擎执行请求,业务代码不直接接触 OkHttp/NSURLSession。
概念解释
Ktor Client 把网络能力抽象为公共客户端与请求管线:common 侧写 HttpClient、请求构造、序列化与拦截器;平台引擎负责实际传输。引擎按 target 选择:Android/JVM 可用 OkHttp 引擎,iOS 用 Darwin 引擎,Web 用 JS 引擎。业务层因此双端复用同一套网络编排。
原理流程
- commonMain 依赖
ktor-client-core与序列化插件。 - 平台 main 引入对应引擎并传给客户端工厂。
- 共享层通过注入的
HttpClient发请求,不感知引擎类型。
代码或图示
// commonMain
val client = HttpClient {
install(ContentNegotiation) { json() }
}
suspend fun fetchPosts(client: HttpClient) =
client.get("/posts").body<List<Post>>()
常见误区
- 在 commonMain 直接依赖某平台引擎坐标。
- 把
HttpClient做成全局可变单例,跨端生命周期与配置难以管理。
追问
- Ktor Client 3.x 与旧 2.x 有哪些 API 变化?答:核心客户端与插件模型延续,部分坐标与配置项有调整;迁移前对照 3.x 官方迁移指南核对(待确认)。
07.2.3.1-048 Ktor Client 引擎按平台如何选择?
一句话结论
引擎在平台 main 装配:Android/JVM 常用 OkHttp 引擎,iOS/macOS 用 Darwin 引擎,Web 目标用 JS 引擎;common 侧只持有 HttpClient 抽象,不引用引擎类型。
概念解释
引擎决定底层传输实现:Darwin 基于系统 URLSession,OkHttp 基于 JVM HTTP 栈,JS 引擎走浏览器 fetch/XHR。选择时要与 target 矩阵一致:同一平台可选用的引擎有限。引擎实例随客户端生命周期创建,不应在 common 层直接 new 引擎。
原理流程
- 列出已声明 target 与对应引擎。
- 平台 main 配置引擎并构建
HttpClient。 - 共享层接收注入的客户端,公共请求逻辑复用。
代码或图示
// androidMain
HttpClient(OkHttp)
// iosMain
HttpClient(Darwin)
常见误区
- 一个平台配置了未发布或不兼容的引擎,运行期类缺失。
- 引擎超时、连接池等平台参数漏配,表现为请求 hang 或失败。
追问
- 引擎层的证书与域名校验在哪配?答:引擎或客户端配置中按平台开启;公共超时、拦截器可在 common 层配置,平台安全相关项在平台 main 核对系统行为。
07.2.3.1-049 SQLDelight 在跨平台数据层如何工作?
一句话结论
SQLDelight 把 SQL 编译成类型安全的 Kotlin 查询,公共 schema 与查询在 commonMain 维护,各平台用对应 SQLite 驱动执行,是 KMP 本地持久化的主流方案之一。
概念解释
SQLDelight 以 .sq 文件定义表与查询,编译器生成 Kotlin 接口与方法;公共数据访问逻辑写在 common 层,平台 main 提供驱动(Android、iOS、JVM 各有对应驱动)。它不做 ORM 式对象映射,SQL 仍是核心,类型安全由生成代码保证。
原理流程
- commonMain 写
.sq表定义与查询语句。 - 编译器生成公共查询接口。
- 平台 main 安装驱动并打开数据库,共享层调用生成方法。
代码或图示
-- 公共查询
select id, name from User where id = :id;
常见误区
- 把平台专属 SQL 方言写进公共
.sq,其他平台驱动不支持。 - 以为 SQLDelight 会自动做数据库迁移:版本迁移脚本仍需显式维护。
追问
- 数据库文件路径与初始化在哪处理?答:平台 main 提供驱动与文件位置,common 层只调用生成的查询接口;具体驱动坐标随版本核对官方文档(待确认)。
07.2.3.1-050 Room、Realm 等库能否进 commonMain?
一句话结论
Room 绑定 Android 与 JVM 注解处理,不能进 commonMain;Realm 有跨平台方案但 API 与成熟度需单独评估;common 层持久化优先选 SQLDelight 这类明确支持 KMP 的库。
概念解释
Room 的编译期处理、Context 与 SQLite 封装都面向 Android,共享层无法直接使用。Realm 提供过跨平台 SDK,但版本演进、target 覆盖与 API 稳定性要以官方现状为准。选型时先确认库的 KMP 构件与 target 列表,再决定公共层依赖还是平台封装。
原理流程
- 核对候选库是否发布多平台构件。
- 公共层只依赖确认支持的库。
- 不支持的能力在平台 main 封装为 common 接口实现。
代码或图示
// commonMain:不直接引用 Room/Realm 类型
interface LocalCache { fun put(key: String, value: String) }
常见误区
- 凭「也是移动数据库」就把 Room 写进共享层。
- 忽略库的 KMP 状态,后期 iOS 编译期才发现缺构件。
追问
- 现有 Android Room 代码如何过渡?答:先在共享层定义缓存/仓储接口,Android 实现保留 Room,其他平台用 SQLDelight 或等价方案;逐步对齐 schema。
07.2.3.1-051 kotlinx.serialization 在 commonMain 如何使用?
一句话结论
kotlinx.serialization 是多平台序列化库:@Serializable 标注数据类,commonMain 配置 JSON 格式,各 target 复用同一套编解码逻辑。
概念解释
序列化插件在编译期为 @Serializable 类生成序列化器,运行时通过 Json 实例编码解码。公共模型与格式配置放 commonMain;平台不需要单独引入 JSON 库。日期、字节、自定义类型需要配合对应序列化器或转换层。
原理流程
- 数据类加
@Serializable,字段类型可序列化。 - commonMain 注入
Json实例,配置忽略未知键、命名策略等。 - 共享层调用
encodeToString/decodeFromString。
代码或图示
@Serializable
data class Post(val id: Long, val title: String)
val json = Json { ignoreUnknownKeys = true }
val text = json.encodeToString(Post.serializer(), post)
常见误区
- 数据类漏标
@Serializable,运行期找不到序列化器。 - 把平台日期/二进制类型直接塞进可序列化模型,缺少对应编码器。
追问
- 枚举与密封类的序列化怎么处理?答:按库规则配置类判别器;跨语言传输时字段命名、可选默认值要双端对齐,多态场景在下一题展开。
07.2.3.1-052 序列化多态在共享层有哪些注意点?
一句话结论
密封类/接口的多态序列化需要显式注册子类或配置判别字段;公共契约要稳定,字段增删与可选值变更需双端兼容,避免解码失败。
概念解释
多态编码依赖类型判别信息(通常是 type 字段)。kotlinx.serialization 对密封类有内置支持,开放接口需要 SerializersModule 注册子类。跨端传输时,新增子类、改判别名、去掉默认值都可能让旧客户端解码失败,需要版本兼容策略。
原理流程
- 定义公共继承体系与判别字段。
- 配置
SerializersModule或依赖密封类内置规则。 - 灰度期校验新旧客户端对新旧模型的解码兼容性。
代码或图示
@Serializable
sealed class Card {
@Serializable data class TextCard(val text: String) : Card()
@Serializable data class ImageCard(val url: String) : Card()
}
常见误区
- 新增子类未在模块注册,旧端解码报未知类型。
- 直接修改已上线字段名或类型,没有兼容期。
追问
- 后端返回的 JSON 结构不稳定怎么办?答:公共模型用宽松可空字段与默认值兜底,解析失败在仓储层映射为领域错误;不要把原始动态 JSON 透传到 UI 层。
07.2.3.1-053 Koin 多平台模块如何组织?
一句话结论
Koin 的模块定义在 commonMain,按业务分层注册单例与工厂;平台实现通过绑定接口注册,各端入口启动对应 Koin 容器,共享层从容器取依赖。
概念解释
Koin 提供多平台 DSL:module { single { } }、factory { } 在公共层编写。公共接口注册平台实现时,平台模块补充绑定。容器生命周期跟随 App 进程;共享库不自行启动 Koin,避免重复容器与全局状态。
原理流程
- commonMain 定义公共模块与接口绑定。
- 平台 main 补充平台实现绑定。
- App 入口合并模块并
startKoin,共享层通过注入获取实例。
代码或图示
val commonModule = module {
single { HttpClient() }
single<AuthGate> { DefaultAuthGate(get()) }
}
常见误区
- 在共享库内部自动启动 Koin,导致多容器并存。
- 平台实现漏注册,运行期解析不到依赖。
追问
- Koin 与手写 DI 怎么选?答:模块小、绑定简单可手写工厂;需要作用域、生命周期与多模块装配时 Koin 更系统。版本与 target 支持以官方发布为准(待确认)。
07.2.3.1-054 依赖注入在 common 层与平台层的边界怎么划?
一句话结论
common 层声明接口与注入点,平台层负责实现选择与实例装配;common 不创建平台对象,平台不绕过公共契约直接回传原生类型。
概念解释
依赖倒置让共享层面向抽象:构造函数接收接口,平台入口决定注入哪个实现。边界清晰后,common 层可独立测试,平台实现可替换。常见越界:共享层内部 new 平台类、平台把原生对象塞进 common、全局单例跨层持有状态。
原理流程
- common 定义依赖接口与接收方。
- 平台 main 实现接口并在装配期注册。
- 共享层只使用接口方法,不感知实现来源。
代码或图示
// commonMain
class ProfileViewModel(private val repo: ProfileRepository)
// 平台装配
// container.bind<ProfileRepository> { IosProfileRepo() }
常见误区
- 共享层用
object直接持有平台实现。 - 平台实现返回原生对象,common 被迫类型强转。
追问
- 生命周期长的依赖(客户端、数据库)怎么管理?答:在平台入口创建并持有单例,注入共享层;关闭与释放由平台生命周期负责,共享层不持有销毁职责。
07.2.3.1-055 跨平台日志库如何选择?
一句话结论
common 层定义日志接口或使用支持 KMP 的日志库;JVM 常用的 kotlin-logging 等不能直接进 commonMain,平台 main 负责桥接到本端日志系统。
概念解释
JVM 日志框架(SLF4J、Logback)绑定 Java 运行时,iOS/Web 不可用。可选路径:在 common 定义最小日志接口,平台实现分别桥接到 Android Log、iOS os_log、浏览器 console;或采用已发布 KMP 构件的日志库。日志级别、标签与脱敏规则在公共层统一。
原理流程
- common 定义
Logger接口与级别。 - 平台 main 实现并桥接本端日志通道。
- 共享层通过注入记录日志,敏感字段在公共层脱敏。
代码或图示
interface Logger {
fun debug(tag: String, message: String)
fun error(tag: String, message: String, throwable: Throwable?)
}
常见误区
- 在 commonMain 直接用
println当日志,上线后无法分级与采集。 - 把 JVM 日志门面加进共享层,iOS 编译失败。
追问
- 日志里的异常如何跨端传递?答:共享层抛 Kotlin 异常,日志接口接收
Throwable;导出到 Swift 时异常类型映射另见互操作题目。
07.2.3.1-056 日期时间在共享层用什么库?
一句话结论
优先使用 kotlinx-datetime 这类多平台日期时间库;JDK 时间 API 不能进 commonMain,公共模型避免使用 java.time 类型。
概念解释
java.time 与 Date 是 JVM 类型,iOS/Web target 不可用。kotlinx-datetime 提供跨平台的 Instant、LocalDate、时区计算等抽象;平台 main 在边界做系统日期转换。业务层统一用库类型,序列化时再转为时间戳或 ISO 字符串。
原理流程
- common 模型使用 kotlinx-datetime 类型或时间戳。
- 序列化层在边界与字符串/时间戳互转。
- 平台 main 需要系统日期时做双向映射。
代码或图示
import kotlinx.datetime.Instant
data class Session(val createdAt: Instant)
常见误区
- commonMain 引用
LocalDateTime、Date,非 JVM target 编译失败。 - 用本地时区时间存储业务时刻,跨端展示与计算出错。
追问
- 跨端传日期用什么格式?答:传 UTC 时间戳或 ISO-8601 字符串,展示层按本端时区格式化;时区处理逻辑在公共层复用。
07.2.3.1-057 加密与安全库在共享层有哪些限制?
一句话结论
common 层只能复用算法无关的协议与模型;加解密、密钥存储、安全随机数依赖平台安全能力,通常通过 expect/actual 或接口在平台 main 实现。
概念解释
Android Keystore、iOS Keychain、安全随机源、加密套件都是平台能力。纯算法(哈希校验、格式校验)可下沉公共层;密钥保管、对称/非对称加解密、证书校验在平台侧完成。共享层不应自带硬编码密钥或自研加密实现。
原理流程
- 区分公共规则与平台安全能力。
- 平台 main 实现安全接口,接入系统安全存储。
- common 层只调用抽象方法,不接触密钥材料。
代码或图示
interface SecureStore {
fun saveSecret(key: String, value: String)
fun readSecret(key: String): String?
}
常见误区
- 在共享层引入 JVM 加密 API 或纯软件密钥存储。
- 把密钥写进 common 配置或日志。
追问
- 跨端需要一致的哈希怎么做?答:公共层定义算法与输入规范,平台实现调用系统/标准库哈希;摘要结果比较使用恒定时间方式,具体安全实现需按平台文档核对(待确认)。
07.2.3.1-058 第三方库不支持 KMP 时的兜底方案是什么?
一句话结论
在 common 定义接口,平台 main 分别用本端库实现;公共层只依赖接口,必要时用多平台替代库,避免把 JVM 库强行塞进共享层。
概念解释
缺口库常见于设备能力、支付、地图、统计 SDK。兜底路径:先找 KMP 替代;没有则做平台适配层:common 接口固定输入输出,Android 用原 SDK、iOS 用对应 SDK,结果统一为公共模型。适配层代码量与双端 SDK 差异成正比,选型时要计入成本。
原理流程
- 评估是否有 KMP 替代库。
- 无替代则在 common 定义能力接口。
- 平台 main 封装原生 SDK,返回公共数据模型。
代码或图示
interface PushService {
suspend fun register(): String
}
// androidMain: 封装厂商推送 SDK
// iosMain: 封装 APNs 注册
常见误区
- 等待库官方支持 KMP 而阻塞业务,或硬把 JVM 库编译进共享层。
- 平台适配层返回原生对象,导致 common 与 UI 被迫耦合 SDK 类型。
追问
- 适配层工作量怎么估?答:按接口方法数 × 双端 SDK 接入成本估算;双端 SDK 能力不对等时,公共契约要取交集,缺失能力在平台侧标注不可用。
07.2.3.1-059 如何检查共享层误用了 JVM 专属 API?
一句话结论
以全 target 编译为门禁:CI 中执行各 target 编译与测试,JVM 专属 API 会在非 JVM target 解析失败;代码评审按 stdlib 与多平台库清单核对导入。
概念解释
JVM 专属 API(java.util、java.io、java.lang 非映射类、JVM 注解)在 commonMain 中对 JVM target 看似可用,iOS/Web 编译期才暴露。静态检查可辅助扫描导入语句,但最可靠的门禁是多 target 编译通过。新增依赖也要核对其构件是否覆盖全部 target。
原理流程
- commonMain 只导入 stdlib 与多平台库包。
- CI 跑 android、ios、jvm、wasm 各 target 编译与测试。
- 非 JVM 报错回溯到 common 误用点,下沉平台实现。
代码或图示
禁止导入:java.util.*、java.io.*、java.math.BigDecimal(非映射)
允许:kotlin.*、kotlinx.* 及已确认多平台库
常见误区
- 只在 Android/JVM 上验证,漏检 iOS/Web 编译问题。
- 通过反射或字符串调用 JVM 类,绕过静态可见性检查。
追问
- 团队怎么固化这条规则?答:评审清单加入导入审查,CI 保留全 target 构建;新成员与依赖改动以编译结果为准,不凭经验判断 API 可移植性。
07.2.3.1-060 共享层代码体积与依赖裁剪怎么做?
一句话结论
公共层只保留跨端复用代码,平台依赖隔离在平台 main;通过模块拆分、剔除未用传递依赖、检查各 target 产物体积,避免 common 引入大而全的库。
概念解释
共享层体积影响 iOS framework 与 APK 大小:common 依赖会被各 target 复制打包。裁剪手段:按层拆模块,业务方只依赖所需模块;审查 common 依赖是否有未使用功能;Native 产物保留符号裁剪配置;Web 目标关注打包体积。重复的工具类不应在多模块各自引入。
原理流程
- 拆分 core-model、core-network 等窄职责模块。
- 审查 common 依赖清单,移除未用库与冗余传递依赖。
- 对比各产物体积基线,定位体积增长来源。
代码或图示
shared-android APK 体积含 common + android 依赖
shared-ios framework 体积含 common + ios 依赖 + 运行时
常见误区
- common 引入全家桶工具库,所有端被迫打包。
- 只看 Android 体积,忽略 iOS framework 增长。
追问
- 体积基线怎么建?答:在试点期记录各 target 产物大小,每次大依赖改动前后对比;符号裁剪、混淆与资源策略按平台发布规范配置。
07.2.3.1-061 Kotlin/Native 的内存模型经历了什么演进?
一句话结论
早期 Kotlin/Native 采用带对象归属与共享冻结约束的旧内存模型;新内存模型(自 Kotlin 1.7.20 起逐步稳定)取消大部分冻结限制,对象可在线程间共享,行为更接近 JVM 并发模型。
概念解释
旧模型下跨线程共享对象需要冻结(frozen)或限定线程归属,并发编写受限。新内存模型允许普通对象在并发场景共享,垃圾回收与线程调度与 JVM 更接近,但线程安全仍需开发者保证:共享可变状态需要同步原语。版本基线 Kotlin 2.x 使用新模型,旧迁移问题按版本核对文档。
原理流程
- 旧模型:对象绑定线程归属,跨线程需冻结。
- 新模型:取消冻结为主的限制,支持并发共享可变对象。
- 开发者用 Mutex、线程封闭等方式保证状态一致性。
代码或图示
// 共享可变状态需要显式同步
private val mutex = Mutex()
private var counter = 0
suspend fun increment() = mutex.withLock { counter++ }
常见误区
- 仍按旧模型把所有对象冻结,或误以为新模型下共享可变状态自动安全。
- 在 iOS 后台线程持有主线程 UI 对象引用而不做切换。
追问
- 新模型下旧代码的
freeze()还需要吗?答:按版本兼容情况处理;Kotlin 2.x 基线以官方迁移说明为准,项目中旧冻结调用需逐一核对(待确认)。
07.2.3.1-062 iOS 上协程调度器与主线程如何配合?
一句话结论
共享层挂起任务在后台调度执行,更新 UI 的回调必须切回主线程;iOS 主线程对应主 RunLoop,跨线程更新界面会崩溃或表现异常。
概念解释
Kotlin/Native 协程在平台线程上调度:Dispatchers.Default 跑后台任务,主线程调度器绑定 iOS 主队列。业务编排可在共享层完成,结果回到平台侧由主线程刷新 UI。跨层回调要明确线程约定:网络、数据库回调默认后台,UI 刷新在平台入口切主线程。
原理流程
- 共享层用
Dispatchers.Default执行后台挂起任务。 - 结果通过回调/Flow 回到平台。
- 平台 main 在主线程更新 SwiftUI/UIKit 界面。
代码或图示
// commonMain:后台执行
suspend fun loadUser(): User = withContext(Dispatchers.Default) {
repo.fetch()
}
常见误区
- 假设协程回调天然在主线程,直接在共享层触发 UI 刷新。
- 在主线程执行网络/数据库阻塞操作,造成界面卡顿。
追问
- 平台侧怎么切主线程?答:iOS 用主队列派发,Android 用主线程 Handler/View 调用;共享层只保证后台任务与线程约定,不直接操作 UI。
07.2.3.1-063 Dispatchers.Main 在 iOS 的可用性如何?
一句话结论
Dispatchers.Main 在 iOS 目标可用并绑定主线程,但使用范围限于需要主线程的场景;共享层公共逻辑应优先用 Default/IO 语义调度,避免在 common 层强绑主线程。
概念解释
主线程调度器把协程调度到平台主线程队列。共享层面向多平台,若在公共代码写 Dispatchers.Main,会把平台线程假设带入 common。更稳的做法:公共层执行后台任务,主线程切换由平台入口决定。跨平台协程库对 Main 调度器的具体实现随版本演进,使用前核对文档(待确认)。
原理流程
- common 后台任务使用默认/后台调度器。
- 平台入口需要主线程时取
Dispatchers.Main。 - 共享层不持有主线程引用,便于测试与复用。
代码或图示
// 不推荐在 common 公共业务里写
// withContext(Dispatchers.Main) { ... }
常见误区
- common 层到处使用 Main 调度器,Web/JVM 行为不一致。
- 在 Main 上做长时间挂起或阻塞计算。
追问
- 跨平台测试如何验证线程切换?答:commonTest 验证业务结果,线程切换与 UI 刷新在平台测试源集验证;调度器注入可便于测试替身。
07.2.3.1-064 Dispatchers.Default 与 IO 在 iOS 的行为有何特点?
一句话结论
Default 用于 CPU 密集型任务,IO 调度在不同平台实现有差异;iOS 上不要假设与 JVM IO 线程池行为完全一致,阻塞式 IO 应避免,改用挂起式非阻塞调用。
概念解释
JVM 上 Dispatchers.IO 有独立线程池承载阻塞 IO;Native 目标的调度器实现受平台线程模型约束。共享层应优先使用 Ktor、SQLDelight 等提供的挂起式 API,而不是在线程池里跑阻塞调用。跨平台公共代码不要硬编码线程数或线程池行为。
原理流程
- CPU 计算任务用
Default。 - IO 走挂起式客户端 API,不手动阻塞线程。
- 平台特定线程池在平台 main 封装。
代码或图示
// 推荐:挂起式请求,不阻塞线程
suspend fun load(): List<Post> = client.get("/posts").body()
常见误区
- 在共享层起阻塞线程做文件/网络 IO,iOS 线程资源受限。
- 假设 iOS 有与 JVM 相同的 IO 线程池容量与排队策略。
追问
- 必须跑阻塞调用怎么办?答:下沉平台 main,在本端线程模型内封装为挂起函数;公共层不直接操作底层线程。
07.2.3.1-065 共享状态在 iOS 上有哪些线程安全要求?
一句话结论
即使新内存模型允许对象跨线程共享,共享可变状态仍需 Mutex、Actor 式封装或线程封闭;多协程并发修改同一变量会产生竞态。
概念解释
新模型取消冻结不等于自动并发安全。多个协程读写同一个可变集合或变量时,需要同步原语保护。常见风险:缓存、计数器、会话状态在后台线程被并发修改。共享层提供线程安全的数据封装,平台侧不要绕过封装直接改内部状态。
原理流程
- 识别跨协程共享的可变状态。
- 用
Mutex.withLock、单线程封闭或不可变数据保护。 - 对外暴露只读访问或线程安全方法。
代码或图示
class SafeCache {
private val mutex = Mutex()
private val map = mutableMapOf<String, String>()
suspend fun put(k: String, v: String) = mutex.withLock { map[k] = v }
suspend fun get(k: String) = mutex.withLock { map[k] }
}
常见误区
- 把普通
var/MutableList当线程安全容器共享。 - 读不加锁、写加锁,读到中间状态。
追问
- 不可变状态是否就安全?答:不可变对象发布后可安全共享;每次更新生成新对象的模式可减少锁竞争,是跨平台常用思路。
07.2.3.1-066 iOS 主线程阻塞会有什么表现,如何避免?
一句话结论
主线程被阻塞会导致界面无响应、触摸事件延迟,严重时被系统 watchdog 终止;共享层的网络、数据库、重计算必须挂起在后台,不能在主线程同步等待。
概念解释
iOS 主 RunLoop 负责界面渲染与事件分发,长时间同步阻塞会造成掉帧与卡死。KMP 共享层若在主线程调用阻塞式 API(同步 HTTP、阻塞数据库、死循环计算),问题与原生开发一致。平台入口应把任务提交到后台,结果回主线程刷新。
原理流程
- 排查启动与页面回调中是否存在同步阻塞调用。
- 共享层改为挂起式 API,后台调度执行。
- 平台侧在主线程只做轻量 UI 更新。
代码或图示
// 错误:主线程同步等待阻塞结果
// val data = blockingApi()
// 正确:挂起返回,后台执行
suspend fun load(): Data = repository.data()
常见误区
- 用
runBlocking在主线程等待共享层结果。 - 把大数据解析、JSON 转换放在主线程。
追问
- 怎么定位主线程卡顿?答:用 Instruments/性能工具看主线程耗时调用栈,回溯到共享层阻塞点;跨端基线在 CMP 性能题目继续展开。
07.2.3.1-067 协程作用域在 iOS 侧如何绑定生命周期?
一句话结论
共享层 ViewModel/用例持有自己的 CoroutineScope,平台页面在销毁时调用取消方法;避免全局作用域导致任务泄漏与回调残留。
概念解释
跨层协程需要明确作用域归属:公共层用例可创建 SupervisorJob + Dispatchers 的作用域,暴露 close()/cancel() 入口;iOS 页面退出时调用该入口取消未完成任务。全局 GlobalScope 不用于业务页面,防止页面销毁后回调仍访问已释放对象。
原理流程
- 公共层定义作用域与取消方法。
- 平台页面出现时启动订阅,销毁时调用取消。
- 协程取消后不再向平台侧发结果回调。
代码或图示
class ProfileViewModel {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
fun close() = scope.cancel()
}
常见误区
- 页面退出后协程仍持有 Kotlin 对象,回调触发时平台对象已释放。
- 用 GlobalScope 启动业务协程,无法随页面取消。
追问
- 长时间任务(上传、同步)要不要跟随页面取消?答:按业务区分:页面级任务跟随取消,后台持久任务由平台进程级作用域持有,并做任务状态持久化。
07.2.3.1-068 挂起函数导出到 Swift 后是什么调用形态?
一句话结论
Kotlin suspend 函数在 Objective-C/Swift 边界导出为带 completion handler 的异步方法;Swift 侧可通过桥接包装成 async/await,不能按普通同步函数直接调用。
概念解释
Kotlin/Native 互操作把挂起函数翻译为接收回调的方法:参数末尾追加 completion,结果与异常通过回调返回。Swift 6 可在桥接层封装为 async 函数。直接在 Swift 同步等待会阻塞线程;返回的 Task/回调必须处理生命周期与重复回调。
原理流程
- 共享层声明
suspend fun。 - 生成框架时导出 completion handler 形态。
- Swift 侧回调取结果,或包一层 async 桥接。
代码或图示
// 导出后典型调用形态
repo.fetchPosts { result, error in
// 处理结果或异常
}
常见误区
- Swift 侧把 suspend 方法当同步函数取值。
- 回调闭包强引用 Kotlin 对象与页面,造成循环引用。
追问
- 怎么提供 Swift async/await 接口?答:在桥接封装层写
withCheckedContinuation包装 completion 回调;具体导出签名以生成头文件为准(待确认)。
07.2.3.1-069 suspend 与 completion handler 之间如何桥接?
一句话结论
Kotlin 挂起函数内部用协程调度,边界上由互操作层转成 completion 回调;反向把 Swift 闭包传给 Kotlin 时,闭包作为普通函数/接口参数接收,回调线程由调用方约定。
概念解释
正向:suspend → completion,编译器生成回调签名。反向:Swift 闭包传给 Kotlin 时,需要在 common 定义函数类型或单方法接口,平台桥接把闭包适配进去。回调是否在主线程、是否允许重复调用,必须在接口契约里写明,否则平台侧容易出现线程错乱与泄漏。
原理流程
- common 定义回调接口或函数类型。
- 平台桥接把 Swift 闭包适配为该类型。
- 共享层在确定线程上回调,平台侧按约定刷新 UI。
代码或图示
// commonMain
interface ProgressListener {
fun onProgress(percent: Int)
}
常见误区
- 回调在后台线程触发,平台直接刷新 UI。
- 闭包捕获页面强引用,回调不释放导致泄漏。
追问
- 回调只需要单次结果怎么办?答:用 suspend + completion 桥接;多次更新用 Flow 或监听器接口,避免单次回调被反复调用。
07.2.3.1-070 Flow 在 Swift 侧如何订阅?
一句话结论
Flow 不直接作为强类型流导出给 Swift;常见做法是在共享层提供带监听器接口的订阅方法,或在桥接层把 Flow 收集为回调序列,Swift 侧按回调接收增量数据。
概念解释
Kotlin Flow 是协程响应式流,Objective-C/Swift 没有对等原生类型,导出泛型与协程链受限。工程上通常封装:common 定义 StateListener 接口,共享层启动协程收集 Flow 并回调;Swift 实现接口注册订阅,页面销毁时取消订阅。数据模型用具体 data class,避免嵌套泛型导出。
原理流程
- common 定义监听器接口与订阅/取消方法。
- 共享层协程收集 Flow,逐帧回调接口。
- Swift 侧实现接口并在退出时注销。
代码或图示
interface CounterListener { fun onValue(value: Int) }
class CounterViewModel {
fun subscribe(listener: CounterListener) { /* collect flow */ }
fun unsubscribe() { /* cancel */ }
}
常见误区
- 直接把
Flow<T>暴露给 Swift,头文件类型不可读或擦除。 - 订阅后不取消,Flow 持续收集并回调已释放页面。
追问
- 状态流与一次性事件分别怎么导出?答:状态流用监听器持续推送;一次性事件(Toast、导航)用单次回调或事件队列,避免重复消费。
07.2.3.1-071 并发原语在跨平台有哪些可用选择?
一句话结论
kotlinx.coroutines 提供 Mutex、withLock、Channel、Actor 风格封装;跨平台公共代码使用这些协程原语,不直接依赖 JVM synchronized、ReentrantLock 或平台线程锁。
概念解释
JVM 并发工具类不能进 commonMain。协程原语在各 target 有对应实现:Mutex 保护共享状态,Channel 做协程间通信,不可变数据与线程封闭作为补充。共享层封装线程安全容器,平台侧不直接操作内部可变状态。
原理流程
- 识别共享可变状态与通信通道。
- 用 Mutex 保护临界区,Channel 传递事件。
- 避免引入 JVM 锁原语与平台线程 API。
代码或图示
private val channel = Channel<Event>()
suspend fun send(event: Event) = channel.send(event)
常见误区
- commonMain 使用
synchronized块或 JVM 锁类。 - 用全局可变集合替代 Channel 做协程间传递。
追问
- 高并发写场景选锁还是消息队列?答:临界区小用 Mutex;生产者-消费者模型用 Channel 解耦,减少锁竞争;具体容量与缓冲策略按场景设计。
07.2.3.1-072 后台线程与主线程切换的常见写法有哪些?
一句话结论
共享层后台执行挂起任务,平台入口在需要刷新 UI 时切主线程;公共代码通过调度器注入与回调约定表达线程边界,不直接操作平台线程。
概念解释
标准写法:用例在作用域内启动协程,withContext 切换后台调度;结果通过接口回调。Android 在主线程 Handler/View 派发,iOS 在主队列派发。线程约定写进接口文档:回调线程、是否可空、是否单次。
原理流程
- 公共层定义后台执行方法与结果回调。
- 平台页面调用后在主线程接收回调。
- 退出页面时取消作用域与订阅。
代码或图示
suspend fun loadProfile(): Profile =
withContext(Dispatchers.Default) { repository.profile() }
常见误区
- 公共层直接引用平台主线程 API。
- 回调线程不固定,平台侧每次猜测切线程。
追问
- 怎么在评审中检查线程约定?答:看接口注释是否写明回调线程与生命周期;代码中是否存在主线程阻塞、GlobalScope 与未取消的订阅。
07.2.3.1-073 iOS 上 Kotlin 线程与 NSThread/平台线程是什么关系?
一句话结论
Kotlin/Native 协程运行在平台线程之上,调度器映射到系统线程;共享层不直接操作 NSThread,线程创建与复用由运行时与平台调度负责。
概念解释
Kotlin/Native 没有独立虚拟机线程,协程挂起在系统线程上恢复。公共代码不应假设线程名称、线程数或线程局部存储行为。平台需要控制线程时(专用后台队列、实时任务),在平台 main 封装为挂起函数。调试时可通过线程名/调用栈区分平台主线程与后台线程。
原理流程
- 协程挂起让出系统线程,恢复时由调度器选线程。
- 平台专用线程在平台层创建与管理。
- 公共层只依赖挂起式 API 与调度器抽象。
代码或图示
Kotlin 协程 → Kotlin/Native 调度器 → iOS 系统线程(主队列/后台线程)
常见误区
- 依赖线程局部变量在协程间传递上下文。
- 假设后台任务始终在同一个系统线程恢复。
追问
- 平台强依赖专用线程怎么办?答:在平台 main 封装队列,提供挂起方法;公共层面向该方法调用,不接触底层线程对象。
07.2.3.1-074 长时间任务在共享层如何调度?
一句话结论
按任务归属拆分页面级与进程级作用域:页面任务跟随 ViewModel 取消,后台持久任务由平台进程级作用域持有,并支持状态持久化与中断恢复。
概念解释
上传、批量同步、导入导出等长任务不能绑死单个页面。公共层提供任务状态与进度回调,平台决定作用域生命周期。任务进度、断点状态需要持久化,避免 App 被杀后从头再来。共享层不使用全局作用域启动业务任务。
原理流程
- 区分任务是否随页面销毁。
- 页面任务挂在 ViewModel 作用域,进程任务挂在平台长生命周期作用域。
- 进度与断点持久化,回调按接口约定推送。
代码或图示
class UploadSession(scope: CoroutineScope) {
fun start() { /* 进度回调 + 状态持久化 */ }
fun cancel() { /* 释放协程与资源 */ }
}
常见误区
- 长任务用 GlobalScope,页面退出后仍占用资源。
- 任务状态只存内存,App 重启后无法续传。
追问
- 任务与网络层如何配合?答:长任务内部使用挂式客户端与重试策略;取消时释放连接与临时文件,平台层负责任务记录与重新调度。
07.2.3.1-075 线程相关崩溃与竞态如何排查?
一句话结论
先按崩溃栈定位是否主线程违规或并发修改,再复核共享可变状态的同步保护;复现路径通常是多协程并发回调、页面退出后残留引用。
概念解释
典型问题:后台线程刷新 UI、并发写同一集合、回调访问已释放对象。排查顺序:崩溃线程与调用栈 → 触发路径(并发/生命周期)→ 共享状态封装是否加锁 → 订阅是否取消。线上可通过崩溃日志的线程名与回调链回溯。本地复现需增大并发或延迟抖动。
原理流程
- 读取崩溃栈,判断主线程违规还是状态竞争。
- 检查回调线程约定与订阅取消时机。
- 复核可变状态的锁/不可变封装,补测试用例。
代码或图示
主线程 UI 访问异常 → 回调未切主线程
ConcurrentModification / 数据错乱 → 共享集合无同步
野指针/已释放引用 → 作用域未取消、闭包强引用
常见误区
- 只改 UI 刷新线程,不修底层并发写竞争。
- 靠重试或延后回调规避竞态,根因仍在。
追问
- 怎么预防?答:接口写明线程约定,共享状态封装线程安全容器,页面退出统一取消作用域;评审检查 GlobalScope、可变集合与闭包引用。
07.2.3.1-076 Kotlin/Native 生成的 Objective-C 框架结构是怎样的?
一句话结论
framework 包含编译二进制、导出头文件与资源;头文件按包名/类型生成 ObjC 接口,导出的 public 类型、函数与属性可见,internal 与 private 类型不出现。
概念解释
互操作层为 Kotlin 公共声明生成 ObjC 头文件:类映射为 ObjC 类,顶层函数挂到对应类,属性与方法生成 accessor。数据类、枚举、密封类型按规则转换。框架结构随 target 与配置变化,具体符号以生成头文件为准;不导出的类型 Swift 侧无法引用。
原理流程
- 编译 Kotlin 产物并链接 framework。
- 互操作层生成
.h头文件与类型映射。 - Xcode 链接后 Swift/ObjC 按头文件调用。
代码或图示
Shared.framework/
├── Shared 二进制
├── Headers/Shared.h
└── Modules/ 模块定义(按版本)
常见误区
- 期望 internal 类型在 Swift 侧可用。
- 把头文件里的映射类型当成 Kotlin 原始类型直接混用。
追问
- 怎么检查导出符号是否完整?答:打开生成头文件核对类、方法与属性;缺失则调整可见性或导出注解,具体注解能力以当前版本为准(待确认)。
07.2.3.1-077 挂起函数导出为 completion handler 后参数如何排列?
一句话结论
导出方法保留原参数,末尾追加 completion 参数;回调携带结果与错误,错误映射为 Kotlin 异常对应的平台类型,具体签名以生成头文件为准。
概念解释
completion 回调通常接收结果对象与错误对象两个参数:成功时结果非空、错误为空;失败时错误非空。原参数顺序不变。Swift 侧调用要判断结果与错误分支,不能只看返回值。泛型结果在头文件中可能被擦除为基础类型或包装类。
原理流程
- 共享层定义 suspend 方法与结果类型。
- 生成框架时追加 completion 参数。
- Swift 侧按结果/错误分支处理,必要时包 async 桥接。
代码或图示
// 头文件形态(示意)
- (void)fetchUser:(int64_t)userId
completion:(void (^)(User * _Nullable, NSError * _Nullable))completion;
常见误区
- 假设回调总是在主线程触发。
- 忽略错误分支,失败时结果为 nil 被当作空数据处理。
追问
- 回调多次触发怎么界定?答:契约上 suspend 只回调一次;多次推送用监听器/Flow 封装,避免 completion 被重复调用导致状态错乱。
07.2.3.1-078 异常导出:@Throws 与 KotlinException 如何工作?
一句话结论
Kotlin 受检异常通过 @Throws 标注导出为 ObjC 可抛出类型;未标注的非受检异常在边界包装为 KotlinException 类错误,Swift 侧按平台错误类型接收。
概念解释
JVM/ObjC 异常模型不同:Kotlin 异常导出时,标注 @Throws(...) 的方法在头文件声明可抛异常;其他 Throwable 包装为 Kotlin/Native 运行时的异常类型。平台侧需要把异常映射为可读错误模型,而不是把内部异常透传。共享层建议定义公共错误类型,在边界转换。
原理流程
- 公共层定义领域错误与结果包装。
- 需要导出的方法按规则标注
@Throws。 - 平台侧把 KotlinException 映射为 UI 可展示错误。
代码或图示
@Throws(IOException::class)
suspend fun download(url: String): ByteArray
常见误区
- 把内部堆栈与异常类名直接展示给用户。
- Swift 侧只捕获 NSError,忽略 KotlinException 包装层。
追问
- 跨层错误模型怎么设计?答:公共层用密封错误类或
Result包装,平台边界映射为平台错误;网络错误、业务错误、未知错误分层处理。
07.2.3.1-079 非受检异常在 Swift 侧如何表现?
一句话结论
未标注 @Throws 的 Kotlin 异常在边界被包装为 KotlinException 类错误对象,completion 错误分支返回;Swift 侧需要识别包装层并还原错误信息。
概念解释
Kotlin 运行时异常在 Native 边界不是直接抛出 ObjC 异常,而是经互操作包装。常见表现:回调错误对象携带 Kotlin 异常类型名与消息。如果公共层抛出未捕获的 IllegalStateException 等,平台侧看到的是包装错误。设计上应把异常转为公共错误结果,减少平台对包装类型的依赖。
原理流程
- 共享层内部捕获异常并转为领域错误。
- 无法转换的异常沿 completion 错误分支返回。
- Swift 侧解析错误类型名/消息,映射为提示文案。
代码或图示
// 推荐:异常转结果
fun run(): Result<Data> = try {
Result.success(service.call())
} catch (e: Throwable) {
Result.failure(e.toDomainError())
}
常见误区
- 假设 Swift 可直接
catchKotlin 异常类型。 - 把 KotlinException 的内部消息直接展示给用户。
追问
- 崩溃类异常(空指针、断言)怎么办?答:在公共层防御性检查,避免运行到边界;线上崩溃监控按平台通道采集,异常类型映射在发布前对齐。
07.2.3.1-080 泛型导出有哪些限制?
一句话结论
复杂嵌套泛型、泛型方法与部分集合泛型在 ObjC 导出时被擦弱或包装;跨语言接口应使用具体 data class 结果,避免直接暴露 List<List<T>>、嵌套泛型回调。
概念解释
Objective-C 泛型表达能力有限,Kotlin/Native 导出只能映射其中一部分:外层类可带类型参数,深层嵌套与通配符常被擦除。导出可读性差时,Swift 侧拿到的是弱类型集合。工程做法是在公共层定义具体响应模型,把泛型结构拍平为字段。
原理流程
- 审查导出方法的参数与返回类型。
- 嵌套泛型在公共层封装为 data class。
- 生成头文件核对类型是否保留预期信息。
代码或图示
// 不推荐直接导出
fun fetchGroups(): List<List<User>>
// 推荐:具体模型
@Serializable
data class Group(val members: List<User>)
fun fetchGroups(): List<Group>
常见误区
- 在 Swift 侧强转被擦除的集合元素,运行期类型错误。
- 用泛型回调做跨层事件总线,头文件不可读。
追问
- 必须返回列表怎么办?答:返回元素为具体 data class 的列表;元素层级深就定义多层模型,不要在边界保留嵌套泛型。
07.2.3.1-081 sealed class/interface 导出到 Swift 是什么形态?
一句话结论
密封类型导出为基类加子类层级,Swift 侧按类分支判断; exhaustive when 在跨语言边界不被保证,新增子类时平台分支需要同步兼容。
概念解释
密封类在 Kotlin 侧限制子类封闭,导出后是 ObjC 继承树:基类与各子类类型可见。Swift 不能直接用 Kotlin 的 sealed 穷尽判断,需要 if/else 或类型检查分支。公共层新增密封子类属于破坏性变更:旧平台代码没有对应分支。
原理流程
- common 定义密封层级与公共字段。
- 导出为基类/子类 ObjC 类型。
- Swift 侧类型判断分支处理,未知类型走兜底。
代码或图示
@Serializable
sealed class UiState {
data class Success(val data: String) : UiState()
data class Error(val message: String) : UiState()
}
常见误区
- 假设 Swift 侧能穷尽匹配密封类型。
- 上线后新增密封子类,旧 App 走到未处理分支。
追问
- 密封类型与接口选哪个导出更稳?答:层级简单、分支固定用密封;需要扩展或跨端注册时用开放接口,平台实现独立注入。
07.2.3.1-082 集合类型导出如何映射?
一句话结论
List/Set/Map 导出为 NSArray/NSSet/NSDictionary 对应形态,元素泛型常被擦弱;跨层推荐用具体模型列表,Map 键值类型也要明确。
概念解释
ObjC 集合是泛型容器但类型标注弱,Kotlin 集合导出时元素类型信息部分保留、部分擦除。Map<String, User> 可能导出为字典形态,Swift 取值需要类型转换。直接暴露大 Map 会让平台侧代码充满强转与空判断。
原理流程
- 优先返回元素为 data class 的列表。
- 字典场景定义键值模型或结构体。
- 头文件核对集合元素类型是否可读。
代码或图示
// 推荐:显式字段
data class UserPage(val items: List<User>, val total: Int)
常见误区
- 导出
Map<String, Any>,平台侧无法判断取值类型。 - 把可变集合直接暴露,外部可绕过封装修改内部状态。
追问
- 字典数据必须跨层传怎么办?答:在公共层定义固定字段模型;动态字典只用于原始数据解析,不进入 UI 与业务边界。
07.2.3.1-083 可空类型导出后如何标注?
一句话结论
Kotlin 可空性映射为 Swift 可选/ObjC 可空标注;公共契约必须明确非空与可空字段,避免平台侧把可空值当非空解包。
概念解释
String 导出为非空,String? 导出为可选。互操作层按类型标注生成头文件可空性。字段默认值、集合空与元素空要区分:空列表不等于含空元素。平台侧误解包可选值会触发崩溃,评审与头文件核对可空标注。
原理流程
- common 模型明确字段可空性与默认值。
- 导出头文件标注 nullability。
- Swift 侧按可选安全解包,不强制
!。
代码或图示
data class Profile(
val name: String, // 非空
val avatarUrl: String? // 可空
)
常见误区
- 接口返回类型写
Any?,可空性与元素类型都丢失。 - Swift 侧对可选值强制解包,空值时崩溃。
追问
- 后端字段缺失如何兜底?答:模型字段给默认值或可空,序列化层忽略未知键;公共层把缺失映射为领域默认值,不在平台侧做补救。
07.2.3.1-084 顶层函数与扩展函数导出到哪里?
一句话结论
顶层函数按包名生成到对应 ObjC 类/命名空间;扩展函数作为静态或包装方法导出,可读性受限;跨层 API 优先封装为类方法或接口方法。
概念解释
Kotlin 顶层函数在导出框架时聚合到生成的宿主类型上,命名受包名与文件规则影响。扩展函数不成为接收者的原生方法,而是导出为包装调用。Swift 侧调用位置与命名可能不符合习惯,工程上把业务操作收敛到公共类/接口,减少散落的顶层与扩展 API。
原理流程
- 公共层整理对外 API,优先类方法。
- 顶层/扩展方法保留在内部工具层。
- 生成头文件核对导出位置与命名。
代码或图示
// 对外:类方法
class SessionRepository {
suspend fun token(): String?
}
常见误区
- 对外能力全写成顶层扩展,Swift 侧找不到入口。
- 包名/文件名调整后导出符号位置变化,平台调用失效。
追问
- 工具函数如何复用?答:内部用顶层函数,对外通过公共类暴露必要方法;导出命名冲突时按版本支持的重命名注解调整(待确认)。
07.2.3.1-085 类型别名与数据类在 Swift 侧可读性如何?
一句话结论
data class 导出为带属性的 ObjC 类,可读性较好;typealias 在边界通常不保留别名语义,跨层模型应使用具名 data class 而非类型别名。
概念解释
数据类的字段导出为属性,构造与取值清晰。类型别名只是编译期别名,导出后底层类型暴露,Swift 侧看不到别名含义。嵌套类、深类型也会影响可读性。跨语言模型尽量扁平、字段具名,避免用别名表达业务含义。
原理流程
- 公共模型使用具名 data class。
- 避免
typealias承载跨层业务类型。 - 头文件核对字段命名与层级。
代码或图示
// 推荐
data class Address(val street: String, val city: String)
// 不推荐跨层:typealias UserId = Long
常见误区
- 用 Long 别名表达 ID,Swift 侧看不出业务语义。
- 数据类嵌套过深,平台侧访问链路过长。
追问
- ID 类型怎么设计更稳?答:跨层可用 Long/String 加字段名表达;强类型包装在 common 用 data class 封装,导出时再评估可读性。
07.2.3.1-086 导出命名冲突与重命名如何处理?
一句话结论
同名类型/方法在边界可能冲突或被加后缀;可按当前版本支持的导出重命名注解调整,公共 API 命名应在设计期避开 ObjC/Swift 习惯冲突。
概念解释
互操作导出对保留字、重名与框架前缀有处理规则,具体注解与后缀随 Kotlin 版本演进。设计期建议:类型名带业务前缀,方法名避免与 Foundation/UIKit 冲突;导出后核对头文件。命名冲突的具体注解能力与默认后缀以官方文档为准(待确认)。
原理流程
- 公共 API 命名避开平台保留字与常见前缀冲突。
- 生成框架后检查头文件命名。
- 需要时使用版本支持的重命名注解。
代码或图示
// 命名带业务前缀,降低冲突概率
data class KmpSession(val token: String)
常见误区
- 类型名与系统类同名,导出后被后缀混淆。
- 依赖未确认的重命名注解在生产工程。
追问
- 怎么验证命名导出?答:每次改公共 API 后重新生成 framework,打开头文件核对类名、方法名与参数名;CI 可保留头文件快照比对。
07.2.3.1-087 Objective-C 互操作与 Swift 互操作有什么差别?
一句话结论
Kotlin/Native 主要导出为 Objective-C 接口,Swift 通过桥接层消费;互操作限制以 ObjC 类型系统为底,Swift 特有类型(结构体、枚举关联值)不直接进入 Kotlin 边界。
概念解释
导出目标是 ObjC 运行时:类、协议、方法、可空标注按 ObjC 规则生成,Swift 再桥接。Swift 值类型(struct、enum 关联值)需要先转为 ObjC 可见的类/模型才能传给 Kotlin。理解限制要以头文件为准,而不是按 Swift 类型能力推断。
原理流程
- Kotlin 公共类型导出为 ObjC 接口。
- Swift 经桥接调用,值类型先转模型。
- 边界类型保持 ObjC 可表达。
代码或图示
Kotlin common → ObjC framework → Swift bridge → Swift 代码
常见误区
- 把 Swift struct 直接当参数传给 Kotlin 方法。
- 以为 Swift 协议能直接映射为 Kotlin 接口。
追问
- Swift 侧需要传一组结构化数据怎么办?答:在 Kotlin 侧定义对应 data class,Swift 构造该类实例传入;不要传 Swift 原生值类型。
07.2.3.1-088 向 Kotlin 层传入 Swift 闭包/回调怎么做?
一句话结论
common 定义单方法接口或函数类型,平台桥接把 Swift 闭包适配为该类型;闭包引用注意生命周期,避免强循环与页面释放后回调。
概念解释
ObjC 边界没有 Kotlin 函数类型的直接对等物,通常用协议/接口承载回调。Swift 实现接口或把闭包包装进适配器。回调线程、单次/多次、是否可空在接口契约写明。闭包捕获页面与 Kotlin 对象时要检查引用链。
原理流程
- common 定义回调接口。
- iOS 桥接实现接口,内部调用 Swift 闭包。
- 订阅注销时释放适配器与闭包引用。
代码或图示
interface ResultCallback {
fun onSuccess(data: String)
fun onFailure(error: String)
}
常见误区
- 闭包强引用页面与 Kotlin 对象,形成循环引用。
- 页面销毁后闭包仍被调用,访问已释放 UI。
追问
- 闭包在哪个线程被调用?答:由共享层按约定线程回调;桥接层不擅自切线程,平台侧按契约刷新 UI。
07.2.3.1-089 回调持有 Kotlin 对象会造成哪些内存问题?
一句话结论
平台闭包/适配器强引用 Kotlin 对象,而 Kotlin 侧订阅又持有回调,会形成循环引用;页面退出后未注销订阅,对象与协程无法释放。
概念解释
跨层引用链:Swift 页面 → 适配器闭包 → Kotlin 回调接口 → ViewModel → 订阅协程。任一环不释放,整链驻留。常见表现:页面反复进出后内存上涨、回调残留触发野指针。需要在页面销毁时注销订阅、断开适配器引用,并检查闭包捕获列表。
原理流程
- 画出页面、适配器、Kotlin 对象与协程的引用链。
- 页面退出调用注销/取消方法。
- 适配器弱引用页面,闭包不持有强引用链。
代码或图示
class ListViewModel {
private var listener: Listener? = null
fun unsubscribe() { listener = null; scope.cancel() }
}
常见误区
- 只取消协程,不释放回调接口引用。
- 闭包默认强引用页面 self,循环引用不断开。
追问
- 怎么验证泄漏?答:反复进出页面观察内存曲线与对象存活; Instruments/Android Profiler 查看引用链,定位未注销的适配器与闭包。
07.2.3.1-090 框架导出的 ABI 稳定性如何理解?
一句话结论
已发布 framework 的公共签名(类型、方法、字段、可空性)属于 ABI 契约:删改签名会让旧平台代码链接或调用失败;新增类型与可选方法兼容性较好,破坏性变更需要版本协调。
概念解释
Xcode 链接的是头文件与二进制接口。Kotlin 侧重命名方法、改参数类型、删除公开属性、改可空性,都会破坏旧 App 或旧桥接代码。跨团队分发 framework 时需要语义化版本与兼容策略。Kotlin 编译器自身的二进制兼容规则另按版本核对。
原理流程
- 列出对外公共 API 与版本承诺。
- 破坏性变更走大版本,保留旧接口过渡。
- 发布前用旧平台工程链接新框架验证。
代码或图示
兼容:新增类、新增可选方法、补默认值
破坏:删除方法、改参数类型、收紧可空性、改返回类型
常见误区
- 认为 Kotlin 源码改了重新打包,旧工程自动适配。
- 小版本里改公共签名,线上 App 调用崩溃。
追问
- 内部模块也要注意 ABI 吗?答:同工程源码依赖以源码编译为准;独立分发 framework、XCFramework 或 CocoaPods 产物时必须考虑 ABI 兼容。
07.2.3.1-091 Android 侧如何调用共享模块?
一句话结论
Android app 模块依赖 shared 工程,直接注入或实例化共享类;androidMain 可使用 Android API,公共方法在主线程/后台按协程约定调用,结果回到主线程刷新界面。
概念解释
Android 是 JVM 目标,共享模块编译为普通类与 jar/dex 参与打包。调用方式与本模块 Kotlin 类一致:ViewModel/仓库从 DI 取共享实例。共享层挂起函数在 Android 用 lifecycleScope/viewModelScope 调用;平台 Context、系统服务由 androidMain 或 app 层提供。
原理流程
- app 模块
implementation(project(":shared"))。 - DI 注册共享仓库与实现。
- Android ViewModel 启动协程调用,结果切主线程更新 UI。
代码或图示
class ProfileViewModel(
private val repo: SharedProfileRepository
) : ViewModel() {
fun load() = viewModelScope.launch {
val profile = repo.profile()
}
}
常见误区
- 在主线程调用共享层阻塞式方法。
- 共享库内部读取 app Context,库无法复用。
追问
- Android 专属能力如何给共享层用?答:在 common 定义接口,androidMain/app 提供实现并注入;共享层不直接持有 Context 单例。
07.2.3.1-092 JNI 与 KMP 共享层是什么关系?
一句话结论
JNI 是 JVM/Android 调用原生 C/C++ 的机制,与 KMP 共享层是两条独立链路;KMP 共享代码在 Android 编译为 JVM 字节码,不需要经过 JNI,只有直接调用 C 库时才另走 Native 绑定。
概念解释
KMP 的 Kotlin/Native 目标底层经 LLVM 生成原生二进制,不依赖 JNI。Android 侧共享模块是普通 JVM 代码;若要接入 C/C++ 库,可通过 JNI(Android)或 Kotlin/Native 的 C 绑定(Native 目标)分别处理。不要把 KMP 框架理解成“用 JNI 把 Kotlin 暴露给 Android”。
原理流程
- Android 共享代码 → JVM 字节码 → dex,直接运行。
- 接入 C 库时:Android 走 JNI,Native 目标走 C interop。
- 两套绑定不混用,接口在 common 抽象。
代码或图示
Android: Kotlin shared → JVM bytecode → dex(无 JNI)
Native: Kotlin shared → Kotlin/Native 二进制
C 库接入: JNI / Cinterop,按 target 分别绑定
常见误区
- 以为 iOS framework 也通过 JNI 接入。
- 把 C 绑定代码写进 commonMain。
追问
- 跨端同一 C 库怎么复用?答:common 定义能力接口,Android 用 JNI 封装、Native 用 Cinterop 封装;两套实现返回公共模型。
07.2.3.1-093 commonTest 在各 target 如何执行?
一句话结论
执行 test 任务时 Gradle 为每个 target 编译并运行对应测试集,commonTest 用例在各平台各跑一遍;平台专属用例在平台测试源集执行,结果可汇总到报告。
概念解释
commonTest 编译进每个 target 的测试产物,同一用例在 JVM、Android、Native 上分别运行。kotlin-test 注解与断言映射到各运行器。平台行为差异导致的失败会在对应 target 暴露;只在 JVM 通过不代表 iOS 可用。CI 应汇总各 target 测试结果。
原理流程
- commonTest 写平台无关用例与断言。
- Gradle 按 target 生成测试任务并执行。
- 汇总各 target 报告,平台缺陷下沉平台测试。
代码或图示
import kotlin.test.Test
import kotlin.test.assertEquals
class ParserTest {
@Test
fun parsesField() = assertEquals("a", Parser("a").field)
}
常见误区
- 只跑 JVM 测试就认为共享层全端可用。
- commonTest 用例依赖平台时间、随机数未固定种子。
追问
- 测试数据与时钟如何隔离?答:注入时钟与随机源,固定输入与预期;平台环境差异在平台测试源集覆盖。
07.2.3.1-094 kotlin-test 多平台测试框架如何使用?
一句话结论
kotlin-test 提供跨平台注解与断言 API,commonTest 统一编写;各 target 映射到对应运行器,版本与 Kotlin 对齐,避免在公共测试中引入 JUnit 专属类。
概念解释
kotlin.test.Test、assertEquals、assertTrue 等在多平台可用;JVM 目标底层映射 JUnit,Native 目标使用对应测试运行器。公共测试不导入 org.junit.*,否则 iOS/Wasm 编译失败。参数化测试、时序断言等能力按库版本支持情况选用。
原理流程
- commonTest 依赖 kotlin-test。
- 用
@Test与 kotlin-test 断言写用例。 - 各 target 测试任务映射运行器并执行。
代码或图示
import kotlin.test.Test
import kotlin.test.assertContains
class ValidatorTest {
@Test
fun rejectsEmpty() = assertContains(Validator.errors(""), "required")
}
常见误区
- commonTest 导入 JUnit 断言与规则。
- 依赖测试框架的 JVM 专属扩展(Rule、Runner)。
追问
- 版本怎么对齐?答:kotlin-test 版本与 Kotlin 版本配套,在版本目录统一管理;具体兼容矩阵以官方发布说明为准(待确认)。
07.2.3.1-095 平台测试源集 androidTest / iosTest 覆盖什么?
一句话结论
需要真实平台 API、UI 交互、数据库实例或系统服务的用例放在平台测试源集:androidTest、iosTest 等;commonTest 只覆盖脱离平台的规则与编排。
概念解释
平台测试源集与平台 main 对称,可以使用本端 SDK 与测试框架。适用场景:平台实现正确性、存储读写、权限与回调、集成链路。UI 测试按各端原生测试框架组织。公共逻辑不应回流到平台测试重复断言。
原理流程
- 判断用例是否依赖平台 API 或真实环境。
- 依赖平台的用例下沉对应测试源集。
- commonTest 保留纯规则、模型与编排测试。
代码或图示
commonTest 规则、解析、模型、编排
androidTest Room/Context、Android 组件集成
iosTest Keychain/URLSession、iOS 集成
常见误区
- 在 commonTest 构造平台对象,非 JVM 编译失败。
- 平台测试重复验证公共规则,维护两份断言。
追问
- 集成测试在 CI 怎么排期?答:commonTest 随每次提交跑;平台集成测试按模块与时长分级,必要时在夜间或合并前执行。
07.2.3.1-096 CocoaPods 集成方式与 podspec 如何生成?
一句话结论
KMP 可通过 Kotlin CocoaPods 插件把共享模块暴露为 Pod:配置 pod 名与 target,插件生成 podspec 与 framework,Xcode 工程经 Podfile 引入;产物与链接方式随插件版本演进。
概念解释
CocoaPods 链路:Gradle 插件注册 kotlin { cocoapods { } },声明 pod 摘要、版本与依赖;pod install 后 Pod 工程链接 KMP 产物。适合团队已用 Pod 管理 iOS 依赖的场景。插件坐标、DSL 与是否支持 SPM 按当前 Kotlin 版本核对(待确认)。
原理流程
- 应用 CocoaPods 插件并配置 pod 元数据。
- 声明 iOS 框架 target 与外部 pod 依赖。
- 执行 pod install,Xcode 工程编译链接 KMP 产物。
代码或图示
kotlin {
cocoapods {
summary = "Shared module"
version = "1.0.0"
}
iosArm64()
iosSimulatorArm64()
}
常见误区
- 手动改生成的 podspec,下次构建被覆盖。
- 把 iOS 外部库依赖写进 commonMain,Pods 链路解析不到。
追问
- 与手动 XCFramework 集成怎么选?答:Pod 体系成熟、依赖统一时用 CocoaPods;需要精确控制二进制与链接路径时手动挂 XCFramework。
07.2.3.1-097 Swift Package Manager 集成的当前状态如何?
一句话结论
SPM 对 KMP 产物的支持属于快速演进能力,可用形态(直接 package 或经 XCFramework 二进制包)以当前 Kotlin 与工具链版本为准;接入前必须在试点工程验证链接与签名流程(待确认)。
概念解释
SPM 原生管理 Swift 源码包,Kotlin/Native 产物是预编译二进制,通常以二进制目标方式接入。不同版本工具链对自动生成 Package 清单的支持程度不同。团队若强依赖 SPM,需要在验证期打通:产物架构、链接、嵌入签名、更新流程,不能按通用 SPM 源码包经验假设。
原理流程
- 核对当前版本对 SPM 集成的官方说明。
- 试点工程生成二进制产物并注册为 SPM 二进制目标。
- 验证模拟器/真机链接、签名与发版流程。
代码或图示
SPM 二进制目标 → 预编译 XCFramework/framework → Xcode 链接
常见误区
- 按 Swift 源码包方式引入 KMP 产物。
- 未验证 Intel/Apple Silicon 模拟器与真机架构就纳入发布流程。
追问
- 不确定支持程度时怎么办?答:短期用 CocoaPods 或手动 XCFramework 落地;SPM 方案在试点验证通过后再切换,跟踪官方发行说明。
07.2.3.1-098 XCFramework 如何链接到 Xcode 工程?
一句话结论
把 .xcframework 加入「Frameworks, Libraries, and Embedded Content」,按目标设置嵌入与签名;真机/模拟器架构由 Xcode 按当前目标选择,更新产物后清理 DerivedData 避免链接旧二进制。
概念解释
手动集成不需要 Pod:Gradle 打包出多架构 XCFramework,拖入 Xcode 工程并加入嵌入列表。Framework 需要随 App 嵌入;纯静态库可不嵌入但需链接配置。签名设置与 Xcode 版本相关,模拟器 slice 不进入 Release 包。
原理流程
- Gradle 任务生成 XCFramework。
- 加入 Xcode 工程 Frameworks 列表并勾选 Embed。
- 编译真机与模拟器分别验证,清理缓存后复测。
代码或图示
Xcode → General → Frameworks, Libraries, and Embedded Content
→ Shared.xcframework → Embed & Sign
常见误区
- 框架只链接不嵌入,运行期 dyld 找不到库。
- 更新 KMP 产物后未清理缓存,调试到旧 framework。
追问
- 链接报错库找不到怎么排查?答:检查嵌入列表、架构覆盖、Framework 搜索路径与签名;用
lipo/架构列表核对 slice 是否包含当前目标。
07.2.3.1-099 二进制产物如何分发与缓存?
一句话结论
模块间复用走 klib 编译期库;分发给 iOS 工程走 framework/XCFramework;产物可在 CI 缓存或私有仓库管理,版本与架构清单随产物一起发布。
概念解释
KMP 工程内部:Gradle 模块依赖编译产物,klib 供 Native 模块链接。对外分发:iOS 消费 XCFramework,Android 消费本地模块或 AAR。产物分发要记录 Kotlin 版本、target 架构、构建时间与兼容范围;缓存命中错误版本会导致链接与符号问题。
原理流程
- 区分编译期复用(klib)与运行期分发(framework/XCFramework)。
- CI 按版本号产出产物并归档。
- 消费方按版本与架构清单拉取,校验后链接。
代码或图示
klib 模块间编译期复用
framework 单架构分发
XCFramework 多架构 iOS 分发
常见误区
- 把调试符号与 Release 产物混放,体积与符号信息不一致。
- 缓存未按 Kotlin/插件版本隔离,新旧产物混用。
追问
- 产物版本号怎么管理?答:与模块语义化版本一致,记录依赖的 Kotlin、AGP、CMP 版本;破坏性变更升大版本,消费方工程锁定版本更新。
07.2.3.1-100 KMP 集成常见问题清单与排查路径是什么?
一句话结论
按「编译 target → 依赖构件 → 源集边界 → 互操作导出 → 线程与生命周期」分层排查:先让各 target 编译通过,再处理运行期回调、泄漏与导出可读性问题。
概念解释
典型问题分层:编译期缺构件、API 放错源集、签名不匹配;运行期线程违规、状态竞争、回调残留;边界层泛型擦除、可空性、异常包装。排查先定位失败 target 与任务,再沿调用链回溯到源码源集与接口契约。记录问题模板:现象、target、复现路径、报错栈、涉及模块。
原理流程
- 编译失败:核对 target 列表、依赖构件、源集依赖与签名匹配。
- 运行崩溃:区分主线程违规、并发竞争、生命周期泄漏。
- 边界问题:核对头文件类型、可空性、异常映射与订阅注销。
代码或图示
编译期:缺构件 / unresolved reference / actual 缺失
运行期:主线程卡顿 / 竞态 / 野指针 / 回调残留
边界层:泛型擦除 / 可空误判 / KotlinException / 命名冲突
常见误区
- 一上来改公共代码,不先定位失败 target 与源集。
- 用加日志、重试掩盖线程与生命周期根因。
追问
- 团队如何沉淀排查经验?答:按上述分层建问题清单与检查项,纳入评审与 CI 门禁;版本敏感项在试点工程验证后再推广。
参考来源
- Kotlin Multiplatform 官方文档:KMP 工程结构、source set、target 与共享层组织总览。
- expect/actual 声明规则:expect 函数、类与 actual 匹配约束的官方说明。
- Kotlin/Native CocoaPods 集成:CocoaPods 插件配置与产物集成方式。
- Ktor Client 文档:多平台 HTTP 客户端 core API 与平台引擎说明。
- Android 官方 KMP 指南:Android 侧接入 Kotlin Multiplatform 的官方实践指引。
待整理清单
- [ ] 核对 Kotlin 2.x 各版本对 expect class 成员声明、重命名注解与 SPM 集成的最新支持范围
- [ ] 补充各多平台库(Ktor、SQLDelight、Koin、kotlinx.serialization、kotlin-test)与 Kotlin 2.x 的兼容版本矩阵
- [ ] 补充新内存模型下旧
freeze()调用的迁移要点与版本边界 - [ ] 补充 XCFramework 签名、嵌入与 Release 架构裁剪的 Xcode 版本差异细节
- [ ] 整理 Swift async/await 桥接与 Flow 订阅封装的可复用代码模板