罗罗编程学习记录
本页内容 展开查看

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 也跨平台,业务层、数据层、领域模型是最常见的共享部分。

原理流程

  1. Gradle 插件在 kotlin { } 块中声明需要编译的 target。
  2. 编译器为每个 target 选择对应 source set 与依赖集,独立产出目标二进制。
  3. 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 或接口注入在平台侧实现。

原理流程

  1. 先列出模块内所有类型与函数,标注依赖的 API 来源。
  2. 只依赖 Kotlin stdlib 与多平台库的部分下沉到 commonMain。
  3. 平台能力抽成 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 与中间层级源集,不能横向引用另一个平台的实现。

原理流程

  1. 公共代码与 expect 声明写在 commonMain。
  2. 平台差异在对应平台 main 中写 actual 实现。
  3. 编译某 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 独立编译。

原理流程

  1. 在 kotlin { } 块用 androidTarget()、iosArm64() 等函数声明 target。
  2. 插件为每个 target 生成对应的编译任务与源集。
  3. 打包阶段把各 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 框架等对应运行器。

原理流程

  1. 在 commonTest 写用例,断言使用 kotlin-test 的 assertEquals 等。
  2. 平台专属用例下沉到对应平台测试源集。
  3. 执行 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 架构共享它。模板还会自动配置源集依赖关系。

原理流程

  1. 插件根据已声明的 target 识别平台族。
  2. 自动生成 iosMain、macosMain 等中间源集并把架构源集挂到其下。
  3. 公共 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 只在源集内可见。

原理流程

  1. 编译 androidTarget 时,编译器按 commonMain → androidMain 顺序合并。
  2. commonMain 的公开类在 androidMain 可直接引用。
  3. 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。如果某个实现只在特定架构不同,才需要下沉到对应架构源集,绝大多数情况下差异只在真机与模拟器之间。

原理流程

  1. 声明三个 iOS target 后,模板生成 iosMain 聚合关系。
  2. iOS 公共 actual 实现写在 iosMain。
  3. 链接阶段把架构产物打成 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 语法差异。

原理流程

  1. 模块只做 JVM 库时用 jvmMain。
  2. 引入 Compose Desktop 后,桌面专属能力下沉 desktopMain。
  3. 编译 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 表达源码复用关系:父源集的公开代码对子源集可见,依赖也会传递。模板已经配好默认层级;自定义源集(如按业务分组的中间层)需要手动声明父子关系,否则编译器无法解析跨源集引用。

原理流程

  1. 在 sourceSets 块中获取源集引用。
  2. 对子源集调用 dependsOn(父源集)。
  3. 检查依赖方向无环、无横向平台依赖。

代码或图示

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 的资源机制统一管理。

原理流程

  1. 识别资源是否被所有 target 复用。
  2. 公共资源放 commonMain 资源目录,平台资源下沉平台源集。
  3. 通过 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 模块,共享层只提供可组合的能力。

原理流程

  1. 新建 KMP 库模块,声明需要的 target。
  2. 公共数据层、领域层代码入库。
  3. 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 拆分。

原理流程

  1. 试点期:一个 shared 模块覆盖网络、模型、业务规则。
  2. 出现依赖混乱或编译变慢后,识别稳定的下层能力(模型、序列化、网络)。
  3. 逐层拆分为独立 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 资源。

原理流程

  1. 编译期:源码 → 对应 target 中间表示 → 目标后端产物。
  2. 库链接:klib 在 Native 模块间复用。
  3. 分发: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 集成与手动链接都围绕该产物组织。

原理流程

  1. 各架构 target 分别编译出 framework。
  2. 打包任务把多架构 framework 合并为 .xcframework。
  3. 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。既有业务代码不需要一次性迁移。

原理流程

  1. 新建 shared KMP 模块并配置 androidTarget。
  2. 把可复用逻辑逐步移入 commonMain,平台调用留在 androidMain。
  3. 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 名作为后缀。理解任务命名有助于定位「某个平台编译失败」的任务入口。

原理流程

  1. 配置阶段插件注册各 target 任务。
  2. 执行某平台构建时,只触发对应 target 的编译与打包链。
  3. 汇总任务(如 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 可见。

原理流程

  1. 查依赖库是否提供多平台构件。
  2. 多平台依赖写进 commonMain 的 dependencies。
  3. 平台专属依赖写进对应源集的 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 插件版本必须一致,跨平台库版本之间也有兼容矩阵。

原理流程

  1. 在 [versions] 固化 Kotlin、AGP、CMP、各库版本。
  2. [libraries] 拆分 core 与平台引擎条目。
  3. 模块 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,再回查源码放在哪个源集,比全局搜索效率高。

原理流程

  1. 从报错任务名确认失败 target。
  2. 打开报错文件,判断其所在源集与引用类型的来源。
  3. 平台 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 由编译器按签名匹配到对应平台。

原理流程

  1. commonMain 写 expect 函数/类/属性声明。
  2. 各平台 main 写 actual 实现。
  3. 编译某 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 不能有 { } 实现块,也不能写表达式体。

原理流程

  1. 在 commonMain 用 expect fun 写签名。
  2. 标注可空性、泛型与返回类型。
  3. 各平台提供 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 或改变类型参数边界。

原理流程

  1. 比对 expect 与 actual 的函数签名各组成部分。
  2. 类型、泛型、返回可空性逐项对齐。
  3. 匹配通过后,编译期把调用解析到本平台实现。

代码或图示

// 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 按需调用。

原理流程

  1. expect 只保留签名。
  2. 公共默认逻辑写成 commonMain 普通函数。
  3. 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 侧声明。

原理流程

  1. commonMain 用 expect class 写类型与必要成员签名。
  2. 平台 main 提供 actual class。
  3. 编译器保证每个 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 对成员的约束比普通类严格:可空类型、平台类型映射、构造参数等都受限制。遇到表达不了的成员,应改用接口加平台实现。

原理流程

  1. 列出类需要暴露给 common 的方法与属性。
  2. 跨平台签名部分写进 expect class。
  3. 依赖平台父类或初始化形态的部分移到平台实现,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 不一致,编译器报绑定错误。

原理流程

  1. 平台 main 写 actual class。
  2. 对齐构造参数与成员签名。
  3. 平台父类、平台接口在 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。

原理流程

  1. 定义 common interface 与方法签名。
  2. 平台 main 写实现类,不使用 actual 绑定。
  3. 装配阶段把实现注入 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 限制。

原理流程

  1. commonMain 声明接口与数据模型。
  2. androidMain/iosMain 分别写实现类。
  3. 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,平台需要原生枚举映射时再做转换层。注解用于代码生成或平台元数据,不应承载业务逻辑。

原理流程

  1. 先判断该类型是否真的需要平台化。
  2. 可在 commonMain 定义的枚举/对象直接下沉公共层。
  3. 必须平台化的部分核对当前版本 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 侧。

原理流程

  1. commonMain 用 expect val 声明只读平台属性。
  2. 平台 main 提供 actual val,类型一致。
  3. 调用方通过公共属性读取,不感知实现来源。

代码或图示

// 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 调用方只按公共构造参数创建类型。

原理流程

  1. commonMain 写 expect class 与构造参数列表。
  2. actual 类用 actual constructor 对齐参数。
  3. 平台初始化逻辑在 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 代码不直接引用平台类型,映射只发生在导出边界。

原理流程

  1. commonMain 使用 Kotlin 标准类型。
  2. 导出框架时互操作层生成头文件类型映射。
  3. 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 直接报错,公共代码不感知平台分支。

原理流程

  1. common 代码面向 expect 声明编译。
  2. 每个 target 独立解析对应 actual。
  3. 签名不匹配或缺 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。

原理流程

  1. 判断实现是否对所有 iOS 架构一致。
  2. 一致时写 iosMain,由模板聚合到各架构。
  3. 不一致时按架构源集分别写 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 改成无约束,也不能把返回类型写死成具体类。泛型协变/逆变标注同样需要一致。

原理流程

  1. 在 expect 签名中写清类型参数与上界。
  2. actual 复制泛型形参列表,保持约束。
  3. 编译器校验后,调用点按 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、尺寸、占位模型),平台侧再转原生类型。

原理流程

  1. 审查 expect 签名的参数与返回类型。
  2. 平台类型替换为 common 数据模型或标识。
  3. 平台 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 定位源集,再核对签名。

原理流程

  1. 读报错中的 target 与 expect 声明位置。
  2. 检查对应平台 main 是否存在 actual、签名是否匹配。
  3. 补全实现或调整 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 的用例无法在公共测试中断言,应下沉平台测试。

原理流程

  1. 把可脱离平台的逻辑写成纯函数或接口驱动。
  2. commonTest 注入测试替身验证编排与规则。
  3. 平台行为在 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 契约。

原理流程

  1. 列出 common 调用方需要的方法与属性。
  2. 逐项写入 expect class 声明。
  3. 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 成员会受编译器约束。

原理流程

  1. common 契约只声明属性类型与读写可见性。
  2. 初始化策略(惰性、委托、延迟注入)写在 actual 类体内。
  3. 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 的能力。判断依据是变化频率与可测试性要求。

原理流程

  1. 区分:纯平台映射 vs 可替换业务能力。
  2. 映射类收敛到 expect/actual。
  3. 策略类定义 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 持有,普通接口实现同样可以。共享库不负责创建平台对象,只消费注入进来的实例;这样平台实现可替换、可测试。

原理流程

  1. common 层定义接口与依赖声明。
  2. 平台入口创建实现(expect actual 类或普通类)并注册到容器。
  3. 共享层从容器取接口实例使用。

代码或图示

// 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 直接暴露给下游重新绑定。

原理流程

  1. 上游模块把公共契约标为 public。
  2. 上游各 target 内完成 expect/actual 绑定与编译。
  3. 下游模块依赖上游产物,按导出接口调用。

代码或图示

// 上游 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 按场景逐步重构。

原理流程

  1. 查当前 Kotlin 版本官方文档对 expect class 的约束说明。
  2. 新平台能力优先定义 common 接口。
  3. 存量 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。

原理流程

  1. 查库文档与 Maven 坐标,确认多平台构件与 target 列表。
  2. 支持的库写入 commonMain 依赖。
  3. 不支持的能力用平台 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 引擎。业务层因此双端复用同一套网络编排。

原理流程

  1. commonMain 依赖 ktor-client-core 与序列化插件。
  2. 平台 main 引入对应引擎并传给客户端工厂。
  3. 共享层通过注入的 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 引擎。

原理流程

  1. 列出已声明 target 与对应引擎。
  2. 平台 main 配置引擎并构建 HttpClient。
  3. 共享层接收注入的客户端,公共请求逻辑复用。

代码或图示

// 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 仍是核心,类型安全由生成代码保证。

原理流程

  1. commonMain 写 .sq 表定义与查询语句。
  2. 编译器生成公共查询接口。
  3. 平台 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 列表,再决定公共层依赖还是平台封装。

原理流程

  1. 核对候选库是否发布多平台构件。
  2. 公共层只依赖确认支持的库。
  3. 不支持的能力在平台 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 库。日期、字节、自定义类型需要配合对应序列化器或转换层。

原理流程

  1. 数据类加 @Serializable,字段类型可序列化。
  2. commonMain 注入 Json 实例,配置忽略未知键、命名策略等。
  3. 共享层调用 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 注册子类。跨端传输时,新增子类、改判别名、去掉默认值都可能让旧客户端解码失败,需要版本兼容策略。

原理流程

  1. 定义公共继承体系与判别字段。
  2. 配置 SerializersModule 或依赖密封类内置规则。
  3. 灰度期校验新旧客户端对新旧模型的解码兼容性。

代码或图示

@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,避免重复容器与全局状态。

原理流程

  1. commonMain 定义公共模块与接口绑定。
  2. 平台 main 补充平台实现绑定。
  3. 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、全局单例跨层持有状态。

原理流程

  1. common 定义依赖接口与接收方。
  2. 平台 main 实现接口并在装配期注册。
  3. 共享层只使用接口方法,不感知实现来源。

代码或图示

// 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 构件的日志库。日志级别、标签与脱敏规则在公共层统一。

原理流程

  1. common 定义 Logger 接口与级别。
  2. 平台 main 实现并桥接本端日志通道。
  3. 共享层通过注入记录日志,敏感字段在公共层脱敏。

代码或图示

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 字符串。

原理流程

  1. common 模型使用 kotlinx-datetime 类型或时间戳。
  2. 序列化层在边界与字符串/时间戳互转。
  3. 平台 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、安全随机源、加密套件都是平台能力。纯算法(哈希校验、格式校验)可下沉公共层;密钥保管、对称/非对称加解密、证书校验在平台侧完成。共享层不应自带硬编码密钥或自研加密实现。

原理流程

  1. 区分公共规则与平台安全能力。
  2. 平台 main 实现安全接口,接入系统安全存储。
  3. 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 差异成正比,选型时要计入成本。

原理流程

  1. 评估是否有 KMP 替代库。
  2. 无替代则在 common 定义能力接口。
  3. 平台 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。

原理流程

  1. commonMain 只导入 stdlib 与多平台库包。
  2. CI 跑 android、ios、jvm、wasm 各 target 编译与测试。
  3. 非 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 目标关注打包体积。重复的工具类不应在多模块各自引入。

