1. Kotlin Multiplatform工程全景

Kotlin Multiplatform（简称 KMP）是 JetBrains 主导的一套跨端工程方案，它的核心主张不是“用一套 UI 打天下”，而是共享业务逻辑与数据层，按平台保留原生 UI 与平台能力。理解这一点，是理解整个课程所有技术选型的前提。KMP 通过 Kotlin 编译器把同一份 Kotlin 源码编译成多个目标平台的原生产物：Android 上是 JVM 字节码，iOS 上是 Native 二进制（经由 Kotlin/Native 与 LLVM），桌面端是 JVM 或 Native，Web 端是 JavaScript 或 Wasm，服务端则是 JVM 字节码。共享的是源码，落地的是各平台真正原生的产物，因此不存在“桥接层性能损耗”这一常见跨端痛点。

KMP 在多端的定位

在移动端，KMP 通常承担网络请求、数据模型、序列化、缓存、业务规则、状态管理等职责，UI 仍由 Jetpack Compose 与 SwiftUI 分别实现；如果希望连 UI 也共享，可以叠加 Compose Multiplatform，把 Compose 运行时编译到 iOS、桌面和 Web。在桌面端，Compose Multiplatform 可直接产出 Windows、macOS、Linux 应用。在 Web 端，Kotlin/JS 与 Kotlin/Wasm 让共享模块可以运行在浏览器中。在服务端，KMP 共享模块可以直接被 Ktor 应用复用，实现“同一份领域模型，客户端与服务端共用”，这对契约一致性帮助极大。

需要明确的是：KMP 不是“一个框架”，而是一组编译器能力、Gradle 插件与库生态的组合。它不规定你必须共享多少代码，你可以只共享一个工具函数，也可以共享整个数据层。这种渐进式采纳能力，是它区别于 Flutter、React Native 的关键工程特征。

与 Flutter、React Native 的对比

Flutter 用 Dart 编写，通过自绘引擎 Skia/Impeller 渲染 UI，UI 一致性最强，但平台原生控件与系统能力需要插件桥接，包体积与启动开销相对更高。React Native 用 JavaScript/TypeScript，通过 JSI 与原生组件通信，生态庞大、热更新成熟，但跨语言调用与线程模型在复杂场景下容易成为性能与调试难点。KMP 的取舍是：不接管 UI，不引入新的运行时桥接，直接编译为平台原生代码，代价是 UI 需要各端分别实现，团队需要具备 Kotlin 与各平台原生开发能力。

课程项目总览

本课程围绕一个名为 KmpNotes 的跨端笔记应用展开，覆盖 Android、iOS、桌面与服务端四个目标。项目采用分层结构：shared 模块承载领域模型、仓库接口、网络与持久化实现；androidApp、iosApp、desktopApp 分别承载各端 UI；server 模块复用共享模型提供 REST 接口。示例中我们会定义 Note 数据类、NoteRepository 接口，并用 Ktor Client 与 SQLDelight 在共享层实现它们，各端只负责调用与展示。

上图展示了本课程项目的整体结构：shared 模块位于中心，向四个目标平台输出各自的原生产物。Android 与 Server 共享 JVM 字节码路径，iOS 走 Kotlin/Native，Desktop 与 Web 则根据配置选择 JVM、Native 或 JS/Wasm。理解这张图，就能在后续章节中快速定位“这段代码应该写在哪一层、会被编译成什么”。

为什么选择 KMP

如果你的团队已经具备 Kotlin 与原生开发能力，且对性能、包体积、平台一致性有较高要求，KMP 是当前跨端方案中“侵入性最低”的选择。它不要求你放弃现有原生代码，可以逐模块迁移；也不要求你接受一套自绘 UI，可以继续使用各平台最成熟的 UI 框架。代价是共享层需要处理平台差异（如 expect/actual 声明、平台特定依赖），这部分正是本课程后续章节要重点解决的内容。

接下来，我们会从工程搭建开始，逐步完成 KmpNotes 的共享层、各端 UI 接入、平台差异处理与构建发布。每一章都会围绕真实可运行的代码与配置展开，确保你不仅理解概念，更能把项目真正跑起来。