AI时代移动端开发：KMP新的默认项目结构从单一composeApp拆成“shared库+各平台app模块”，改一个Android打包配置要在build.gradle.kts里翻半天找不到哪段是共用的、哪段是平台的，这种“工程结构演进”带来的认知负担，到底是在为多平台复用付必要代价，还是KMP在DX上仍然落后Flutter一个身位？

1. 问题的提出：一次“找不到配置”的工程现场

设想一个典型场景：团队使用 KMP 官方模板创建项目，结构为 composeApp/ 单模块，Android 与 iOS 目标共享同一份 build.gradle.kts。某天需要为 Android 单独配置签名、namespace、minSdk 与打包变体（flavor），开发者打开根目录与模块目录下的多个 build.gradle.kts，发现 android { } 块与 kotlin { } 块交错，平台专属配置与共享配置混在同一文件的不同位置，缺乏显式的“这是共享的、那是平台的”语义标记。

这正是用户描述的“翻半天”体验。它表面上是文件定位问题，实质上是配置语义缺乏分层：Gradle 脚本是命令式 DSL，它的可读性依赖于约定（convention）而非结构强制。当项目从单模块拆为多模块，约定被打破，开发者必须在大脑中重建“哪个脚本作用于哪个模块、哪个源集属于哪个目标”的映射关系。这种重建成本，就是本文要量化的“认知负担”。

关键判断：如果一次配置修改需要在 3 个以上文件中跳转、且跳转路径无法从命名直接推断，那么该结构的认知负担已经超过了它带来的复用收益——至少在工具抽象补齐之前如此。

本文不满足于“多模块就是更复杂”的直觉结论，而是要把这个问题拆成可验证的子问题：模块拆分的边界依据是什么？Gradle 配置能否被收敛到可预测的位置？构建与索引成本如何随模块数变化？KMP 与 Flutter 的 DX 差距究竟体现在哪一层？只有把这些问题分开回答，“必要代价”与“工具落后”的二分才有意义。

2. 背景与概念界定：KMP、源集与工程结构的演进史

2.1 KMP 的准确定义

Kotlin Multiplatform（KMP）是 JetBrains 主导的跨平台技术方案，其核心机制是：将 Kotlin 代码编译为多个目标平台的原生产物（JVM/Android、Native/iOS、JS、Wasm 等），通过 expect/actual 机制声明平台差异，通过源集（source set）组织共享代码与平台代码的可见性边界。与 Flutter 的“自绘 UI + 单一 Dart 运行时”不同，KMP 不强制统一 UI 层，Compose Multiplatform 只是其 UI 选项之一。

源集是理解本文全部讨论的钥匙。一个源集是一组源文件及其编译配置的集合，KMP 的 Gradle 插件会为每个目标（target）自动创建对应源集，并建立层级（hierarchy）关系：commonMain 位于层级顶端，其声明对所有目标可见；androidMain、iosMain 等位于下层。本文评述：源集层级本质上是依赖可见性的偏序结构，它把“代码能否跨平台复用”编码进了目录结构，这是 KMP 相对其他方案的结构性优势，但也意味着目录即契约——一旦目录被拆分到多个模块，契约的阅读成本随之上升。

2.2 默认模板的结构演进

根据 Kotlin 官方文档与 JetBrains 博客的公开记录，KMP 项目模板大致经历了三个阶段：早期以 shared + 平台工程（Android Studio 工程与 Xcode 工程并列）为主；随后 Compose Multiplatform 推广期，官方模板倾向于单一 composeApp 模块承载 UI 与逻辑；2024 年之后，随着 kotlin.multiplatform 插件对 Android 目标的支持方式调整（Android Gradle Plugin 与 KMP 插件的协作方式变化），以及多模块构建缓存的成熟，模板重新回到“共享库 + 平台宿主”的分层结构。

本文评述：这一演进不是简单的“来回折腾”，而是在“上手成本”与“长期可维护性”之间做帕累托前沿的移动。单模块降低了入门门槛，却把平台差异压缩进了同一份脚本；分层结构恢复了边界，却把配置成本转嫁给了开发者。判断哪种更好，取决于项目生命周期长度与团队规模，而非模板本身。

2.3 相关研究脉络

跨平台开发的工程复杂度研究并非新话题。学术界对“构建系统复杂度”的度量可追溯到软件产品线工程（SPLE）中的变体管理研究，其核心指标包括变体数量、配置空间大小与特征交互数。工业界方面，Gradle 官方文档对多项目构建的配置阶段（configuration phase）与执行阶段（execution phase）做了明确区分，并指出配置阶段的开销随项目数近似线性增长；Kotlin 官方文档则详细描述了源集层级与 dependsOn 关系的推导规则。这些公开资料构成了本文分析框架的事实基础。

需要说明的是，本文引用的社区调查数据（如开发者满意度、构建时长自报数据）属于自报样本，存在选择偏差，仅用于趋势参考，不作为精确度量。凡涉及具体数值的推断，本文均标注来源类型（官方文档 / 社区调查 / 模拟测算）。

3. 分析主线：认知负担 = 结构复杂度 ÷ 工具抽象能力

为了让“必要代价 vs 工具落后”的争论可检验，本文提出一个简化的分析模型：

其中：模块数是可测量的结构指标；配置分散度指同一语义的配置（如签名、SDK 版本）分布在多少个文件中；源集映射数指开发者需要在大脑中维护的“源集→目标→模块”三元关系数量；配置抽象度指工具是否提供约定插件、版本目录、类型安全访问器等机制；反馈闭环速度指从修改配置到获得错误/成功反馈的时间。

本文评述：这个模型的价值不在于精确计算，而在于把争论从“感觉复杂”转为可干预的变量。如果认知负担高，我们可以选择降低分子（减少模块、收敛配置、简化映射）或提高分母（引入约定插件、版本目录、更快的构建反馈）。KMP 结构演进提高了分子中的模块数，但同时也提供了提高分母的工具——问题在于这些工具是否被默认启用、是否易用。

由此得到本文的核心命题：KMP 的结构演进本身是合理的，用户的“翻半天”体验主要来自分母不足——即配置抽象与反馈闭环没有随结构复杂度同步升级。这不是“多平台复用的必要代价”，而是“工具链成熟度的时间差”。

4. 模块拓扑解剖：shared 与 app 的职责边界

4.1 典型拓扑

当前默认结构可抽象为三层：根项目（root）负责插件版本与仓库声明；shared 模块承载 commonMain 业务逻辑与 expect 声明；androidApp、iosApp 等宿主模块负责平台入口、打包配置与平台专属依赖。Compose Multiplatform 场景下，UI 代码通常也放在 shared 的 commonMain，平台模块只保留 MainActivity 或 UIViewController 的薄壳。

project-root/
├── settings.gradle.kts          // 模块注册与仓库
├── build.gradle.kts             // 根插件声明（apply false）
├── gradle/libs.versions.toml    // 版本目录（Version Catalog）
├── shared/
│   ├── build.gradle.kts         // KMP 插件 + 目标 + 源集依赖
│   └── src/
│       ├── commonMain/kotlin/   // 共享逻辑与 UI
│       ├── androidMain/kotlin/  // actual 实现
│       └── iosMain/kotlin/      // actual 实现
├── androidApp/
│   ├── build.gradle.kts         // AGP + android{} + 打包配置
│   └── src/main/AndroidManifest.xml
└── iosApp/
    └── iosApp.xcodeproj         // Xcode 工程，链接 shared 产物

这个拓扑的合理性在于：平台宿主模块是“可变点”，shared 是“共性核”。Android 的签名、渠道、minSdk 属于可变点，理应只在 androidApp 中出现；业务规则与数据模型属于共性核，理应只在 shared 中出现。问题在于，现实项目里“可变点”会渗透：例如 shared 的 Android 目标也需要 compileSdk，于是同一语义在两个模块各写一遍，产生“配置漂移”。

4.2 配置漂移的成因与检测

配置漂移（configuration drift）指同一语义的配置在不同位置取值不一致。在 KMP 项目中，典型漂移点包括：compileSdk、minSdk、targetSdk、JVM target、Kotlin 编译器参数、依赖版本。漂移的后果不是立即报错，而是在特定组合下才暴露的运行时或链接错误，排查成本远高于配置本身。

检测方法可以工程化：编写一个 Gradle 任务，遍历所有子项目，读取 android.compileSdk 等属性并断言一致。这类“架构守护”任务在多模块项目中是低成本高回报的投入。笔者建议将其纳入 CI，作为合并前检查项。

5. Gradle 配置分层：从“翻半天”到“一眼定位”

5.1 为什么“翻半天”是结构问题而非记忆问题

Gradle 的 Kotlin DSL 是类型安全的，但类型安全不等于语义可见。一个 build.gradle.kts 文件可以同时包含插件声明、仓库、依赖、任务配置与平台专属块，它们共享同一作用域，没有视觉分隔。当项目只有一个模块时，开发者可以通过“文件即项目”的直觉定位；当项目有 N 个模块时，同一语义的配置可能出现在任意一个文件中，定位依赖记忆而非结构。

本文评述：解决之道不是“记住更多”，而是让配置位置可从命名与目录推断。这需要三个机制：版本目录统一版本、约定插件统一语义、目录约定统一归属。三者合起来，把“翻文件”变成“按图索骥”。

5.2 机制一：版本目录（Version Catalog）

Gradle 官方文档将版本目录定义为集中声明依赖版本与依赖坐标的机制，默认文件为 gradle/libs.versions.toml。其价值在于把“版本”从 N 个脚本收敛到 1 个文件，消除版本漂移，并提供类型安全的访问器（如 libs.androidx.core.ktx）。

[versions]
kotlin = "2.1.0"
agp = "8.7.3"
composeMultiplatform = "1.7.3"

[libraries]
androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidxCore" }
kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
androidApplication = { id = "com.android.application", version.ref = "agp" }

需要提醒的是，版本目录只解决“版本在哪”，不解决“配置在哪”。它降低的是版本漂移，不是结构分散。把它当作万能药是常见误解。

5.3 机制二：约定插件（Convention Plugins）

约定插件是 Gradle 官方推荐的复用构建逻辑的方式：把重复的插件应用、依赖声明、编译参数抽取为 buildSrc 或 build-logic 中的插件类，各模块通过 plugins { id("...") } 应用。对 KMP 项目，可以分别定义 kmp-shared 与 android-app 两个约定插件，把“共享模块该长什么样”与“Android 宿主该长什么样”编码为可执行约定。

// build-logic/src/main/kotlin/kmp-shared.gradle.kts
plugins {
    id("org.jetbrains.kotlin.multiplatform")
}

kotlin {
    androidTarget()
    iosX64(); iosArm64(); iosSimulatorArm64()
    sourceSets {
        commonMain.dependencies {
            implementation(libs.kotlinx.coroutines.core)
        }
    }
}

android {
    namespace = "com.example.shared"
    compileSdk = libs.versions.compileSdk.get().toInt()
    defaultConfig { minSdk = libs.versions.minSdk.get().toInt() }
}

本文评述：约定插件把“配置分散度”从 N 个模块降到 1 个插件，是分母端最有效的杠杆。它的代价是初次搭建成本与学习曲线，但这是一次性投入。对于模块数 ≥ 3 的项目，投入产出比通常为正。

5.4 机制三：目录与命名约定

即使有版本目录与约定插件，开发者仍需知道“改签名去哪”。这需要命名约定：平台专属配置只允许出现在 *-app 模块，共享配置只允许出现在 shared 模块，跨模块共享的编译参数只允许出现在约定插件。把这条规则写进 README 与代码评审清单，比任何文档都有效。

6. 构建性能与增量编译：结构演进的隐性账单

6.1 配置阶段与执行阶段的成本结构

Gradle 官方文档明确将构建分为初始化、配置、执行三个阶段。多模块项目在配置阶段需要为每个项目求值构建脚本，成本随项目数增长。KMP 项目还叠加了源集层级推导与目标配置，配置阶段开销更显著。这意味着：模块拆分不仅增加阅读成本，也增加每次构建的固定开销。

缓解手段包括：启用配置缓存（Configuration Cache）、使用 org.gradle.parallel、避免在配置阶段做 I/O。配置缓存对 KMP 项目的兼容性在近两年持续改善，但仍需注意插件是否声明了不兼容的 API。笔者建议在 CI 中开启配置缓存并观察命中率，作为结构健康度指标之一。

6.2 增量编译的边界

Kotlin 编译器的增量编译以模块为粒度建立依赖图。当 shared 的 commonMain 发生变更，所有依赖它的平台编译任务都可能失效。这是共享代码的固有成本：复用度越高，变更传播面越大。它解释了为什么“拆模块”有时反而让全量构建变慢——模块边界切断了部分增量传播，但也增加了跨模块任务调度。

本文评述：这里存在一个常被忽略的权衡——模块拆分的收益主要在“并行构建”与“变更隔离”，成本在“配置开销”与“跨模块依赖解析”。对于小型项目，单模块的增量编译可能更快；对于大型项目，多模块的并行收益才会显现。因此“拆不拆”应基于项目规模与团队并行度，而非教条。

6.3 构建缓存的复用条件

Gradle 构建缓存（Build Cache）以任务输入输出哈希为键复用结果。多模块项目的缓存命中率取决于任务输入的稳定性：版本目录与约定插件让输入更稳定，从而提升命中率；而脚本中内联的随机值（如时间戳、动态版本）会破坏命中。因此，配置收敛不仅是可读性投资，也是构建性能投资。

7. IDE 索引与导航：认知负担的第二个来源

“翻半天”不只发生在编辑器里，也发生在 IDE 的导航中。IntelliJ IDEA / Android Studio 对 KMP 项目的索引需要处理多目标、多源集的符号可见性。当同一符号在 commonMain 与 androidMain 都有声明（expect/actual），IDE 的“跳转到定义”可能给出多个候选，增加判断成本。

此外，Gradle 同步（sync）在多模块 KMP 项目中耗时更长，同步失败时的错误信息往往指向脚本行号而非语义原因，进一步拉长反馈闭环。本文评述：IDE 体验是 DX 的核心组成，但它受制于构建系统的语义表达能力。如果 Gradle 模型不能清晰表达“共享/平台”二分，IDE 也难以提供精准导航。这是 KMP 与 Flutter 在 DX 上的关键差异之一——后者由单一工具链端到端控制，前者需要在 Gradle、Kotlin 插件、AGP、Xcode 之间协调。

8. KMP 与 Flutter 的 DX 模型对比

8.1 两种 DX 模型的本质差异

Flutter 的 DX 模型是单一工具链、单一语言、单一构建入口：flutter run 封装了构建、部署、热重载，平台差异被引擎层吸收。KMP 的 DX 模型是多工具链协作：Gradle 管 Android 与共享代码，Xcode 管 iOS 宿主，Kotlin/Native 负责 iOS 侧编译。前者的认知负担集中在“学习 Flutter 约定”，后者的认知负担集中在“协调多个系统的边界”。

本文评述：把 KMP 与 Flutter 的 DX 差距简单归结为“落后一个身位”并不准确。二者在不同的设计目标下做了不同的取舍：Flutter 用“控制一切”换取 DX 一致性，KMP 用“融入原生生态”换取互操作深度。前者在“快速迭代 UI”场景占优，后者在“复用原生能力、渐进迁移”场景占优。DX 差距是真实的，但它不是同一赛道上的落后，而是不同约束下的不同最优点。

8.2 差距正在收敛的证据

近两年 KMP 在 DX 侧的改进包括：Compose Multiplatform 的热重载支持、Kotlin 2.x 编译器对多平台的支持增强、Android Studio 对 KMP 项目模板与同步的优化、以及社区约定插件（如 Now in Android 风格的 build-logic）的普及。这些改进的方向一致：把配置抽象从“开发者手工维护”转向“工具默认提供”。这正是本文模型中提高分母的路径。

9. 可操作路径：五步完成配置收敛与结构治理

步骤一：建立配置归属清单

先盘点当前所有构建脚本中的配置项，按“共享/平台/版本”三类归档，形成一张归属表（可参考第 5.4 节表格）。这一步不需要改代码，只需要读代码并记录。产出物是一份 Markdown 文档，作为后续重构的依据。

步骤二：引入版本目录

把依赖坐标与版本迁移到 gradle/libs.versions.toml，替换脚本中的内联版本。迁移后运行一次全量构建，确认无版本冲突。此步骤风险低、收益直接（消除版本漂移）。

步骤三：抽取约定插件

创建 build-logic 模块，定义 kmp-shared 与 android-app 两个约定插件。把第 5.3 节的示例作为起点，逐模块替换原有脚本。每替换一个模块，运行该模块的构建任务验证。建议按“shared → androidApp → iosApp”的顺序推进，先易后难。

步骤四：添加架构守护任务

编写 Gradle 任务校验配置一致性（如所有模块的 compileSdk 相同、禁止在 shared 中出现签名配置）。将任务挂到 check 生命周期，纳入 CI。这一步把“约定”从文档变成可执行检查，防止漂移回潮。

步骤五：度量并迭代

记录重构前后的关键指标：配置阶段耗时、全量构建耗时、增量构建耗时、配置缓存命中率、CI 失败率。用数据判断收敛是否有效，而不是凭感觉。若配置阶段耗时未降，检查是否有插件在配置阶段做重活；若增量构建变慢，检查模块边界是否切得过细。

操作提示：重构期间保持“一次只改一类配置”，每步可回滚。多模块构建的重构风险主要来自隐式依赖，建议在每步后运行一次 ./gradlew build --dry-run 检查任务图是否符合预期。

10. 关键数据与案例：公开资料中的量化证据

10.1 官方文档中的结构性事实

Gradle 官方文档指出，配置缓存可以显著减少配置阶段重复求值；Kotlin 官方文档说明源集层级由目标声明自动推导，开发者可通过 applyDefaultHierarchyTemplate 控制。这些是“工具已提供抽象能力”的直接证据，说明分母端并非空白。

10.2 社区调查的趋势数据

JetBrains 开发者生态调查与 Stack Overflow 开发者调查长期跟踪跨平台技术的采用率与满意度。需要强调：这些调查为自报数据，样本与口径每年变化，不能直接比较绝对值。可用的趋势是：KMP 的采用率与“愿意继续使用”比例在近年呈上升态势，而“构建配置复杂”是社区反馈中的高频痛点之一。本文评述：这两条趋势并不矛盾——采用率上升说明收益被认可，配置痛点说明分母端仍有改进空间。

10.3 模拟测算：模块数对配置负担的影响

为说明量级，本文做一个模拟测算（非实测）：假设单模块时定位一次配置平均需查看 1 个文件、耗时 30 秒；拆为 4 个模块且无约定插件时，同一语义配置可能出现在 4 个文件中，定位需查看 2—3 个文件、耗时 60—90 秒；引入版本目录与约定插件后，定位回到 1—2 个文件、耗时 30—45 秒。该测算仅用于说明“分子增大、分母补足”的相对关系，不代表任何真实项目的绝对耗时。

11. 局限、边界条件与反例

本文的分析框架有三点局限。其一，认知负担难以直接测量，本文用“文件数 × 定位耗时”作为代理指标，代理与真实负担之间存在偏差。其二，模拟测算不构成实证，真实项目的耗时受团队熟悉度、IDE 版本、硬件影响极大。其三，本文主要讨论 Android 与 iOS 双目标场景，Web/Wasm/Desktop 目标的加入会改变拓扑与成本结构。

反例同样重要：对于生命周期短、团队规模小、平台差异大的项目，单模块 composeApp 可能仍是更优选择——它的配置分散度低，上手快，过早拆分反而增加负担。本文评述：结构没有绝对优劣，只有与项目约束的匹配度。把“默认模板”当作“最佳实践”是另一种认知陷阱。

12. 结论与展望：结构演进是净收益，DX 差距在收敛

回到开篇的问题：这种认知负担是“必要代价”还是“DX 落后”？本文的结论是：结构演进本身是净收益，负担的可感知程度取决于工具抽象是否同步补齐。KMP 从单模块回到分层结构，恢复了平台边界与复用粒度，这是多平台工程化的合理方向；但默认模板没有强制启用版本目录与约定插件，导致配置分散度上升而抽象度未跟上，于是“翻半天”成为普遍体验。

与 Flutter 相比，KMP 的 DX 差距真实存在，但性质不同：Flutter 以“控制全栈”换取一致性，KMP 以“融入原生”换取互操作深度。前者在 UI 迭代效率上领先，后者在原生能力复用与渐进迁移上占优。随着 Compose Multiplatform 热重载、Kotlin 编译器与 IDE 支持的持续改进，KMP 的 DX 正在向“工具默认提供抽象”的方向收敛。

展望未来，笔者认为三个方向值得关注：其一，KMP 模板是否会将约定插件作为默认生成物，这将直接决定新项目的起点负担；其二，配置缓存与增量编译对多目标项目的兼容性，这决定结构演进的实际性能账单；其三，IDE 对 expect/actual 的导航语义，这决定日常开发的认知摩擦。三者中任意一项的突破，都会显著改变本文模型中的分母。

🔒 复制本站文章内容需登录并达到 L3。当前：未登录