Ohhnews

分类导航

$ cd ..
Jetbrains Blog原文

Kotlin Multiplatform 更新默认项目结构

#kotlin multiplatform#软件架构#gradle#移动开发#工程配置

我们正在更新 Kotlin Multiplatform 项目的默认项目结构，旨在赋予模块更清晰的职责，使其更好地符合其他构建系统和框架的惯例，并反映 Android Gradle Plugin 9.0 的变更。

您将在我们的工具所生成的新项目中、官方文档中以及 Kotlin Multiplatform 的示例中看到这种项目结构。

这些变更已在 KMP 向导中上线，无论是在您的 IDE 中（需安装 Kotlin Multiplatform 插件），还是在 kmp.jetbrains.com 上均已生效。我们也在同步更新示例项目和其他学习材料，以匹配这一新结构。您可以参考 kotlinconf-app、KMP-App-Template 或 RSS Reader。

若要在 IntelliJ IDEA 中获得对 AGP 9.0 的支持，请更新至 2026.1.2 或更高版本，并使用最新版本的 Android 插件。

本文将解释我们所做的变更、变更原因以及如何更新现有项目。

发生了什么变化

在之前的结构中，大多数项目都有一个 composeApp Gradle 模块，它既包含一个 Kotlin Multiplatform 库，又充当一个或多个平台的应用程序，包含了入口点和其他相关配置。

[LOADING...]

在“项目”（Project）视图中，它看起来是这样的：

[LOADING...]

我们新的默认结构包含一个 shared 模块，其职责非常明确：它是一个仅包含共享代码的 Kotlin Multiplatform 库。然后，对于您希望在共享库代码之上构建可运行应用程序的每个平台，您将拥有独立的应用程序模块，如 androidApp、desktopApp 和 webApp。

[LOADING...]

新结构在“项目”视图中如下所示：

[LOADING...]

我们为何进行这些更改

旧结构中的 composeApp 模块承担了多种职责。因此，它包含了大量的配置，包括针对所有平台的特定打包细节。这使得很难区分哪些部分是在配置 Kotlin Multiplatform 库，哪些部分是在配置应用程序本身。

如果您选择不在客户端平台共享 UI（例如，为 iOS 应用程序使用 SwiftUI），旧结构会在 composeApp 之外包含一个额外的 shared 模块。这是模块结构上的重大变化，但仅在特定配置下才会出现。

在 iOS 应用方面也存在不对称性。由于它们需要一个消费共享代码的 Xcode 项目，因此 iOS 应用程序已经位于单独的 iosApp 文件夹中，而其他构建在共享代码之上的应用程序则都集中在 composeApp 中。

Android Gradle Plugin 9.0 要求 Android 应用程序的入口点必须与共享代码位于不同的模块中，因为它不再支持在多平台模块中应用 Android 应用程序 Gradle 插件。

最后，我们之前为基于 Gradle 的项目和基于 Amper 的项目采用了不同的结构。虽然 Gradle 支持在单个模块中配置多个应用程序，但 Amper 允许每个模块仅有一个产品，因此基于 Amper 的项目已经为每个应用程序使用了独立的模块。

新结构的目标

基于以上几点，我们制定了新结构，旨在实现以下目标：

  • 为项目提供初始设置，确保每个模块都有明确的职责和单一目的。项目中任何代码或构建配置应放置在何处，都应始终清晰明了。
  • 保持结构尽可能一致，以适配向导允许的不同配置：不同的目标平台组合、是否包含服务器应用程序，以及客户端选择原生 UI 还是共享 UI。
  • 使其易于进一步模块化，以便根据需要从单个多平台模块扩展为多个模块。

适配其他配置

上述示例展示了 Compose Multiplatform 应用程序的新项目结构，该程序在 Android、iOS、桌面和 Web 平台之间共享 UI。在其他配置中，结构将根据需要进行调整，且改动极小。

包含原生 UI 的配置

Kotlin Multiplatform 支持在共享 Kotlin 代码之上使用原生 UI。例如，您可以选择在 iOS 应用中使用 SwiftUI，同时在其他平台使用 Compose Multiplatform。在这种情况下，您将编写由所有平台使用的共享业务逻辑代码，以及仅由特定平台使用的共享 UI 代码。

在这种配置中，新结构将拥有两个共享模块，而不是一个：sharedLogic 和 sharedUI。sharedLogic 被所有应用程序消费且不包含 Compose 依赖项，而 sharedUI 仅被那些使用 Compose Multiplatform 作为 UI 的应用程序消费。

[LOADING...]

决定将共享代码写在哪个模块中依然很简单：如果所有平台（包括使用原生 UI 实现的平台）都要使用它，就应放在 sharedLogic 中；如果只有使用 Compose Multiplatform 的平台需要该代码，则应放在 sharedUI 中。

包含服务器的配置

对于同时针对服务器端 Kotlin 的项目，新结构增加了一个 server 模块，并将所有客户端模块移入一个嵌套的 app 文件夹中。项目根目录下的额外 core 模块允许您在服务器端和客户端代码之间共享代码，例如模型和验证逻辑。

[LOADING...]

更新现有项目

虽然我们正在更改新创建项目的默认结构，但现有项目并不强制要求采用完全相同的结构。如果您希望将现有项目迁移到此新默认结构，可以使用迁移指南，其中展示了如何为每个入口点引入新模块。

请注意，与 Android Gradle Plugin 9.0 相关的变更对于所有针对 Android 的现有多平台项目是强制性的。您可以在此博客文章中详细了解这些变更以及如何更新您的项目。

若要在 IntelliJ IDEA 中获得对 AGP 9.0 的支持，请更新至 2026.1.2 或更高版本，并使用最新版本的 Android 插件。

立即开始使用 KMP

要使用更新后的结构创建新项目，请前往 kmp.new 或在您的 IDE 中使用 Kotlin Multiplatform 向导（在安装了 Kotlin Multiplatform 插件 的 IntelliJ IDEA 和 Android Studio 中均可用）。

如果您想查看新结构的实际应用示例，请参考 kotlinconf-app、KMP-App-Template 或 RSS Reader。