原理流程

  1. 拆分 core-model、core-network 等窄职责模块。
  2. 审查 common 依赖清单,移除未用库与冗余传递依赖。
  3. 对比各产物体积基线,定位体积增长来源。

代码或图示

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 使用新模型,旧迁移问题按版本核对文档。

原理流程

  1. 旧模型:对象绑定线程归属,跨线程需冻结。
  2. 新模型:取消冻结为主的限制,支持并发共享可变对象。
  3. 开发者用 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 刷新在平台入口切主线程。

原理流程

  1. 共享层用 Dispatchers.Default 执行后台挂起任务。
  2. 结果通过回调/Flow 回到平台。
  3. 平台 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 调度器的具体实现随版本演进,使用前核对文档(待确认)。

原理流程

  1. common 后台任务使用默认/后台调度器。
  2. 平台入口需要主线程时取 Dispatchers.Main。
  3. 共享层不持有主线程引用,便于测试与复用。

代码或图示

// 不推荐在 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,而不是在线程池里跑阻塞调用。跨平台公共代码不要硬编码线程数或线程池行为。

原理流程

  1. CPU 计算任务用 Default。
  2. IO 走挂起式客户端 API,不手动阻塞线程。
  3. 平台特定线程池在平台 main 封装。

代码或图示

// 推荐:挂起式请求,不阻塞线程
suspend fun load(): List<Post> = client.get("/posts").body()

常见误区

  • 在共享层起阻塞线程做文件/网络 IO,iOS 线程资源受限。
  • 假设 iOS 有与 JVM 相同的 IO 线程池容量与排队策略。

追问

  • 必须跑阻塞调用怎么办?答:下沉平台 main,在本端线程模型内封装为挂起函数;公共层不直接操作底层线程。

07.2.3.1-065 共享状态在 iOS 上有哪些线程安全要求?

一句话结论

即使新内存模型允许对象跨线程共享,共享可变状态仍需 Mutex、Actor 式封装或线程封闭;多协程并发修改同一变量会产生竞态。

概念解释

新模型取消冻结不等于自动并发安全。多个协程读写同一个可变集合或变量时,需要同步原语保护。常见风险:缓存、计数器、会话状态在后台线程被并发修改。共享层提供线程安全的数据封装,平台侧不要绕过封装直接改内部状态。

原理流程

  1. 识别跨协程共享的可变状态。
  2. 用 Mutex.withLock、单线程封闭或不可变数据保护。
  3. 对外暴露只读访问或线程安全方法。

代码或图示

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、阻塞数据库、死循环计算),问题与原生开发一致。平台入口应把任务提交到后台,结果回主线程刷新。

原理流程

  1. 排查启动与页面回调中是否存在同步阻塞调用。
  2. 共享层改为挂起式 API,后台调度执行。
  3. 平台侧在主线程只做轻量 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 不用于业务页面,防止页面销毁后回调仍访问已释放对象。

原理流程

  1. 公共层定义作用域与取消方法。
  2. 平台页面出现时启动订阅,销毁时调用取消。
  3. 协程取消后不再向平台侧发结果回调。

代码或图示

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/回调必须处理生命周期与重复回调。

原理流程

  1. 共享层声明 suspend fun。
  2. 生成框架时导出 completion handler 形态。
  3. 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 定义函数类型或单方法接口,平台桥接把闭包适配进去。回调是否在主线程、是否允许重复调用,必须在接口契约里写明,否则平台侧容易出现线程错乱与泄漏。

原理流程

  1. common 定义回调接口或函数类型。
  2. 平台桥接把 Swift 闭包适配为该类型。
  3. 共享层在确定线程上回调,平台侧按约定刷新 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,避免嵌套泛型导出。

原理流程

  1. common 定义监听器接口与订阅/取消方法。
  2. 共享层协程收集 Flow,逐帧回调接口。
  3. 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 做协程间通信,不可变数据与线程封闭作为补充。共享层封装线程安全容器,平台侧不直接操作内部可变状态。

原理流程

  1. 识别共享可变状态与通信通道。
  2. 用 Mutex 保护临界区,Channel 传递事件。
  3. 避免引入 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 在主队列派发。线程约定写进接口文档:回调线程、是否可空、是否单次。

原理流程

  1. 公共层定义后台执行方法与结果回调。
  2. 平台页面调用后在主线程接收回调。
  3. 退出页面时取消作用域与订阅。

代码或图示

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 封装为挂起函数。调试时可通过线程名/调用栈区分平台主线程与后台线程。

原理流程

  1. 协程挂起让出系统线程,恢复时由调度器选线程。
  2. 平台专用线程在平台层创建与管理。
  3. 公共层只依赖挂起式 API 与调度器抽象。

代码或图示

Kotlin 协程 → Kotlin/Native 调度器 → iOS 系统线程(主队列/后台线程)

常见误区

  • 依赖线程局部变量在协程间传递上下文。
  • 假设后台任务始终在同一个系统线程恢复。

追问

  • 平台强依赖专用线程怎么办?答:在平台 main 封装队列,提供挂起方法;公共层面向该方法调用,不接触底层线程对象。

07.2.3.1-074 长时间任务在共享层如何调度?

一句话结论

按任务归属拆分页面级与进程级作用域:页面任务跟随 ViewModel 取消,后台持久任务由平台进程级作用域持有,并支持状态持久化与中断恢复。

概念解释

上传、批量同步、导入导出等长任务不能绑死单个页面。公共层提供任务状态与进度回调,平台决定作用域生命周期。任务进度、断点状态需要持久化,避免 App 被杀后从头再来。共享层不使用全局作用域启动业务任务。

原理流程

  1. 区分任务是否随页面销毁。
  2. 页面任务挂在 ViewModel 作用域,进程任务挂在平台长生命周期作用域。
  3. 进度与断点持久化,回调按接口约定推送。

代码或图示

class UploadSession(scope: CoroutineScope) {
    fun start() { /* 进度回调 + 状态持久化 */ }
    fun cancel() { /* 释放协程与资源 */ }
}

常见误区

  • 长任务用 GlobalScope,页面退出后仍占用资源。
  • 任务状态只存内存,App 重启后无法续传。

追问

  • 任务与网络层如何配合?答:长任务内部使用挂式客户端与重试策略;取消时释放连接与临时文件,平台层负责任务记录与重新调度。

07.2.3.1-075 线程相关崩溃与竞态如何排查?

一句话结论

先按崩溃栈定位是否主线程违规或并发修改,再复核共享可变状态的同步保护;复现路径通常是多协程并发回调、页面退出后残留引用。

概念解释

典型问题:后台线程刷新 UI、并发写同一集合、回调访问已释放对象。排查顺序:崩溃线程与调用栈 → 触发路径(并发/生命周期)→ 共享状态封装是否加锁 → 订阅是否取消。线上可通过崩溃日志的线程名与回调链回溯。本地复现需增大并发或延迟抖动。

原理流程

  1. 读取崩溃栈,判断主线程违规还是状态竞争。
  2. 检查回调线程约定与订阅取消时机。
  3. 复核可变状态的锁/不可变封装,补测试用例。

代码或图示

主线程 UI 访问异常 → 回调未切主线程
ConcurrentModification / 数据错乱 → 共享集合无同步
野指针/已释放引用 → 作用域未取消、闭包强引用

常见误区

  • 只改 UI 刷新线程,不修底层并发写竞争。
  • 靠重试或延后回调规避竞态,根因仍在。

追问

  • 怎么预防?答:接口写明线程约定,共享状态封装线程安全容器,页面退出统一取消作用域;评审检查 GlobalScope、可变集合与闭包引用。

07.2.3.1-076 Kotlin/Native 生成的 Objective-C 框架结构是怎样的?

一句话结论

framework 包含编译二进制、导出头文件与资源;头文件按包名/类型生成 ObjC 接口,导出的 public 类型、函数与属性可见,internal 与 private 类型不出现。

概念解释

互操作层为 Kotlin 公共声明生成 ObjC 头文件:类映射为 ObjC 类,顶层函数挂到对应类,属性与方法生成 accessor。数据类、枚举、密封类型按规则转换。框架结构随 target 与配置变化,具体符号以生成头文件为准;不导出的类型 Swift 侧无法引用。

原理流程

  1. 编译 Kotlin 产物并链接 framework。
  2. 互操作层生成 .h 头文件与类型映射。
  3. Xcode 链接后 Swift/ObjC 按头文件调用。

代码或图示

Shared.framework/
├── Shared          二进制
├── Headers/Shared.h
└── Modules/        模块定义(按版本)

常见误区

  • 期望 internal 类型在 Swift 侧可用。
  • 把头文件里的映射类型当成 Kotlin 原始类型直接混用。

追问

  • 怎么检查导出符号是否完整?答:打开生成头文件核对类、方法与属性;缺失则调整可见性或导出注解,具体注解能力以当前版本为准(待确认)。

07.2.3.1-077 挂起函数导出为 completion handler 后参数如何排列?

一句话结论

导出方法保留原参数,末尾追加 completion 参数;回调携带结果与错误,错误映射为 Kotlin 异常对应的平台类型,具体签名以生成头文件为准。

概念解释

completion 回调通常接收结果对象与错误对象两个参数:成功时结果非空、错误为空;失败时错误非空。原参数顺序不变。Swift 侧调用要判断结果与错误分支,不能只看返回值。泛型结果在头文件中可能被擦除为基础类型或包装类。

原理流程

  1. 共享层定义 suspend 方法与结果类型。
  2. 生成框架时追加 completion 参数。
  3. 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 运行时的异常类型。平台侧需要把异常映射为可读错误模型,而不是把内部异常透传。共享层建议定义公共错误类型,在边界转换。

原理流程

  1. 公共层定义领域错误与结果包装。
  2. 需要导出的方法按规则标注 @Throws。
  3. 平台侧把 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 等,平台侧看到的是包装错误。设计上应把异常转为公共错误结果,减少平台对包装类型的依赖。

原理流程

  1. 共享层内部捕获异常并转为领域错误。
  2. 无法转换的异常沿 completion 错误分支返回。
  3. Swift 侧解析错误类型名/消息,映射为提示文案。

代码或图示

// 推荐:异常转结果
fun run(): Result<Data> = try {
    Result.success(service.call())
} catch (e: Throwable) {
    Result.failure(e.toDomainError())
}

常见误区

  • 假设 Swift 可直接 catch Kotlin 异常类型。
  • 把 KotlinException 的内部消息直接展示给用户。

追问

  • 崩溃类异常(空指针、断言)怎么办?答:在公共层防御性检查,避免运行到边界;线上崩溃监控按平台通道采集,异常类型映射在发布前对齐。

07.2.3.1-080 泛型导出有哪些限制?

一句话结论

复杂嵌套泛型、泛型方法与部分集合泛型在 ObjC 导出时被擦弱或包装;跨语言接口应使用具体 data class 结果,避免直接暴露 List<List<T>>、嵌套泛型回调。

概念解释

Objective-C 泛型表达能力有限,Kotlin/Native 导出只能映射其中一部分:外层类可带类型参数,深层嵌套与通配符常被擦除。导出可读性差时,Swift 侧拿到的是弱类型集合。工程做法是在公共层定义具体响应模型,把泛型结构拍平为字段。

原理流程

  1. 审查导出方法的参数与返回类型。
  2. 嵌套泛型在公共层封装为 data class。
  3. 生成头文件核对类型是否保留预期信息。

代码或图示

// 不推荐直接导出
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 或类型检查分支。公共层新增密封子类属于破坏性变更:旧平台代码没有对应分支。

原理流程

  1. common 定义密封层级与公共字段。
  2. 导出为基类/子类 ObjC 类型。
  3. 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 会让平台侧代码充满强转与空判断。

原理流程

  1. 优先返回元素为 data class 的列表。
  2. 字典场景定义键值模型或结构体。
  3. 头文件核对集合元素类型是否可读。

代码或图示

// 推荐:显式字段
data class UserPage(val items: List<User>, val total: Int)

常见误区

  • 导出 Map<String, Any>,平台侧无法判断取值类型。
  • 把可变集合直接暴露,外部可绕过封装修改内部状态。

追问

  • 字典数据必须跨层传怎么办?答:在公共层定义固定字段模型;动态字典只用于原始数据解析,不进入 UI 与业务边界。

07.2.3.1-083 可空类型导出后如何标注?

一句话结论

Kotlin 可空性映射为 Swift 可选/ObjC 可空标注;公共契约必须明确非空与可空字段,避免平台侧把可空值当非空解包。

概念解释

String 导出为非空,String? 导出为可选。互操作层按类型标注生成头文件可空性。字段默认值、集合空与元素空要区分:空列表不等于含空元素。平台侧误解包可选值会触发崩溃,评审与头文件核对可空标注。

原理流程

  1. common 模型明确字段可空性与默认值。
  2. 导出头文件标注 nullability。
  3. Swift 侧按可选安全解包,不强制 !。

代码或图示

data class Profile(
    val name: String,        // 非空
    val avatarUrl: String?   // 可空
)

常见误区

  • 接口返回类型写 Any?,可空性与元素类型都丢失。
  • Swift 侧对可选值强制解包,空值时崩溃。

