使用 Ktor 和 SQLDelight 创建多平台应用
本教程使用 IntelliJ IDEA,但你也可以在 Android Studio 中跟随操作——这两个 IDE 共享相同的核心功能和 Kotlin Multiplatform 支持。
本教程演示了如何使用 IntelliJ IDEA 通过 Kotlin Multiplatform 为 iOS 和 Android 创建高级移动应用程序。 该应用程序将:
- 使用 Ktor 和
kotlinx.serialization通过互联网从公开的 Launch Library 获取数据。 - 使用 SQLDelight 将数据保存在本地数据库中。
- 显示太空火箭发射列表,附带发射日期、结果以及详细的发射说明。
- 使用 Koin 提供平台特定的数据库驱动程序。
该应用程序将包含一个具有 iOS 和 Android 平台共享代码的模块。业务逻辑和数据访问层仅在共享模块中实现一次,而两个应用程序的 UI 都将采用原生实现。

你可以在我们的 GitHub 仓库中找到模板项目以及最终应用程序的源代码。
创建项目
在 IntelliJ IDEA 中,选择 File | New | Project。
在左侧面板中,选择 Kotlin Multiplatform(在 Android Studio 中,该模板位于 New Project 向导的 Generic 选项卡下)。
在 New Project 窗口中指定以下字段:
- Name:SpaceTutorial
- Project ID:com.jetbrains.spacetutorial
选择 Android 和 iOS 目标。
对于 iOS,选择 Do not share UI 选项。你将为这两个平台分别实现原生 UI。
指定完所有字段和目标后,点击 Create。

添加 Gradle 依赖项
要将多平台库添加到共享模块中,请在模块的 build.gradle.kts 文件中,将依赖项指令(implementation)添加到相关源集的 dependencies {} 块中。
kotlinx.serialization 和 SQLDelight 库还需要额外的配置。
在 gradle/libs.versions.toml 文件的版本目录中更改或添加行,以反映所有必要的依赖项:
在
[versions]块中,检查 AGP 版本并添加其余版本:[versions] {...}
toml[versions] agp = "9.0.1" material3 = "1.11.0-alpha07" # ... coroutinesVersion = "1.11.0" dateTimeVersion = "0.8.0" koin = "4.2.2" ktor = "3.5.2" sqlDelight = "2.3.2"在
[libraries]块中,添加以下库引用:[libraries] {...}
[libraries] ... koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" } koin-androidx-compose = { module = "io.insert-koin:koin-androidx-compose", version.ref = "koin" } kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutinesVersion" } kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "dateTimeVersion" } ktor-client-android = { module = "io.ktor:ktor-client-android", version.ref = "ktor" } ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" } ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" } ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" } ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" } sqldelight-android-driver = { module = "app.cash.sqldelight:android-driver", version.ref = "sqlDelight" } sqldelight-native-driver = { module = "app.cash.sqldelight:native-driver", version.ref = "sqlDelight" } sqldelight-runtime = { module = "app.cash.sqldelight:runtime", version.ref = "sqlDelight" }在
[plugins]块中,指定所需的 Gradle 插件:toml[plugins] # ... kotlinxSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" } sqldelight = { id = "app.cash.sqldelight", version.ref = "sqlDelight" }版本目录更新完成后,系统会提示你重新同步项目。 点击 Sync Gradle Changes 按钮同步 Gradle 文件:

在
sharedLogic/build.gradle.kts文件的最开头,将以下行添加到plugins {}块中:kotlinplugins { // ... alias(libs.plugins.kotlinxSerialization) alias(libs.plugins.sqldelight) }公共源集需要每个库的核心构件,以及用于使用
kotlinx.serialization的 Ktor 序列化功能。 iOS 和 Android 源集还需要 SQLDelight 和 Ktor 的平台驱动程序。在同一个
sharedLogic/build.gradle.kts文件中,添加所有必需的依赖项:kotlinkotlin { // ... sourceSets { commonMain.dependencies { implementation(libs.kotlinx.coroutines.core) implementation(libs.ktor.client.core) implementation(libs.ktor.client.content.negotiation) implementation(libs.ktor.serialization.kotlinx.json) implementation(libs.sqldelight.runtime) implementation(libs.kotlinx.datetime) implementation(libs.koin.core) } androidMain.dependencies { implementation(libs.ktor.client.android) implementation(libs.sqldelight.android.driver) } iosMain.dependencies { implementation(libs.ktor.client.darwin) implementation(libs.sqldelight.native.driver) } } }指定依赖项后,再次点击 Sync Gradle Changes 按钮以更新 Gradle 文件。
Gradle 同步完成后,项目配置即告完成,你可以开始编写代码了。
有关多平台依赖项的深入指南,请参阅依赖 Kotlin Multiplatform 库。
创建应用程序数据模型
教程应用将包含公共的 SpaceSDK 类,作为网络和缓存服务的门面。 应用程序数据模型将包含三个实体类,分别包含:
- 发射的基本信息
- 任务徽章图片的链接
- 与发射相关的文章 URL
在本教程结束时,并非所有这些数据都会呈现在 UI 中。 我们使用该数据模型来演示序列化。 不过,你可以随意使用链接和徽章图片,将示例扩展得更加丰富!
创建必要的数据类:
在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial目录下,创建entity包,然后在该包内创建Entity.kt文件。为基本实体声明所有数据类:
kotlin
每个可序列化类都必须标记有 @Serializable 注解。除非你在注解实参中显式传递对序列化器的引用,否则 kotlinx.serialization 插件会自动为 @Serializable 类生成默认序列化器。
@SerialName 注解允许你重新定义字段名称,这有助于在数据类中使用更易读的标识符来访问属性。
配置 SQLDelight 并实现缓存逻辑
SQLDelight 库允许你从 SQL 查询生成类型安全的 Kotlin 数据库 API。在编译期间,生成器会验证 SQL 查询并将其转换为可在共享模块中使用的 Kotlin 代码。
配置 SQLDelight
SQLDelight 依赖项已经包含在项目中。 要配置该库,请打开 sharedLogic/build.gradle.kts 文件并在末尾添加 sqldelight {} 块。 该块包含数据库及其参数的列表:
sqldelight {
databases {
create("AppDatabase") {
packageName.set("com.jetbrains.spacetutorial.cache")
}
}
}packageName 参数保存生成的 Kotlin 源代码的包名。
根据提示同步 Gradle 项目文件,或者双击 Shift 键并搜索 Sync All Gradle, Swift Package Manager projects 操作。
建议安装官方的 SQLDelight 插件以处理 .sq 文件。
生成数据库 API
首先,创建包含所有必需 SQL 查询的 .sq 文件。默认情况下,SQLDelight 插件会在源集的 sqldelight 文件夹中查找 .sq 文件:
在
sharedLogic/src/commonMain目录下,创建一个新的sqldelight目录。在
sqldelight目录内,创建一个名为com/jetbrains/spacetutorial/cache的新目录,为包创建嵌套目录。在
cache目录内,创建AppDatabase.sq文件(与你在build.gradle.kts文件中指定的数据库名称相同)。 应用程序的所有 SQL 查询都将存储在该文件中。数据库将包含一个存有发射相关数据的表。 将以下代码添加到
AppDatabase.sq文件中以创建该表并定义几个稍后会用到的函数:sqlimport kotlin.Boolean; CREATE TABLE Launch ( flightNumber TEXT NOT NULL, missionName TEXT NOT NULL, launchDateUTC TEXT NOT NULL, imageSmall TEXT NOT NULL, imageLarge TEXT NOT NULL, statusId INTEGER NOT NULL, statusName TEXT NOT NULL, statusDescription TEXT NOT NULL ); insertLaunch: INSERT INTO Launch(flightNumber, missionName, launchDateUTC, imageSmall, imageLarge, statusId, statusName, statusDescription) VALUES(?, ?, ?, ?, ?, ?, ?, ?); removeAllLaunches: DELETE FROM Launch; selectAllLaunchesInfo: SELECT Launch.* FROM Launch;生成对应的
AppDatabase接口(稍后你将使用数据库驱动程序对其进行初始化)。 为此,在项目的根目录下的终端中运行以下命令:shell./gradlew generateCommonMainAppDatabaseInterface生成的 Kotlin 代码将存储在
sharedLogic/build/generated/sqldelight目录中。
为平台专属数据库驱动程序创建工厂
要初始化 AppDatabase 接口,需要向其传递一个 SqlDriver 实例。 SQLDelight 提供了多种平台专属的 SQLite 驱动程序实现,因此你需要为每个平台分别创建这些实例。
虽然可以通过 expected 和 actual 接口来实现这一点,但在本项目中,你将使用 Koin 来体验 Kotlin Multiplatform 中的依赖项注入。
为数据库驱动程序创建一个接口。为此,在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial/目录下,创建cache包。在
cache包内创建DatabaseDriverFactory接口:kotlinpackage com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver interface DatabaseDriverFactory { fun createDriver(): SqlDriver }为 Android 创建实现该接口的类:在
sharedLogic/src/androidMain/kotlin目录下,创建com.jetbrains.spacetutorial.cache包,然后在其中创建AndroidDatabaseDriverFactory.kt文件。在 Android 上,SQLite 驱动程序由
AndroidSqliteDriver类实现。在DatabaseDriverFactory.kt文件中,将数据库信息和上下文引用传递给AndroidSqliteDriver类构造函数:kotlinpackage com.jetbrains.spacetutorial.cache import android.content.Context import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.android.AndroidSqliteDriver class AndroidDatabaseDriverFactory(private val context: Context) : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return AndroidSqliteDriver(AppDatabase.Schema, context, "launch.db") } }对于 iOS,在
shared/src/iosMain/kotlin/com/jetbrains/spacetutorial/目录下,创建cache包。在
cache包内创建DatabaseDriverFactory.kt文件并添加以下代码:kotlinpackage com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.native.NativeSqliteDriver class IOSDatabaseDriverFactory : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return NativeSqliteDriver(AppDatabase.Schema, "launch.db") } }
稍后你将在项目的平台专属部分中使用这些工厂。
实现缓存
到目前为止,你已经添加了用于平台数据库驱动程序的工厂以及用于执行数据库操作的 AppDatabase 接口。 现在,创建一个 Database 类,它将包装 AppDatabase 接口并包含缓存逻辑。
在公共源集
sharedLogic/src/commonMain/kotlin的com.jetbrains.spacetutorial.cache包中创建一个新的Database类。它将包含两个平台通用的逻辑。为了向
AppDatabase提供驱动程序,请将抽象的DatabaseDriverFactory实例传递给Database类的构造函数:kotlinpackage com.jetbrains.spacetutorial.cache internal class Database(databaseDriverFactory: DatabaseDriverFactory) { private val database = AppDatabase(databaseDriverFactory.createDriver()) private val dbQuery = database.appDatabaseQueries }该类的可见性设置为 internal,这意味着它只能在多平台模块内部访问。
在
Database类中,实现一些数据处理操作。 首先,创建getAllLaunches()函数以返回所有火箭发射的列表。mapLaunchSelecting()函数用于将数据库查询结果映射为RocketLaunch对象:internal fun getAllLaunches() {...}
kotlinimport com.jetbrains.spacetutorial.entity.Image import com.jetbrains.spacetutorial.entity.LaunchStatus import com.jetbrains.spacetutorial.entity.RocketLaunch internal class Database(databaseDriverFactory: DatabaseDriverFactory) { private val database = AppDatabase(databaseDriverFactory.createDriver()) private val dbQuery = database.appDatabaseQueries internal fun getAllLaunches(): List<RocketLaunch> { return dbQuery.selectAllLaunchesInfo(::mapLaunchSelecting).executeAsList() } private fun mapLaunchSelecting( flightNumber: String, missionName: String, launchDateUTC: String, imageSmall: String, imageLarge: String, statusId: Long, statusName: String, statusDescription: String ): RocketLaunch { return RocketLaunch( id = flightNumber, missionName = missionName, launchDateUTC = launchDateUTC, image = Image( small = imageSmall, large = imageLarge ), status = LaunchStatus( id = statusId.toInt(), name = statusName, description = statusDescription ) ) } }添加
clearAndCreateLaunches()函数以清空数据库并插入新数据:kotlininternal class Database(databaseDriverFactory: DatabaseDriverFactory) { // ... internal fun clearAndCreateLaunches(launches: List<RocketLaunch>) { dbQuery.transaction { dbQuery.removeAllLaunches() launches.forEach { launch -> dbQuery.insertLaunch( flightNumber = launch.id, missionName = launch.missionName, launchDateUTC = launch.launchDateUTC, imageSmall = launch.image.small, imageLarge = launch.image.large, statusId = launch.status.id.toLong(), statusName = launch.status.name, statusDescription = launch.status.description, ) } } } }
实现 API 服务
为了通过互联网获取数据,你将使用 Launch Library 公开 API,并通过单个方法从 /2.3.0/launches 端点检索所有发射的列表。
创建一个将应用程序连接到 API 的类:
在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial/目录下,创建network包。在
network目录内,创建SpaceApi类:kotlinpackage com.jetbrains.spacetutorial.network import io.ktor.client.HttpClient import io.ktor.client.plugins.contentnegotiation.ContentNegotiation import io.ktor.serialization.kotlinx.json.json import kotlinx.serialization.json.Json class SpaceApi { private val httpClient = HttpClient { install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true useAlternativeNames = false }) } } }该类负责执行网络请求并将 JSON 响应反序列化为
com.jetbrains.spacetutorial.entity包中的实体。 KtorHttpClient实例初始化并存储httpClient属性。此代码使用
ContentNegotiationKtor 插件来反序列化GET请求的结果。该插件将请求和响应有效负载作为 JSON 处理,并根据需要进行序列化和反序列化。声明返回火箭发射列表的数据获取函数:
kotlinimport com.jetbrains.spacetutorial.entity.RocketLaunch import com.jetbrains.spacetutorial.entity.LaunchListResponse import io.ktor.client.request.get import io.ktor.client.call.body class SpaceApi { // ... suspend fun getAllLaunches(): List<RocketLaunch> { return (httpClient.get("https://lldev.thespacedevs.com/2.3.0/launches/previous/?mode=list&format=json").body() as LaunchListResponse).results } }
getAllLaunches 函数具有 suspend 修饰符,因为它包含对挂起函数 HttpClient.get() 的调用。 HttpClient.get() 函数包含一个通过网络获取数据的异步操作,只能从协程或其他挂起函数中调用。网络请求将在 HTTP 客户端的线程池中执行。
发送 GET 请求的 URL 作为实参传递给 get() 函数。
构建 SDK
你的 iOS 和 Android 应用程序将通过共享模块与航天 API 进行通信,共享模块将提供一个公共类 SpaceSDK。
在公共源集
sharedLogic/src/commonMain/kotlin的com.jetbrains.spacetutorial包中创建SpaceSDK类。 该类将充当Database和SpaceApi类的门面。要创建
Database类实例,需提供一个DatabaseDriverFactory实例:kotlinpackage com.jetbrains.spacetutorial import com.jetbrains.spacetutorial.cache.Database import com.jetbrains.spacetutorial.cache.DatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi class SpaceSDK(databaseDriverFactory: DatabaseDriverFactory, val api: SpaceApi) { private val database = Database(databaseDriverFactory) }你将在平台特定代码中通过
SpaceSDK类的构造函数注入正确的数据库驱动程序。添加
getLaunches函数,该函数使用创建的数据库和 API 来请求并存储发射列表:kotlinimport com.jetbrains.spacetutorial.entity.RocketLaunch class SpaceSDK(databaseDriverFactory: DatabaseDriverFactory, val api: SpaceApi) { // ... @Throws(Exception::class) suspend fun getLaunches(forceReload: Boolean): List<RocketLaunch> { val cachedLaunches = database.getAllLaunches() return if (cachedLaunches.isNotEmpty() && !forceReload) { cachedLaunches } else { api.getAllLaunches().also { database.clearAndCreateLaunches(it) } } } }
该类包含一个用于获取所有发射信息的函数。根据 forceReload 的值,它会返回缓存的值,或者从网络加载数据并用结果更新缓存。如果没有缓存数据,则无论 forceReload 标志的值如何,它都会从网络加载数据。
你的 SDK 客户端可以使用 forceReload 标志来加载关于发射的最新信息,从而为用户提供下拉刷新手势支持。
所有 Kotlin 异常都是非受检异常,而 Swift 只有受检错误(详见与 Swift/Objective-C 的互操作性)。因此,为了让你的 Swift 代码能够感知预期的异常,从 Swift 调用的 Kotlin 函数应标记有 @Throws 注解,并指定潜在异常类的列表。
创建 Android 应用程序
IntelliJ IDEA 会为你处理初始的 Gradle 配置,因此 sharedUI 和 sharedLogic 模块已经连接到你的 Android 应用程序(androidApp)。
根据提示同步 Gradle 项目文件,或者双击 Shift 键并搜索 Sync All Gradle, Swift Package Manager projects。
为 androidApp 添加网络访问权限
为了访问互联网,Android 应用程序需要相应的权限。 在 androidApp/src/main/AndroidManifest.xml 文件中,添加 <uses-permission> 标记:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<!--...-->
</manifest>添加依赖项注入代码
通过 Koin 依赖项注入,你可以声明可在不同上下文中使用的模块(组件集)。 在本项目中,你将创建两个模块:一个用于 Android 应用程序,另一个用于 iOS 应用。 然后,你将使用对应的模块为每个原生 UI 启动 Koin。
声明一个包含 Android 应用组件的 Koin 模块:
在
sharedUI/build.gradle.kts文件中,为androidMain源集添加 Koin Android 依赖项:kotlinkotlin { // ... sourceSets { androidMain.dependencies { // ... implementation(libs.koin.androidx.compose) } } }创建
sharedUI/src/androidMain/kotlin目录以存放 Android 专属的 UI 代码。在
sharedUI/src/androidMain/kotlin目录下,创建com.jetbrains.spacetutorial包。从
sharedUI模块中移除commonMain和commonTest源集,因为 Android UI 并不进行共享。在
sharedUI/src/androidMain/kotlin/com.jetbrains.spacetutorial包中创建AppModule.kt文件。在该文件中,将 Koin 模块声明为两个单例,一个用于
SpaceApi类,另一个用于SpaceSDK类:kotlinimport com.jetbrains.spacetutorial.cache.AndroidDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi import org.koin.android.ext.koin.androidContext import org.koin.dsl.module val appModule = module { single<SpaceApi> { SpaceApi() } single<SpaceSDK> { SpaceSDK( databaseDriverFactory = AndroidDatabaseDriverFactory(androidContext()), api = get() ) } }SpaceSDK类的构造函数被注入了平台专属的AndroidDatabaseDriverFactory类。get()函数负责解析模块内的依赖项:对于SpaceSDK()的api形参,Koin 将传递先前声明的SpaceApi单例。在
androidApp/build.gradle.kts文件中,为androidApp模块添加 Koin Android 依赖项:kotlinkotlin { // ... dependencies { // ... implementation(libs.koin.androidx.compose) } }在
androidApp模块的src/main/kotlin/com/jetbrains/spacetutorial目录下,创建MainApplication类以启动 Koin 模块。将你在
AppModule.kt文件中声明的模块传递给modules()函数:kotlinpackage com.jetbrains.spacetutorial import android.app.Application import org.koin.android.ext.koin.androidContext import org.koin.core.context.GlobalContext.startKoin class MainApplication : Application() { override fun onCreate() { super.onCreate() startKoin { androidContext(this@MainApplication) modules(appModule) } } }在
AndroidManifest.xml文件的<application>标记中指定你创建的MainApplication类:xml<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... android:name="com.jetbrains.spacetutorial.MainApplication"> ... </application> </manifest>
现在,你已准备好实现使用平台专属数据库驱动程序所提供信息的 UI。
准备带有发射列表的 ViewModel
你将使用 Jetpack Compose 和 Material 3 实现 Android UI。首先,创建使用 SDK 获取发射列表的 ViewModel。然后设置 Material 主题,最后编写将所有内容组合在一起的 Composable 函数。
在
sharedUI/src/androidMain/kotlin目录的com.jetbrains.spacetutorial包中,创建RocketLaunchViewModel.kt文件:kotlinpackage com.jetbrains.spacetutorial import androidx.compose.runtime.State import androidx.compose.runtime.mutableStateOf import androidx.lifecycle.ViewModel import com.jetbrains.spacetutorial.entity.RocketLaunch class RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { private val _state = mutableStateOf(RocketLaunchScreenState()) val state: State<RocketLaunchScreenState> = _state } data class RocketLaunchScreenState( val isLoading: Boolean = false, val launches: List<RocketLaunch> = emptyList() )RocketLaunchScreenState实例将存储从 SDK 接收的数据以及请求的当前状态。在
RocketLaunchViewModel类中添加loadLaunches函数,该函数将在该 ViewModel 的协程作用域内调用 SDK 的getLaunches函数:kotlinimport androidx.lifecycle.viewModelScope import kotlinx.coroutines.launch class RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { //... fun loadLaunches() { viewModelScope.launch { _state.value = _state.value.copy(isLoading = true, launches = emptyList()) try { val launches = sdk.getLaunches(forceReload = true) _state.value = _state.value.copy(isLoading = false, launches = launches) } catch (_: Exception) { _state.value = _state.value.copy(isLoading = false, launches = emptyList()) } } } }在
RocketLaunchViewModel类中,添加包含loadLaunches()调用的init {}块,以便在创建RocketLaunchViewModel对象后立即从 API 请求数据:kotlinclass RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { // ... init { loadLaunches() } }现在,在
AppModule.kt文件中,于 Koin 模块中指定该 ViewModel:kotlinimport org.koin.core.module.dsl.viewModel val appModule = module { // ... viewModel { RocketLaunchViewModel(sdk = get()) } }
构建 Material 主题
你将围绕 Material 主题提供的 AppTheme 函数构建主 App() 可组合项:
你可以使用 Material Theme Builder 为你的 Compose 应用生成主题。 选取颜色、字体,然后点击右下角的 Export theme。
在导出界面上,点击 Export 下拉菜单并选择 Jetpack Compose (Theme.kt) 选项。
解压缩归档文件,并将
theme文件夹复制到sharedUI/src/androidMain/kotlin/com/jetbrains/spacetutorial目录中:
在
theme包内的每个文件中,修改package行以指向你创建的包:kotlinpackage com.jetbrains.spacetutorial.theme在
Color.kt文件中,添加两个用于表示发射成功与失败的颜色变量:kotlinval app_theme_successful = Color(0xff4BB543) val app_theme_unsuccessful = Color(0xffFC100D)
实现表现层逻辑
为你的应用程序创建主 App() 可组合项,并从 ComponentActivity 类中调用它:
在
sharedUI/src/androidApp/kotlin/com/jetbrains/spacetutorial目录中创建App.kt文件。打开
App.kt文件并插入以下代码:kotlinpackage com.jetbrains.spacetutorial import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.runtime.setValue import androidx.compose.ui.tooling.preview.Preview import org.koin.androidx.compose.koinViewModel import androidx.compose.material3.ExperimentalMaterial3Api @OptIn( ExperimentalMaterial3Api::class ) @Composable @Preview fun App() { val viewModel = koinViewModel<RocketLaunchViewModel>() val state by remember { viewModel.state } val coroutineScope = rememberCoroutineScope() var isRefreshing by remember { mutableStateOf(false) } val pullToRefreshState = rememberPullToRefreshState() }在此处,你使用 Koin ViewModel API 来引用你在 Android Koin 模块中声明的
viewModel。现在添加实现加载屏幕、发射结果列表列以及下拉刷新操作的 UI 代码:
import com.jetbrains.spacetutorial.theme.AppTheme {...}
kotlinimport androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.foundation.layout.padding import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.material3.* import androidx.compose.material3.pulltorefresh.PullToRefreshBox import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState import androidx.compose.runtime.* import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.tooling.preview.Preview import androidx.compose.ui.unit.dp import com.jetbrains.spacetutorial.entity.RocketLaunch import com.jetbrains.spacetutorial.theme.AppTheme import com.jetbrains.spacetutorial.theme.app_theme_successful import com.jetbrains.spacetutorial.theme.app_theme_unsuccessful import kotlinx.coroutines.launch import org.koin.androidx.compose.koinViewModel @OptIn(ExperimentalMaterial3Api::class) @Composable @Preview fun App() { val viewModel = koinViewModel<RocketLaunchViewModel>() val state by remember { viewModel.state } val coroutineScope = rememberCoroutineScope() var isRefreshing by remember { mutableStateOf(false) } val pullToRefreshState = rememberPullToRefreshState() AppTheme { Scaffold( topBar = { TopAppBar( title = { Text( "Space Launches", style = MaterialTheme.typography.headlineLarge ) } ) } ) { padding -> PullToRefreshBox( modifier = Modifier .fillMaxSize() .padding(padding), state = pullToRefreshState, isRefreshing = isRefreshing, onRefresh = { isRefreshing = true coroutineScope.launch { viewModel.loadLaunches() isRefreshing = false } } ) { if (state.isLoading && !isRefreshing) { Column( verticalArrangement = Arrangement.Center, horizontalAlignment = Alignment.CenterHorizontally, modifier = Modifier.fillMaxSize() ) { Text("Loading...", style = MaterialTheme.typography.bodyLarge) } } else { LazyColumn { items(state.launches) { launch: RocketLaunch -> Column( verticalArrangement = Arrangement.spacedBy(8.dp), modifier = Modifier.padding(16.dp) ) { Text( text = launch.missionName, style = MaterialTheme.typography.headlineSmall ) Text( text = if (launch.status.id == 3) "Successful" else "Unsuccessful", color = if (launch.status.id == 3) app_theme_successful else app_theme_unsuccessful ) Text( text = "Launch year: ${launch.launchYear}" ) val details = launch.status.description if (details.isNotBlank()) { Text(details) } } HorizontalDivider() } } } } } } }最后,在
androidApp/src/main/AndroidManifest.xml的<activity>标记中指定你的MainActivity类:xml<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... <activity ... android:name="com.jetbrains.spacetutorial.MainActivity"> ... </activity> </application> </manifest>运行你的 Android 应用:从运行配置菜单中选择 androidApp,选择一个模拟器,然后点击运行按钮。 应用程序会自动发起 API 请求并显示发射列表(背景颜色取决于你生成的 Material 主题):

你刚刚创建了一个 Android 应用程序,其业务逻辑在 Kotlin Multiplatform 模块中实现,UI 则运行在原生 Jetpack Compose 之上。
创建 iOS 应用程序
对于项目的 iOS 部分,你将使用 SwiftUI 构建用户界面,并使用 Model View View-Model 模式。
IntelliJ IDEA 生成的 iOS 项目已经连接到共享模块。Kotlin 模块以 sharedLogic/build.gradle.kts 文件中指定的名称(baseName = "SharedLogic")导出,并使用常规的 import 语句导入:import SharedLogic。
为 SQLDelight 添加动态链接标志
默认情况下,IntelliJ IDEA 生成的项目配置为静态链接 iOS 框架。
要在 iOS 上使用原生 SQLDelight 驱动程序,请添加动态链接器标志,以便 Xcode 工具链能够找到系统提供的 SQLite 二进制文件:
在 IntelliJ IDEA 中,选择 File | Open Project in Xcode 选项以在 Xcode 中打开你的项目。
在 Xcode 中,点击项目名称打开其设置。
切换到 Build Settings 选项卡,在该选项卡中切换到 All 列表,并搜索 Other Linker Flags 字段。
展开该字段,点击 Debug 字段旁边的加号,并将字符串
-lsqlite3粘贴到 Any Architecture | Any SDK 中。对 Other Linker Flags | Release 字段重复此过程。

返回 IntelliJ IDEA。
准备用于 iOS 依赖项注入的 Koin 类
要在 Swift 代码中使用 Koin 类和函数,请创建一个特殊的 KoinComponent 类并声明适用于 iOS 的 Koin 模块。
在
sharedLogic/src/iosMain/kotlin/com/jetbrains/spacetutorial目录下,创建KoinHelper.kt文件。添加
KoinHelper类,该类将使用延迟 Koin 注入包装SpaceSDK类:kotlinpackage com.jetbrains.spacetutorial import org.koin.core.component.KoinComponent import com.jetbrains.spacetutorial.entity.RocketLaunch import org.koin.core.component.inject class KoinHelper : KoinComponent { private val sdk: SpaceSDK by inject<SpaceSDK>() suspend fun getLaunches(forceReload: Boolean): List<RocketLaunch> { return sdk.getLaunches(forceReload = forceReload) } }在
KoinHelper类下方,添加initKoin()函数,你将在 Swift 中使用该函数来初始化并启动 iOS Koin 模块:kotlinimport com.jetbrains.spacetutorial.cache.IOSDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi import org.koin.core.context.startKoin import org.koin.dsl.module fun initKoin() { startKoin { modules(module { single<SpaceApi> { SpaceApi() } single<SpaceSDK> { SpaceSDK( databaseDriverFactory = IOSDatabaseDriverFactory(), api = get() ) } }) } }
现在,你可以在 iOS 应用中启动 Koin 模块,以便将原生数据库驱动程序与公共 SpaceSDK 类配合使用。
实现 UI
首先,你将创建一个 RocketLaunchRow SwiftUI 视图以显示列表中的每一项。它将基于 HStack 和 VStack 视图构建。在 RocketLaunchRow 结构体上将提供扩展,包含用于显示数据的实用帮助程序。
在 IntelliJ IDEA 中,确保处于 Project 视图中。
在
iosApp/iosApp文件夹中(与ContentView.swift同级),新建一个名为RocketLaunchRow的 Swift 文件。使用以下代码更新
RocketLaunchRow.swift文件:Swiftimport SwiftUI import SharedLogic struct RocketLaunchRow: View { var rocketLaunch: RocketLaunch var body: some View { HStack() { VStack(alignment: .leading, spacing: 10.0) { Text("\(rocketLaunch.missionName)") .font(.system(size: 18)) .bold() .fixedSize(horizontal: false, vertical: true) Text(launchText).foregroundColor(launchColor) Text("Launch year: \(String(rocketLaunch.launchYear))") Text("\(rocketLaunch.status.description_)") } Spacer() } } } extension RocketLaunchRow { private var launchText: String { let isSuccess = rocketLaunch.status.id == 3 return isSuccess ? "Successful" : "Unsuccessful" } private var launchColor: Color { let isSuccess = rocketLaunch.status.id == 3 return isSuccess ? Color.green : Color.red } }发射列表将显示在
ContentView视图中,该视图已包含在项目中。在
ContentView.swift文件中,为ContentView类添加一个扩展,其中包含用于准备和管理数据的ViewModel类:Swiftextension ContentView { enum LoadableLaunches { case loading case result([RocketLaunch]) case error(String) } @MainActor class ViewModel: ObservableObject { @Published var launches = LoadableLaunches.loading } }ViewModel(
ContentView.ViewModel)通过 Combine 框架与 View(ContentView)连接:ContentView.ViewModel类被声明为ObservableObject。@Published属性用于launches属性,因此每当该属性发生更改时,ViewModel 都会发出信号。
移除
ContentView_Previews结构体:你无需实现与该 ViewModel 兼容的预览。更新
ContentView类的主体以显示发射列表并添加重新加载功能。- 这是 UI 基础工作:你将在教程的下一阶段实现
loadLaunches函数。 viewModel属性标记有@ObservedObject特性,以订阅该 ViewModel。
swiftstruct ContentView: View { @ObservedObject private(set) var viewModel: ViewModel var body: some View { NavigationView { listView() .navigationBarTitle("Space Launches") .navigationBarItems(trailing: Button("Reload") { self.viewModel.loadLaunches(forceReload: true) }) } } private func listView() -> AnyView { switch viewModel.launches { case .loading: return AnyView(Text("Loading...").multilineTextAlignment(.center)) case .result(let launches): return AnyView(List(launches) { launch in RocketLaunchRow(rocketLaunch: launch) }) case .error(let description): return AnyView(Text(description).multilineTextAlignment(.center)) } } }- 这是 UI 基础工作:你将在教程的下一阶段实现
RocketLaunch类作为初始化List视图的参数使用,因此它需要遵循Identifiable协议。 该类已经有名为id的属性,因此你只需在ContentView.swift的底部添加一个扩展:Swiftextension RocketLaunch: Identifiable { }
加载数据
要在 ViewModel 中获取关于火箭发射的数据,你需要多平台库中 KoinHelper 类的实例。 它将允许你使用正确的数据库驱动程序调用 SDK 函数。
在
ContentView.swift文件中,扩展ViewModel类以包含一个KoinHelper对象和loadLaunches函数:Swiftextension ContentView { // ... class ViewModel: ObservableObject { // ... let helper: KoinHelper = KoinHelper() init() { self.loadLaunches(forceReload: false) } func loadLaunches(forceReload: Bool) { // TODO: retrieve data } } }在
loadLaunches()函数中,调用KoinHelper.getLaunches()函数(它将代理对SpaceSDK类的调用)并将结果保存到launches属性中:Swiftfunc loadLaunches(forceReload: Bool) { Task { do { self.launches = .loading let launches = try await helper.getLaunches(forceReload: forceReload) self.launches = .result(launches) } catch { self.launches = .error(error.localizedDescription) } } }将 Kotlin 模块编译为 Apple 框架时,可以使用 Swift 的
async/await机制调用挂起函数。由于在 Kotlin 中
getLaunches函数标记有@Throws(Exception::class)注解,任何作为Exception类或其子类实例的异常都将作为NSError传播到 Swift 中。 因此,所有此类异常都可以被loadLaunches()函数捕获。转到应用的入口点
iOSApp.swift文件,并初始化 Koin 模块、视图以及 ViewModel:Swiftimport SwiftUI import SharedLogic @main struct iOSApp: App { init() { KoinHelperKt.doInitKoin() } var body: some Scene { WindowGroup { ContentView(viewModel: .init()) } } }在 IntelliJ IDEA 中,切换到 iosApp 配置,选择一个模拟器,然后运行它以查看结果:

你可以在 final 分支上找到该项目的最终版本。
下一步
本教程包含一些可能较为消耗资源的操作,例如在主线程中解析 JSON 以及向数据库发起请求。要了解如何编写并发代码并优化你的应用,请参阅协程指南。
你还可以查看以下附加学习材料:
