Kotlin Multiplatform实战：基于agentic-awesome-skills的共享业务逻辑架构

1. 为什么我又把 KMM 捡起来了先说结论Kotlin Multiplatform后面统一简称 KMM这两年被讨论得越来越多但真正把它落到“共享业务逻辑”这个层面、而不是只拿来炫技写个 Hello World 的项目其实没那么多。我这次重新捡起 KMM是因为手上有一个多端产品——Android、iOS、外加一个桌面端的小工具——三端各自维护一套几乎一模一样的业务规则改一个折扣计算逻辑要同步改三遍测试还得写三遍时间一长必然出现“三端行为不一致”的经典事故。标题里提到的agentic-awesome-skills你可以把它理解成一个“技能/能力聚合”的参考项目骨架它把一堆可复用的能力模块技能注册、调度、状态流转、规则匹配之类组织在一起天然就适合做跨端共享。我拿它当参照物不是为了照抄它的代码而是借它的分层思路来验证一件事——KMM 到底能不能把“业务逻辑”这一层干净地抽出来共享同时让各端的 UI 和平台特性各玩各的。这篇文章适合谁看如果你已经会写 Kotlin做过 Android对 iOS 或桌面端有一点了解并且正在被“多端逻辑重复”折磨那这篇就是写给你的。如果你完全没碰过 Kotlin建议先把 Kotlin 基础语法过一遍再回来不然读起来会有点吃力。全文我会围绕“共享业务逻辑架构”这个核心把选型理由、目录结构、关键代码、踩坑记录都摊开讲尽量让你能直接抄作业。我先把这次实战的整体目标摆出来免得后面跑偏把纯业务逻辑规则、计算、状态机、数据模型抽到一个 KMM 共享模块里各端只保留UI 层 平台特有 API 调用共享层要能独立单元测试不依赖任何一端运行时平台差异比如时间、存储、日志通过expect/actual或依赖注入解决最终三端跑同一套业务规则行为一致。这五条是我判断“这次 KMM 用得对不对”的标准后面每个技术决策我都会回到这五条上解释。2. 架构选型为什么是共享逻辑而不是共享 UI2.1 共享 UI 和共享逻辑差别到底在哪很多人第一次接触 KMM第一反应是“那我是不是可以一套 UI 跑三端”。技术上可以Compose Multiplatform 现在也能覆盖 iOS 和桌面但我这次刻意没有共享 UI原因很现实。共享 UI 的收益是“写一次界面三端用”但代价是一旦某个平台要做原生体验比如 iOS 的侧滑返回、Android 的 Material You 动态取色你就得在共享 UI 里塞一堆平台判断最后共享层变得又臭又长比各写各的还难维护。而共享业务逻辑不一样业务逻辑本来就是“与界面无关”的它天然适合被抽出来。我打个生活化的比方共享 UI 像是三家人共用一套装修图纸谁想改个墙色都得开会共享业务逻辑像是三家人共用一本“家规”至于家里怎么摆设各管各的。家规统一了行为就不会乱摆设不同反而各有各的味道。所以我的架构分层是这样的层级是否共享职责典型内容UI 层否界面渲染、交互Compose、SwiftUI、平台控件业务逻辑层是规则、计算、状态用例、状态机、校验数据模型层是数据结构定义data class、枚举、密封类平台适配层部分平台 API 封装时间、存储、日志、网络基础设施层否平台运行时系统 API、第三方 SDK这张表是我整个项目的“宪法”任何代码要进来先问它属于哪一层。属于共享层的就必须保证不 import 任何平台特有的包。2.2 为什么参照 agentic-awesome-skills 的分层agentic-awesome-skills这类“技能聚合”项目的核心特征是能力被注册成一个个独立单元由调度器统一编排。这个思路放到 KMM 里特别合适因为跨端共享最怕的就是“逻辑全糊在一个大类里”。我借鉴了它三个设计点第一能力注册制。每个业务能力比如“计算折扣”“校验库存”“生成推荐”都是一个独立单元通过统一接口注册到调度器。这样新增能力不用改调度器符合开闭原则。第二状态与行为分离。状态用不可变数据类表示行为用纯函数或用例类表示。不可变数据在跨端传递时特别省心不用担心某端偷偷改了引用导致另一端行为异常。第三依赖显式注入。调度器需要什么依赖全部通过构造函数传入而不是在内部 new。这样在测试时可以直接塞假实现不需要真实平台环境。提示不要一上来就追求“大而全”的调度框架。我第一版就是过度设计写了个带优先级、带重试、带熔断的调度器结果业务代码还没写几行调度器先写了一千行。后来砍到只剩“注册 按顺序执行”反而好用。2.3 共享模块的边界怎么划边界划不清是 KMM 项目翻车的头号原因。我的经验是能纯函数化的一律进共享层一旦碰到平台 API立刻下沉到适配层。举个具体例子。“判断当前是否在促销时段”这个逻辑拆开看有两部分一是“当前时间”这是平台相关的各端取时间方式不同二是“时间是否落在促销区间内”这是纯逻辑。所以我的做法是共享层定义一个TimeProvider接口各端实现它共享层的促销判断逻辑只依赖这个接口不关心时间从哪来。这样拆的好处是促销判断逻辑可以在 JVM 上直接跑单元测试我传一个假的时间进去就能测出各种边界情况完全不需要启动 Android 模拟器或 iOS 模拟器。测试速度从“分钟级”降到“毫秒级”这个体验提升是实打实的。3. 项目骨架搭建从零到能跑3.1 目录结构设计我这次用的目录结构是踩了几次坑之后稳定下来的版本。核心原则是共享代码集中在一个模块平台代码各自独立测试代码跟着共享代码走。project-root/ ├── shared/ # KMM 共享模块 │ ├── src/ │ │ ├── commonMain/ # 共享业务逻辑核心 │ │ │ └── kotlin/ │ │ │ ├── model/ # 数据模型 │ │ │ ├── skill/ # 能力单元 │ │ │ ├── dispatcher/ # 调度器 │ │ │ └── platform/ # expect 声明 │ │ ├── commonTest/ # 共享层单元测试 │ │ ├── androidMain/ # Android actual 实现 │ │ ├── iosMain/ # iOS actual 实现 │ │ └── jvmMain/ # 桌面 actual 实现 │ └── build.gradle.kts ├── androidApp/ # Android 应用 ├── iosApp/ # iOS 应用 └── desktopApp/ # 桌面应用这里有个细节值得说commonTest是 KMM 里最值钱的部分。因为共享逻辑的测试只写一遍三端都受益。我现在的习惯是共享层代码的测试覆盖率必须高于 80%平台层反而可以松一点因为平台层大多是“胶水代码”逻辑很薄。3.2 Gradle 配置的关键参数KMM 的 Gradle 配置是新手最容易卡住的地方。我把关键部分拆出来讲参数为什么这么设我都会说明。// shared/build.gradle.kts kotlin { androidTarget { compilations.all { kotlinOptions.jvmTarget 17 } } iosX64() iosArm64() iosSimulatorArm64() jvm(desktop) sourceSets { val commonMain by getting { dependencies { implementation(org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0) implementation(org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3) } } val commonTest by getting { dependencies { implementation(kotlin(test)) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0) } } } }几个参数的解释jvmTarget 17Android 端现在主流是 JDK 17设低了会有兼容警告设高了部分老设备工具链跟不上。17 是当前比较稳的选择。iosX64 / iosArm64 / iosSimulatorArm64这三个分别对应 Intel 模拟器、真机、Apple Silicon 模拟器。三个都要声明否则在 M 系列芯片的 Mac 上跑模拟器会报找不到目标。jvm(desktop)桌面端我复用了 JVM target这样桌面应用可以直接依赖共享模块不用额外配置。kotlinx-coroutines-test这个一定要加共享层里如果有挂起函数测试时需要用runTest没有这个库跑不起来。注意kotlinx-serialization的版本要和 Kotlin 版本匹配。我遇到过 Kotlin 1.9.x 配 serialization 1.5.x 导致编译期报错的情况后来统一升到 1.6.3 才正常。版本对齐这件事KMM 比纯 Android 更敏感因为涉及多个 target。3.3 expect/actual 的正确打开方式expect/actual是 KMM 处理平台差异的核心机制。但我要泼一盆冷水能不用就不用。每多一个 expect/actual就多一份三端都要维护的实现维护成本是乘三的。我的判断标准是只有当“这个能力确实无法用纯逻辑表达且三端实现差异很大”时才用 expect/actual。比如日志、时间、文件路径这些适合。而像“字符串格式化”这种Kotlin 标准库已经跨平台了根本不需要 expect/actual。以时间为例共享层这样声明// commonMain/platform/TimeProvider.kt expect object TimeProvider { fun nowMillis(): Long }Android 端实现// androidMain/platform/TimeProvider.kt actual object TimeProvider { actual fun nowMillis(): Long System.currentTimeMillis() }iOS 端实现// iosMain/platform/TimeProvider.kt import platform.Foundation.NSDate import platform.Foundation.timeIntervalSince1970 actual object TimeProvider { actual fun nowMillis(): Long (NSDate().timeIntervalSince1970 * 1000).toLong() }桌面端实现// jvmMain/platform/TimeProvider.kt actual object TimeProvider { actual fun nowMillis(): Long System.currentTimeMillis() }看起来很简单对吧但这里有个坑expect/actual 的签名必须完全一致包括返回类型、参数名。我有一次在 expect 里写fun now(): Long在 actual 里写成fun nowMillis(): Long编译报错信息非常隐晦找了半天才发现是名字不一致。另一个经验是优先用依赖注入替代 expect/actual。比如TimeProvider其实可以定义成一个普通接口在应用启动时注入具体实现。这样共享层连 expect 都不用写测试时注入假实现也更方便。我现在大部分场景都用注入只有极少数“全局单例性质”的东西才用 expect/actual。4. 核心业务逻辑的共享实现4.1 数据模型不可变是底线共享层的数据模型我全部用不可变data class。原因前面提过跨端传递时不可变数据最安全。而且 Kotlin 的data class自带equals、hashCode、copy在状态比较和更新时特别方便。// commonMain/model/Skill.kt data class Skill( val id: String, val name: String, val category: SkillCategory, val baseScore: Int, val tags: ListString emptyList() ) enum class SkillCategory { COMBAT, SUPPORT, UTILITY, PASSIVE }这里tags给了默认值emptyList()是为了让调用方在不需要标签时可以省略这个参数。这种小设计在跨端 API 里很实用能减少各端的样板代码。状态模型我用密封类表示因为状态往往是“有限几种情况之一”密封类配合when表达式能强制编译器检查穷尽性// commonMain/model/SkillState.kt sealed class SkillState { data object Idle : SkillState() data class Ready(val skill: Skill, val cooldownRemaining: Long) : SkillState() data class Cooling(val skill: Skill, val remainingMillis: Long) : SkillState() data class Disabled(val reason: String) : SkillState() }data object是 Kotlin 1.9 引入的比普通object多了toString和equals的合理实现。如果你的 Kotlin 版本低于 1.9用普通object也行但记得手动处理相等性。4.2 能力单元把业务拆成可注册的 Skill参照agentic-awesome-skills的注册制思路我把每个业务能力定义成一个SkillHandler// commonMain/skill/SkillHandler.kt interface SkillHandler { val id: String fun canHandle(context: SkillContext): Boolean suspend fun execute(context: SkillContext): SkillResult }三个方法各有讲究id唯一标识调度器用它来查找和去重。canHandle判断当前上下文是否适用这个能力。这是“条件匹配”的入口比如“只有在战斗状态下才能触发攻击技能”。execute真正执行返回结果。用suspend是因为业务逻辑里经常有异步操作读数据库、调网络共享层统一用协程处理。SkillContext是上下文携带执行所需的所有信息// commonMain/skill/SkillContext.kt data class SkillContext( val actorId: String, val targetId: String?, val currentState: SkillState, val timestamp: Long, val attributes: MapString, Int emptyMap() )attributes用Map而不是固定字段是为了让上下文可扩展。新增一种属性时不用改SkillContext的定义各端也不用重新编译。这种“用 Map 换灵活性”的取舍在跨端共享里很常见因为改一次共享模型三端都要跟着动。4.3 调度器编排能力的核心调度器是整个共享层的心脏。它的职责很简单按顺序找到能处理的能力执行返回结果。我刻意没做复杂的优先级和并发因为业务上暂时不需要过早优化只会增加维护负担。// commonMain/dispatcher/SkillDispatcher.kt class SkillDispatcher( private val handlers: ListSkillHandler, private val logger: Logger ) { suspend fun dispatch(context: SkillContext): SkillResult { logger.log(dispatch start, actor${context.actorId}) val handler handlers.firstOrNull { it.canHandle(context) } ?: return SkillResult.NoHandler return try { val result handler.execute(context) logger.log(dispatch done, handler${handler.id}) result } catch (e: Exception) { logger.log(dispatch error: ${e.message}) SkillResult.Failure(e.message ?: unknown) } } }Logger也是共享层定义的接口各端注入实现。这样调度器本身不依赖任何平台日志 API测试时可以注入一个“把日志收集到列表里”的假实现方便断言。SkillResult用密封类表示各种结果// commonMain/skill/SkillResult.kt sealed class SkillResult { data class Success(val output: MapString, Int) : SkillResult() data class Failure(val reason: String) : SkillResult() data object NoHandler : SkillResult() data object Skipped : SkillResult() }这里Success的output用MapString, Int是为了让不同能力返回不同结构的结果而调度器不用关心具体结构。各端拿到结果后自己决定怎么展示。4.4 一个完整的业务能力示例光看接口太抽象我写一个具体的“冷却检查”能力把前面所有东西串起来// commonMain/skill/handler/CooldownCheckHandler.kt class CooldownCheckHandler( private val timeProvider: TimeProvider ) : SkillHandler { override val id: String cooldown_check override fun canHandle(context: SkillContext): Boolean { return context.currentState is SkillState.Cooling } override suspend fun execute(context: SkillContext): SkillResult { val state context.currentState as SkillState.Cooling val elapsed timeProvider.nowMillis() - context.timestamp val remaining state.remainingMillis - elapsed return if (remaining 0) { SkillResult.Success(mapOf(cooldown_ready to 1)) } else { SkillResult.Success(mapOf(cooldown_remaining to remaining.toInt())) } } }注意这里timeProvider是通过构造函数注入的不是直接调TimeProvider.nowMillis()。这样测试时我可以传一个固定时间的假实现精确控制“经过了多少毫秒”从而测试各种边界。这个能力在 Android、iOS、桌面三端跑的是完全相同的代码。三端唯一不同的是TimeProvider的实现而那个实现只有一行。这就是共享业务逻辑的威力——把复杂逻辑集中在一处把平台差异压缩到最小。5. 各端接入与平台适配5.1 Android 端接入Android 端接入 KMM 相对最顺因为都是 Kotlin/JVM 生态。在androidApp的build.gradle.kts里加依赖dependencies { implementation(project(:shared)) }然后在 Application 或 ViewModel 里组装依赖class SkillViewModel( private val dispatcher: SkillDispatcher ) : ViewModel() { fun triggerSkill(context: SkillContext) { viewModelScope.launch { val result dispatcher.dispatch(context) _uiState.value result.toUiState() } } }toUiState()是 Android 端自己的扩展函数把共享层的SkillResult转成 UI 状态。这个转换逻辑是平台特有的所以放在 Android 端不进共享层。Android 端有个坑协程调度器。共享层的suspend函数默认在调用方的调度器上执行。如果 Android 端在Dispatchers.Main上调用而共享层里有耗时计算就会卡主线程。我的做法是在共享层的耗时操作里显式withContext(Dispatchers.Default)而不是依赖调用方。这样三端行为一致不会因为某端忘了切线程而出问题。5.2 iOS 端接入iOS 端接入 KMM核心是把共享模块编译成 iOS 能用的 framework。在shared/build.gradle.kts里配置kotlin { listOf(iosX64(), iosArm64(), iosSimulatorArm64()).forEach { target - target.binaries.framework { baseName Shared isStatic true } } }isStatic true表示生成静态 framework链接进 App 后体积更小启动也快一点。代价是每次改共享代码都要重新编译 framework增量编译速度不如动态库。这个取舍看项目阶段开发期可以用动态库加快迭代发布时切静态库。iOS 端调用共享代码是通过生成的 Objective-C 头文件。Kotlin 的suspend函数在 iOS 侧会变成带 completion handler 的方法// iosApp/ContentView.swift let dispatcher SkillDispatcher(handlers: [...], logger: ...) dispatcher.dispatch(context: context) { result, error in if let result result { // 处理结果 } }这里有个体验问题Kotlin 的密封类在 Swift 里会变成普通类when表达式的穷尽性检查在 Swift 侧就没了。所以我在共享层尽量把结果“扁平化”减少 iOS 侧的判断复杂度。比如SkillResult在 iOS 侧我会提供一个isSuccess的辅助属性让 Swift 代码写起来简单点。提示iOS 端调试共享代码时Xcode 的断点默认进不了 Kotlin 代码。需要在 Xcode 里配置 Kotlin 的调试符号或者用println打日志。我一般先用日志定位问题确认是共享层的问题后再用 IDE 的 Kotlin 调试器单独调试共享模块。5.3 桌面端接入桌面端我用的 JVM target接入最简单直接依赖共享模块就行。桌面端的价值在于快速验证改完共享逻辑跑一下桌面端就能看到效果不用等 Android 编译或 iOS 打包。我现在的开发流程是共享逻辑先在桌面端验证没问题了再上 Android 和 iOS。桌面端的TimeProvider和 Android 一样用System.currentTimeMillis()因为都是 JVM。这里其实可以合并——如果两个 target 的实现完全一样可以在 Gradle 里配置共享 source set减少重复代码。但为了清晰我这次还是分开写了因为将来桌面端可能换成别的时间源。5.4 平台适配层的设计原则平台适配层我总结了三条原则都是踩坑换来的第一适配层要薄。适配层的代码应该只有“转发”和“转换”不应该有业务逻辑。一旦发现适配层里出现了if判断业务规则说明这段逻辑该下沉到共享层。第二适配层要可替换。所有适配层实现都通过接口注入不要在共享层里直接引用具体实现。这样测试时能替换将来换平台也能替换。第三适配层要少。每多一个适配点就多三份实现。我现在的项目里适配层只有时间、日志、存储三个接口其他全部用纯逻辑或标准库解决。6. 测试策略与常见问题排查6.1 共享层测试怎么写共享层的测试是整个项目性价比最高的部分。我以冷却检查为例// commonTest/skill/CooldownCheckHandlerTest.kt class CooldownCheckHandlerTest { private val fakeTime FakeTimeProvider(1000L) private val handler CooldownCheckHandler(fakeTime) Test fun cooldown ready when elapsed exceeds remaining() runTest { val state SkillState.Cooling(skill mockSkill, remainingMillis 500L) val context SkillContext( actorId a1, targetId null, currentState state, timestamp 0L ) fakeTime.setNow(600L) val result handler.execute(context) assertTrue(result is SkillResult.Success) assertEquals(1, (result as SkillResult.Success).output[cooldown_ready]) } }FakeTimeProvider是测试专用的假实现可以任意设置当前时间。这样我就能精确测试“刚好到点”“差一毫秒”“超时很久”等各种边界而不需要真的等。runTest来自kotlinx-coroutines-test它会自动跳过delay让测试瞬间完成。这个库在共享层测试里几乎是必备的。6.2 常见问题速查表我把这次实战中遇到的问题整理成表方便你对照排查问题现象可能原因排查思路解决方法iOS 编译找不到 frameworkGradle 未配置 iOS target检查 build.gradle.kts补全 iosX64/iosArm64/iosSimulatorArm64expect/actual 编译报错签名不一致逐字对比 expect 和 actual保证返回类型、参数名完全一致共享层测试跑不起来缺少 coroutines-test检查 commonTest 依赖加 kotlinx-coroutines-testAndroid 主线程卡顿耗时逻辑在 Main 调度器用 Profiler 看线程共享层内显式 withContext(Default)iOS 侧拿不到密封类子类型Kotlin 密封类映射问题打印实际类型共享层提供辅助判断属性版本升级后编译失败Kotlin 与库版本不匹配查官方兼容性矩阵统一升级到匹配版本共享层引用了平台 API边界划错搜索 import 平台包下沉到适配层用接口注入6.3 几个我踩过的深坑坑一协程作用域泄漏。共享层里我一开始用了GlobalScope结果测试时协程在后台跑测试结束了它还没结束导致偶发失败。后来全部改成由调用方传入CoroutineScope测试时用TestScope问题消失。共享层永远不要自己创建全局作用域这是铁律。坑二序列化版本不一致。共享层用kotlinx-serialization序列化数据Android 端和 iOS 端各自依赖了不同版本的序列化库导致反序列化时字段对不上。解决方法是把序列化库的版本在共享模块里统一管理各端通过api而不是implementation传递依赖。坑三iOS 侧内存管理。Kotlin/Native 的内存模型和 JVM 不同早期版本有严格的对象冻结规则。虽然现在新内存模型已经放宽了但在 iOS 侧持有共享层对象时还是要注意生命周期。我的做法是共享层对象尽量无状态有状态的部分由各端自己管理。坑四调试信息丢失。Release 构建时共享层的堆栈信息会被混淆或裁剪导致崩溃日志看不懂。需要在各端配置保留共享层的符号信息Android 端在 ProGuard 规则里加 keep 规则iOS 端保留 dSYM。注意KMM 的编译错误信息有时候很隐晦尤其是涉及多 target 时。我的经验是遇到看不懂的编译错误先执行./gradlew clean再重新编译能解决一半的“玄学问题”。剩下的一半去官方 issue 区搜错误关键词基本都能找到答案。7. 性能与体积的实测数据光说架构好没用得看实际数据。我在一个中等规模的项目上做了对比测试共享层代码约 3000 行包含 15 个业务能力单元。编译时间方面首次全量编译含三端大约 4 分钟增量编译只改共享层大约 40 秒。这个速度可以接受但如果共享层代码量再翻倍增量编译可能会到 1 分钟以上。所以我的建议是共享模块不要无限膨胀如果某个业务领域特别复杂可以考虑拆成多个共享模块按需依赖。包体积方面Android 端引入共享模块后APK 增大约 800KBRelease 混淆后。iOS 端 framework 约 2.5MB静态链接后实际增量约 1.2MB。桌面端因为本来就是 JVM增量可以忽略。这个体积代价换来的是三端逻辑一致和测试复用我认为非常划算。运行时性能方面共享层的纯逻辑计算和原生代码没有明显差异因为 Kotlin/Native 编译后就是机器码。唯一需要注意的是跨语言调用边界Android 端是 JVM 内调用几乎无开销iOS 端是 Kotlin/Native 和 Swift 之间调用频繁的细粒度调用会有一些开销。我的做法是减少跨边界调用次数把多次小调用合并成一次大调用比如批量处理而不是逐条处理。8. 这套架构后续还能怎么扩展这套架构跑通之后我发现它的扩展性比预想的好。几个我打算继续做的方向一是把能力单元做成插件化。现在能力单元是编译期注册的将来可以做成运行时动态加载这样新增业务能力不用重新发版。当然这会带来安全性和稳定性的考量需要谨慎设计。二是共享层接入更多端。现在有 Android、iOS、桌面三端将来如果要做 Web 端Kotlin/JS 也能复用同一套共享逻辑。这意味着业务规则真正做到了“一次编写处处运行”。三是把测试用例也共享。现在共享层的测试是共享的但各端的 UI 测试还是各写各的。将来可以考虑用统一的测试 DSL 描述测试场景各端用各自的测试框架执行进一步减少重复。四是性能监控下沉。把关键业务逻辑的耗时统计放到共享层各端统一上报这样能横向对比三端的性能差异快速定位是共享逻辑的问题还是平台实现的问题。我个人在实际操作中的体会是KMM 最大的价值不在于“省了多少代码”而在于强制你把业务逻辑想清楚。因为要共享你就必须把逻辑从平台细节里剥离出来这个过程本身就会让代码质量提升一个档次。那些原本糊在 Activity 或 ViewController 里的业务规则被逼着抽出来之后你会发现它们其实可以写得更清晰、更可测。最后再分享一个小技巧如果你刚开始尝试 KMM不要一上来就改造整个项目。先挑一个最独立、最纯粹的业务逻辑比如某个计算规则或校验逻辑抽到共享层跑通三端感受一下流程。等这套流程顺了再逐步扩大共享范围。我见过太多人一上来就想“全盘 KMM 化”结果卡在配置和兼容性上最后放弃。小步快跑才是 KMM 落地的正确姿势。