追问

  • 后端字段缺失如何兜底?答:模型字段给默认值或可空,序列化层忽略未知键;公共层把缺失映射为领域默认值,不在平台侧做补救。

07.2.3.1-084 顶层函数与扩展函数导出到哪里?

一句话结论

顶层函数按包名生成到对应 ObjC 类/命名空间;扩展函数作为静态或包装方法导出,可读性受限;跨层 API 优先封装为类方法或接口方法。

概念解释

Kotlin 顶层函数在导出框架时聚合到生成的宿主类型上,命名受包名与文件规则影响。扩展函数不成为接收者的原生方法,而是导出为包装调用。Swift 侧调用位置与命名可能不符合习惯,工程上把业务操作收敛到公共类/接口,减少散落的顶层与扩展 API。

原理流程

  1. 公共层整理对外 API,优先类方法。
  2. 顶层/扩展方法保留在内部工具层。
  3. 生成头文件核对导出位置与命名。

代码或图示

// 对外:类方法
class SessionRepository {
    suspend fun token(): String?
}

常见误区

  • 对外能力全写成顶层扩展,Swift 侧找不到入口。
  • 包名/文件名调整后导出符号位置变化,平台调用失效。

追问

  • 工具函数如何复用?答:内部用顶层函数,对外通过公共类暴露必要方法;导出命名冲突时按版本支持的重命名注解调整(待确认)。

07.2.3.1-085 类型别名与数据类在 Swift 侧可读性如何?

一句话结论

data class 导出为带属性的 ObjC 类,可读性较好;typealias 在边界通常不保留别名语义,跨层模型应使用具名 data class 而非类型别名。

概念解释

数据类的字段导出为属性,构造与取值清晰。类型别名只是编译期别名,导出后底层类型暴露,Swift 侧看不到别名含义。嵌套类、深类型也会影响可读性。跨语言模型尽量扁平、字段具名,避免用别名表达业务含义。

原理流程

  1. 公共模型使用具名 data class。
  2. 避免 typealias 承载跨层业务类型。
  3. 头文件核对字段命名与层级。

代码或图示

// 推荐
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 冲突;导出后核对头文件。命名冲突的具体注解能力与默认后缀以官方文档为准(待确认)。

原理流程

  1. 公共 API 命名避开平台保留字与常见前缀冲突。
  2. 生成框架后检查头文件命名。
  3. 需要时使用版本支持的重命名注解。

代码或图示

// 命名带业务前缀,降低冲突概率
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 类型能力推断。

原理流程

  1. Kotlin 公共类型导出为 ObjC 接口。
  2. Swift 经桥接调用,值类型先转模型。
  3. 边界类型保持 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 对象时要检查引用链。

原理流程

  1. common 定义回调接口。
  2. iOS 桥接实现接口,内部调用 Swift 闭包。
  3. 订阅注销时释放适配器与闭包引用。

代码或图示

interface ResultCallback {
    fun onSuccess(data: String)
    fun onFailure(error: String)
}

常见误区

  • 闭包强引用页面与 Kotlin 对象,形成循环引用。
  • 页面销毁后闭包仍被调用,访问已释放 UI。

追问

  • 闭包在哪个线程被调用?答:由共享层按约定线程回调;桥接层不擅自切线程,平台侧按契约刷新 UI。

07.2.3.1-089 回调持有 Kotlin 对象会造成哪些内存问题?

一句话结论

平台闭包/适配器强引用 Kotlin 对象,而 Kotlin 侧订阅又持有回调,会形成循环引用;页面退出后未注销订阅,对象与协程无法释放。

概念解释

跨层引用链:Swift 页面 → 适配器闭包 → Kotlin 回调接口 → ViewModel → 订阅协程。任一环不释放,整链驻留。常见表现:页面反复进出后内存上涨、回调残留触发野指针。需要在页面销毁时注销订阅、断开适配器引用,并检查闭包捕获列表。

原理流程

  1. 画出页面、适配器、Kotlin 对象与协程的引用链。
  2. 页面退出调用注销/取消方法。
  3. 适配器弱引用页面,闭包不持有强引用链。

代码或图示

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 编译器自身的二进制兼容规则另按版本核对。

原理流程

  1. 列出对外公共 API 与版本承诺。
  2. 破坏性变更走大版本,保留旧接口过渡。
  3. 发布前用旧平台工程链接新框架验证。

代码或图示

兼容:新增类、新增可选方法、补默认值
破坏:删除方法、改参数类型、收紧可空性、改返回类型

常见误区

  • 认为 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 层提供。

原理流程

  1. app 模块 implementation(project(":shared"))。
  2. DI 注册共享仓库与实现。
  3. 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”。

原理流程

  1. Android 共享代码 → JVM 字节码 → dex,直接运行。
  2. 接入 C 库时:Android 走 JNI,Native 目标走 C interop。
  3. 两套绑定不混用,接口在 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 测试结果。

原理流程

  1. commonTest 写平台无关用例与断言。
  2. Gradle 按 target 生成测试任务并执行。
  3. 汇总各 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 编译失败。参数化测试、时序断言等能力按库版本支持情况选用。

原理流程

  1. commonTest 依赖 kotlin-test。
  2. 用 @Test 与 kotlin-test 断言写用例。
  3. 各 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 测试按各端原生测试框架组织。公共逻辑不应回流到平台测试重复断言。

原理流程

  1. 判断用例是否依赖平台 API 或真实环境。
  2. 依赖平台的用例下沉对应测试源集。
  3. 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 版本核对(待确认)。

原理流程

  1. 应用 CocoaPods 插件并配置 pod 元数据。
  2. 声明 iOS 框架 target 与外部 pod 依赖。
  3. 执行 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 源码包经验假设。

原理流程

  1. 核对当前版本对 SPM 集成的官方说明。
  2. 试点工程生成二进制产物并注册为 SPM 二进制目标。
  3. 验证模拟器/真机链接、签名与发版流程。

代码或图示

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 包。

原理流程

  1. Gradle 任务生成 XCFramework。
  2. 加入 Xcode 工程 Frameworks 列表并勾选 Embed。
  3. 编译真机与模拟器分别验证,清理缓存后复测。

代码或图示

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 架构、构建时间与兼容范围;缓存命中错误版本会导致链接与符号问题。

原理流程

  1. 区分编译期复用(klib)与运行期分发(framework/XCFramework)。
  2. CI 按版本号产出产物并归档。
  3. 消费方按版本与架构清单拉取,校验后链接。

代码或图示

klib            模块间编译期复用
framework       单架构分发
XCFramework     多架构 iOS 分发

常见误区

  • 把调试符号与 Release 产物混放,体积与符号信息不一致。
  • 缓存未按 Kotlin/插件版本隔离,新旧产物混用。

追问

  • 产物版本号怎么管理?答:与模块语义化版本一致,记录依赖的 Kotlin、AGP、CMP 版本;破坏性变更升大版本,消费方工程锁定版本更新。

07.2.3.1-100 KMP 集成常见问题清单与排查路径是什么?

一句话结论

按「编译 target → 依赖构件 → 源集边界 → 互操作导出 → 线程与生命周期」分层排查:先让各 target 编译通过,再处理运行期回调、泄漏与导出可读性问题。

概念解释

典型问题分层:编译期缺构件、API 放错源集、签名不匹配;运行期线程违规、状态竞争、回调残留;边界层泛型擦除、可空性、异常包装。排查先定位失败 target 与任务,再沿调用链回溯到源码源集与接口契约。记录问题模板:现象、target、复现路径、报错栈、涉及模块。

原理流程

  1. 编译失败:核对 target 列表、依赖构件、源集依赖与签名匹配。
  2. 运行崩溃:区分主线程违规、并发竞争、生命周期泄漏。
  3. 边界问题:核对头文件类型、可空性、异常映射与订阅注销。

代码或图示

编译期:缺构件 / unresolved reference / actual 缺失
运行期:主线程卡顿 / 竞态 / 野指针 / 回调残留
边界层:泛型擦除 / 可空误判 / KotlinException / 命名冲突

常见误区

  • 一上来改公共代码,不先定位失败 target 与源集。
  • 用加日志、重试掩盖线程与生命周期根因。

追问

  • 团队如何沉淀排查经验?答:按上述分层建问题清单与检查项,纳入评审与 CI 门禁;版本敏感项在试点工程验证后再推广。

参考来源

待整理清单

  • [ ] 核对 Kotlin 2.x 各版本对 expect class 成员声明、重命名注解与 SPM 集成的最新支持范围
  • [ ] 补充各多平台库(Ktor、SQLDelight、Koin、kotlinx.serialization、kotlin-test)与 Kotlin 2.x 的兼容版本矩阵
  • [ ] 补充新内存模型下旧 freeze() 调用的迁移要点与版本边界
  • [ ] 补充 XCFramework 签名、嵌入与 Release 架构裁剪的 Xcode 版本差异细节
  • [ ] 整理 Swift async/await 桥接与 Flow 订阅封装的可复用代码模板