引言：Kotlin Multiplatform 的崛起
在移动开发领域，跨平台开发一直是开发者和企业关注的焦点。传统的跨平台方案如 React Native 或 Flutter 虽然解决了”一次编写，多端运行”的问题，但往往在性能、原生体验和代码复用方面存在妥协。Kotlin Multiplatform（KMP）作为 JetBrains 推出的现代化跨平台解决方案，通过独特的架构设计和语言优势，为跨平台开发带来了全新的思路。
Kotlin Multiplatform 的核心理念不是”一次编写，多端运行”，而是”
共享核心逻辑，保留原生UI
“。这种方法既保证了应用的性能和原生体验，又大幅提升了开发效率。根据 JetBrains 的调查，采用 KMP 的团队平均可以共享 70% 以上的业务逻辑代码，同时保持 100% 的原生 UI 体验。
1. Kotlin Multiplatform 的核心架构
1.1 平台抽象层设计
Kotlin Multiplatform 通过 expect/actual 机制实现平台抽象，这是其解决跨平台难题的关键技术。
// 共享模块中的期望声明（expect）
// 这部分代码放在 shared/src/commonMain 目录下
expect fun getPlatformName(): String
expect fun showToast(message: String)
expect class PlatformHttpClient {
fun get(url: String): String
fun post(url: String, body: String): String
}
// 平台特定实现
// Android 实现（shared/src/androidMain）
actual fun getPlatformName(): String = “Android ${android.os.Build.VERSION.SDK_INT}”
actual fun showToast(message: String) {
Toast.makeText(android.app.Application.Context, message, Toast.LENGTH_SHORT).show()
}
actual class PlatformHttpClient actual constructor() {
private val client = OkHttpClient()
fun get(url: String): String {
val request = Request.Builder().url(url).build()
return client.newCall(request).execute().body?.string() ?: “”
}
fun post(url: String, body: String): String {
val requestBody = body.toRequestBody(“application/json”.toMediaType())
val request = Request.Builder()
.url(url)
.post(requestBody)
.build()
return client.newCall(request).execute().body?.string() ?: “”
}
}
// iOS 实现（shared/src/iosMain）
actual fun getPlatformName(): String = “iOS ${UIDevice.currentDevice.systemVersion}”
actual fun showToast(message: String) {
// iOS 的实现，使用 UIAlertController
val alert = UIAlertController.alertControllerWithTitle(
“Message”, message, UIAlertControllerStyle.Alert
)
alert.addAction(UIAlertAction.actionWithTitle(
“OK”, style = UIAlertActionStyle.Default, handler = null
))
// 获取当前的 view controller 来展示 alert
val viewController = UIApplication.sharedApplication.keyWindow?.rootViewController
viewController?.presentViewController(alert, animated = true, completion = null)
}
actual class PlatformHttpClient actual constructor() {
private val session = NSURLSession.sharedSession()
fun get(url: String): String {
val nsUrl = NSURL.URLWithString(url) ?: return “”
val request = NSURLRequest.requestWithURL(nsUrl)
val semaphore = DispatchSemaphore(0)
var result: String? = null
session.dataTaskWithRequest(request) { data, response, error ->
result = data?.let { NSString.create(it, NSStringEncoding.UTF8) }?.toString()
semaphore.signal()
}.resume()
semaphore.wait()
return result ?: “”
}
fun post(url: String, body: String): String {
val nsUrl = NSURL.URLWithString(url) ?: return “”
val request = NSMutableURLRequest.requestWithURL(nsUrl)
request.HTTPMethod = “POST”
request.HTTPBody = body.toNSData()
request.setValue(“application/json”, forHTTPHeaderField: “Content-Type”)
val semaphore = DispatchSemaphore(0)
var result: String? = null
session.dataTaskWithRequest(request) { data, response, error ->
result = data?.let { NSString.create(it, NSStringEncoding.UTF8) }?.toString()
semaphore.signal()
}.resume()
semaphore.wait()
return result ?: “”
}
}
1.2 共享模块结构
合理的项目结构是提升开发效率的基础。以下是推荐的 KMP 项目结构：
my-kmp-app/
├── androidApp/ # Android 原生应用模块
├── iosApp/ # iOS 原生应用模块
├── shared/ # 共享的 Kotlin 模块
│ ├── src/
│ │ ├── commonMain/ # 所有平台共享的代码
│ │ │ ├── data/ # 数据模型和仓库
│ │ │ ├── domain/ # 业务逻辑
│ │ │ ├── presentation/ # ViewModel 等
│ │ │ └── di/ # 依赖注入
│ │ ├── androidMain/ # Android 特定代码
│ │ ├── iosMain/ # iOS 特定代码
│ │ └── test/ # 测试代码
│ ├── build.gradle.kts
│ └── shared.podspec # iOS 集成配置
2. 解决跨平台难题的关键技术
2.1 异步编程的统一处理
跨平台开发中最大的挑战之一是异步操作的处理。Kotlin 协程为异步编程提供了统一的解决方案：
// 共享模块中的异步数据仓库
class UserRepository(
private val api: PlatformHttpClient,
private val cache: PlatformCache
) {
// 使用协程处理异步操作
suspend fun getUserProfile(userId: String): UserProfile {
// 先尝试从缓存读取
cache.getUser(userId)?.let { return it }
// 缓存未命中，从网络获取
val response = withContext(Dispatchers.IO) {
api.get(“https://api.example.com/users/$userId”)
}
// 解析响应
val user = parseUserResponse(response)
// 写入缓存
cache.saveUser(user)
return user
}
// 并行请求示例
suspend fun getUserDashboard(userId: String): UserDashboard {
return coroutineScope {
val userDeferred = async { getUserProfile(userId) }
val statsDeferred = async { getUserStats(userId) }
val notificationsDeferred = async { getNotifications(userId) }
UserDashboard(
user = userDeferred.await(),
stats = statsDeferred.await(),
notifications = notificationsDeferred.await()
)
}
}
// 错误处理
suspend fun getUserWithErrorHandling(userId: String): Result
return try {
Result.success(getUserProfile(userId))
} catch (e: NetworkException) {
Result.failure(UserLoadError(“Network error”, e))
} catch (e: SerializationException) {
Result.failure(UserLoadError(“Data format error”, e))
} catch (e: Exception) {
Result.failure(UserLoadError(“Unknown error”, e))
}
}
}
// 在 ViewModel 中使用
class UserViewModel : ViewModel() {
private val repository = UserRepository(
PlatformHttpClient(),
PlatformCache()
)
private val _userState = MutableStateFlow
val userState: StateFlow
fun loadUser(userId: String) {
viewModelScope.launch {
_userState.value = UserState.Loading
val result = repository.getUserWithErrorHandling(userId)
_userState.value = when {
result.isSuccess -> UserState.Success(result.getOrNull()!!)
else -> UserState.Error(result.exceptionOrNull()?.message ?: “Unknown error”)
}
}
}
}
2.2 数据序列化与类型安全
Kotlin Multiplatform 利用
kotlinx.serialization
提供跨平台的 JSON 处理能力：
// 共享模块的 build.gradle.kts
plugins {
kotlin(“multiplatform”)
kotlin(“plugin.serialization”)
}
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(“org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0”)
}
}
}
}
// 数据模型定义
@Serializable
data class UserProfile(
val id: String,
val name: String,
val email: String,
@Serializable(with = InstantSerializer::class)
val createdAt: Instant,
val preferences: UserPreferences
)
@Serializable
data class UserPreferences(
val theme: String = “light”,
val notifications: Boolean = true,
val language: String = “en”
)
// 序列化器扩展
object InstantSerializer : KSerializer
override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor(“Instant”, PrimitiveKind.STRING)
override fun serialize(encoder: Encoder, value: Instant) {
encoder.encodeString(value.toString())
}
override fun deserialize(decoder: Decoder): Instant {
return Instant.parse(decoder.decodeString())
}
}
// API 响应包装
@Serializable
data class ApiResponse
val success: Boolean,
val data: T? = null,
val error: ApiError? = null
)
@Serializable
data class ApiError(
val code: String,
val message: String,
val details: Map
)
// 使用示例
class UserApi(private val client: PlatformHttpClient) {
suspend fun getUser(id: String): Result
return try {
val response = client.get(“https://api.example.com/users/$id”)
val apiResponse = Json.decodeFromString
if (apiResponse.success && apiResponse.data != null) {
Result.success(apiResponse.data)
} else {
Result.failure(ApiException(apiResponse.error?.message ?: “Unknown error”))
}
} catch (e: Exception) {
Result.failure(e)
}
}
}
2.3 依赖注入与可测试性
Kotlin Multiplatform 支持依赖注入，便于编写可测试的共享代码：
// 共享模块中的依赖注入配置
// 使用 Koin 或自定义 DI 框架
// 这里展示手动 DI 实现
// 依赖容器
class ServiceLocator {
private val cache = PlatformCache()
private val httpClient = PlatformHttpClient()
val userRepository: UserRepository by lazy {
UserRepository(httpClient, cache)
}
val userViewModel: UserViewModel by lazy {
UserViewModel(userRepository)
}
companion object {
val instance = ServiceLocator()
}
}
// 在 ViewModel 中使用
class UserViewModel(private val repository: UserRepository) : ViewModel() {
// … 同上
}
// 测试代码
class UserRepositoryTest {
@Test
fun `should return cached user when available`() = runTest {
// Arrange
val mockCache = MockCache().apply {
saveUser(testUser)
}
val mockApi = MockHttpClient()
val repository = UserRepository(mockApi, mockCache)
// Act
val result = repository.getUserProfile(“123”)
// Assert
assertEquals(testUser, result)
assertEquals(0, mockApi.callCount) // 确保没有调用网络
}
@Test
fun `should fetch from network when cache miss`() = runTest {
// Arrange
val mockCache = MockCache() // 空缓存
val mockApi = MockHttpClient().apply {
mockResponse = Json.encodeToString(testUser)
}
val repository = UserRepository(mockApi, mockCache)
// Act
val result = repository.getUserProfile(“123”)
// Assert
assertEquals(testUser, result)
assertEquals(1, mockApi.callCount)
assertEquals(testUser, mockCache.getUser(“123”))
}
}
2.4 平台特定UI集成
Kotlin Multiplatform 允许在每个平台使用原生UI框架，同时共享业务逻辑：
Android 端集成（Compose）
// androidApp/src/main/java/com/example/app/ui/MainActivity.kt
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
MaterialTheme {
UserScreen()
}
}
}
}
@Composable
fun UserScreen(viewModel: UserViewModel = ServiceLocator.instance.userViewModel) {
val userState by viewModel.userState.collectAsState()
when (val state = userState) {
is UserState.Loading -> {
CircularProgressIndicator(modifier = Modifier.align(Alignment.Center))
}
is UserState.Success -> {
UserProfileCard(user = state.user)
}
is UserState.Error -> {
ErrorMessage(message = state.message, onRetry = { viewModel.loadUser(“123”) })
}
}
}
@Composable
fun UserProfileCard(user: UserProfile) {
Card(
modifier = Modifier
.fillMaxWidth()
.padding(16.dp),
elevation = 4.dp
) {
Column(modifier = Modifier.padding(16.dp)) {
Text(text = user.name, style = MaterialTheme.typography.h4)
Text(text = user.email, style = MaterialTheme.typography.body1)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = “Member since: ${user.createdAt}”,
style = MaterialTheme.typography.caption
)
}
}
}
iOS 端集成（SwiftUI）
// iosApp/iosApp/UserScreen.swift
import SwiftUI
import shared // 导入共享模块
struct UserScreen: View {
@StateObject private var viewModel = UserViewModelWrapper()
var body: some View {
Group {
switch viewModel.state {
case .loading:
ProgressView()
.frame(maxWidth: .infinity, maxHeight: .infinity)
case .success(let user):
UserProfileCard(user: user)
case .error(let message):
VStack {
Text(message)
.foregroundColor(.red)
Button(“Retry”) {
viewModel.loadUser()
}
}
}
}
.onAppear {
viewModel.loadUser()
}
}
}
// ViewModel 包装器，适配 SwiftUI
class UserViewModelWrapper: ObservableObject {
private let viewModel = ServiceLocator.shared.userViewModel
@Published var state: UserState = .loading
init() {
// 监听 Kotlin StateFlow
viewModel.userState.collect { newState in
DispatchQueue.main.async {
self.state = newState
}
}
}
func loadUser() {
viewModel.loadUser(userId: “123”)
}
}
struct UserProfileCard: View {
let user: UserProfile
var body: some View {
VStack(alignment: .leading, spacing: 8) {
Text(user.name)
.font(.largeTitle)
Text(user.email)
.font(.body)
.foregroundColor(.secondary)
Text(“Member since: \(user.createdAt)”)
.font(.caption)
}
.padding()
.background(Color(.systemGray6))
.cornerRadius(8)
.padding()
}
}
// 状态枚举包装
enum UserState {
case loading
case success(UserProfile)
case error(String)
}
3. 提升开发效率的实践方法
3.1 自动化构建与配置
使用 Gradle 脚本自动化重复性工作：
// shared/build.gradle.kts
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
plugins {
kotlin(“multiplatform”)
kotlin(“plugin.serialization”)
id(“com.android.library”)
id(“maven-publish”)
}
kotlin {
androidTarget {
compilations.all {
kotlinOptions {
jvmTarget = “1.8”
}
}
}
iosArm64()
iosSimulatorArm64()
sourceSets {
val commonMain by getting {
dependencies {
implementation(“org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0”)
implementation(“org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3”)
}
}
val androidMain by getting {
dependencies {
implementation(“androidx.core:core-ktx:1.12.0”)
implementation(“androidx.lifecycle:lifecycle-runtime-ktx:2.6.2”)
}
}
val iosMain by getting {
dependencies {
// iOS 特定依赖
}
}
}
}
// 自动化版本管理
object Versions {
const val kotlin = “1.9.20”
const val serialization = “1.6.0”
const val coroutines = “1.7.3”
}
// CI/CD 脚本扩展
tasks.register(“testAll”) {
dependsOn(“test”)
// 可以添加 iOS 测试任务
}
// 发布到 Maven 仓库
publishing {
publications {
create
from(components[“kotlin”])
groupId = “com.example”
artifactId = “shared”
version = “1.0.0”
}
}
}
3.2 代码生成与元编程
使用 Kotlin 的注解处理生成重复代码：
// 自定义注解处理器（在单独的模块中）
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class GenerateRepository
// 处理器示例（简化版）
// 实际项目中可以使用 KSP (Kotlin Symbol Processing)
class RepositoryProcessor {
fun process(element: AnnotatedElement): String {
// 生成 Repository 代码
return “””
class ${element.name}Repository(
private val api: PlatformHttpClient,
private val cache: PlatformCache
) {
suspend fun getById(id: String): Result<${element.name}> {
cache.get(id)?.let { return Result.success(it) }
val response = api.get(“${element.name}/$id”)
val data = Json.decodeFromString<${element.name}>(response)
cache.save(data)
return Result.success(data)
}
}
“””.trimIndent()
}
}
// 使用示例
@GenerateRepository
data class User(val id: String, val name: String)
// 生成的代码会自动包含：
// – 缓存逻辑
// – 网络请求
// – 错误处理
// – 类型安全的反序列化
3.3 持续集成配置
# .github/workflows/kmp-ci.yml
name: KMP CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v3
– name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: ’17’
distribution: ‘temurin’
– name: Cache Gradle
uses: actions/cache@v3
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
key: ${{ runner.os }}-gradle-${{ hashFiles(‘**/*.gradle*’, ‘**/gradle-wrapper.properties’) }}
– name: Run Unit Tests
run: ./gradlew test
– name: Run Android Instrumented Tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
script: ./gradlew connectedCheck
– name: Build Android App
run: ./gradlew :androidApp:assembleDebug
– name: Upload Artifacts
uses: actions/upload-artifact@v3
with:
name: android-app
path: androidApp/build/outputs/apk/debug/
ios-test:
runs-on: macos-latest
steps:
– uses: actions/checkout@v3
– name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: ’17’
distribution: ‘temurin’
– name: Cache Gradle
uses: actions/cache@v3
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
key: ${{ runner.os }}-gradle-${{ hashFiles(‘**/*.gradle*’, ‘**/gradle-wrapper.properties’) }}
– name: Build Shared Framework
run: ./gradlew :shared:podPublishReleaseXCFramework
– name: Run iOS Tests
run: |
cd iosApp
xcodebuild -scheme iosApp -destination ‘platform=iOS Simulator,name=iPhone 14’ test
4. 实际案例分析：构建跨平台电商应用
4.1 项目结构设计
ecommerce-kmp/
├── androidApp/
│ ├── src/main/java/com/ecommerce/android/
│ │ ├── MainActivity.kt
│ │ ├── ui/
│ │ │ ├── ProductListScreen.kt
│ │ │ ├── CartScreen.kt
│ │ │ └── CheckoutScreen.kt
│ │ └── di/
│ │ └── AndroidModule.kt
│ └── build.gradle.kts
├── iosApp/
│ ├── Sources/
│ │ ├── App/
│ │ │ ├── ContentView.swift
│ │ │ ├── ProductListView.swift
│ │ │ └── CartView.swift
│ │ └── DI/
│ │ └── IosModule.swift
│ └── iosApp.xcodeproj
├── shared/
│ ├── src/
│ │ ├── commonMain/
│ │ │ ├── data/
│ │ │ │ ├── model/
│ │ │ │ │ ├── Product.kt
│ │ │ │ │ ├── CartItem.kt
│ │ │ │ │ └── Order.kt
│ │ │ │ ├── repository/
│ │ │ │ │ ├── ProductRepository.kt
│ │ │ │ │ ├── CartRepository.kt
│ │ │ │ │ └── OrderRepository.kt
│ │ │ │ └── api/
│ │ │ │ └── EcommerceApi.kt
│ │ │ ├── domain/
│ │ │ │ ├── usecase/
│ │ │ │ │ ├── GetProductsUseCase.kt
│ │ │ │ │ ├── AddToCartUseCase.kt
│ │ │ │ │ └── CheckoutUseCase.kt
│ │ │ │ └── validation/
│ │ │ │ └── OrderValidator.kt
│ │ │ ├── presentation/
│ │ │ │ ├── viewmodel/
│ │ │ │ │ ├── ProductViewModel.kt
│ │ │ │ │ ├── CartViewModel.kt
│ │ │ │ │ └── CheckoutViewModel.kt
│ │ │ │ └── state/
│ │ │ │ ├── ProductState.kt
│ │ │ │ ├── CartState.kt
│ │ │ │ └── CheckoutState.kt
│ │ │ └── di/
│ │ │ └── AppModule.kt
│ │ ├── androidMain/
│ │ │ ├── di/
│ │ │ │ └── AndroidPlatformModule.kt
│ │ │ └── platform/
│ │ │ ├── ImageLoader.kt
│ │ │ └── Analytics.kt
│ │ ├── iosMain/
│ │ │ ├── di/
│ │ │ │ └── IosPlatformModule.kt
│ │ │ └── platform/
│ │ │ ├── ImageLoader.kt
│ │ │ └── Analytics.kt
│ │ └── test/
│ │ ├── commonTest/
│ │ │ ├── repository/
│ │ │ │ └── ProductRepositoryTest.kt
│ │ │ └── usecase/
│ │ │ └── GetProductsUseCaseTest.kt
│ │ ├── androidTest/
│ │ └── iosTest/
│ ├── build.gradle.kts
│ └── shared.podspec
└── build.gradle.kts
4.2 核心业务逻辑实现
// shared/src/commonMain/kotlin/data/model/Product.kt
@Serializable
data class Product(
val id: String,
val name: String,
val description: String,
val price: Double,
val imageUrl: String,
val category: String,
val inStock: Boolean = true
)
// shared/src/commonMain/kotlin/domain/usecase/GetProductsUseCase.kt
class GetProductsUseCase(
private val repository: ProductRepository
) {
suspend operator fun invoke(category: String? = null): Result
return repository.getProducts(category)
}
}
// shared/src/commonMain/kotlin/domain/usecase/AddToCartUseCase.kt
class AddToCartUseCase(
private val cartRepository: CartRepository
) {
suspend operator fun invoke(product: Product, quantity: Int = 1): Result
require(quantity > 0) { “Quantity must be positive” }
val currentItems = cartRepository.getCartItems().getOrNull() ?: emptyList()
val existingItem = currentItems.find { it.productId == product.id }
return if (existingItem != null) {
val newQuantity = existingItem.quantity + quantity
cartRepository.updateQuantity(product.id, newQuantity)
} else {
val newItem = CartItem(
productId = product.id,
productName = product.name,
price = product.price,
quantity = quantity,
imageUrl = product.imageUrl
)
cartRepository.addItem(newItem)
}
}
}
// shared/src/commonMain/kotlin/presentation/viewmodel/ProductViewModel.kt
class ProductViewModel(
private val getProductsUseCase: GetProductsUseCase
) : ViewModel() {
private val _state = MutableStateFlow
val state: StateFlow
private val _events = MutableSharedFlow
val events: SharedFlow
fun loadProducts(category: String? = null) {
viewModelScope.launch {
_state.value = ProductState.Loading
val result = getProductsUseCase(category)
result.onSuccess { products ->
_state.value = ProductState.Success(products)
}.onFailure { error ->
_state.value = ProductState.Error(error.message ?: “Unknown error”)
_events.emit(ProductEvent.ShowError(error.message ?: “Unknown error”))
}
}
}
fun refresh() {
loadProducts()
}
}
// shared/src/commonMain/kotlin/data/repository/ProductRepository.kt
class ProductRepository(
private val api: EcommerceApi,
private val cache: PlatformCache
) {
suspend fun getProducts(category: String?): Result
return try {
// 先检查缓存
val cached = cache.getProducts(category)
if (cached.isNotEmpty()) {
return Result.success(cached)
}
// 从 API 获取
val products = api.getProducts(category)
// 缓存结果
cache.saveProducts(products, category)
Result.success(products)
} catch (e: Exception) {
// 如果网络失败但有缓存，返回缓存
val cached = cache.getProducts(category)
if (cached.isNotEmpty()) {
Result.success(cached)
} else {
Result.failure(e)
}
}
}
suspend fun getProductById(id: String): Result
return try {
val cached = cache.getProduct(id)
if (cached != null) {
return Result.success(cached)
}
val product = api.getProduct(id)
cache.saveProduct(product)
Result.success(product)
} catch (e: Exception) {
Result.failure(e)
}
}
}
4.3 平台特定实现
// shared/src/androidMain/kotlin/platform/Analytics.kt
actual class Analytics actual constructor() {
actual fun trackEvent(name: String, params: Map
// Android 实现：使用 Firebase Analytics
FirebaseAnalytics.getInstance(context).logEvent(name, Bundle().apply {
params.forEach { (key, value) ->
when (value) {
is String -> putString(key, value)
is Int -> putInt(key, value)
is Double -> putDouble(key, value)
is Boolean -> putBoolean(key, value)
}
}
})
}
actual fun trackScreen(screenName: String) {
FirebaseAnalytics.getInstance(context).logEvent(FirebaseAnalytics.Event.SCREEN_VIEW, Bundle().apply {
putString(FirebaseAnalytics.Param.SCREEN_NAME, screenName)
putString(FirebaseAnalytics.Param.SCREEN_CLASS, screenName)
})
}
}
// shared/src/iosMain/kotlin/platform/Analytics.kt
actual class Analytics actual constructor() {
actual fun trackEvent(name: String, params: Map
// iOS 实现：使用 Firebase 或自定义分析
FIRAnalytics.logEventWithName(name, parameters: params as? [String: Any])
}
actual fun trackScreen(screenName: String) {
FIRAnalytics.logEventWithName(“screen_view”, parameters: [“screen_name”: screenName])
}
}
4.4 Android UI 实现
// androidApp/src/main/java/com/ecommerce/android/ui/ProductListScreen.kt
@Composable
fun ProductListScreen(
viewModel: ProductViewModel = ServiceLocator.instance.productViewModel
) {
val state by viewModel.state.collectAsState()
val event by viewModel.events.collectAsState(initial = null)
// 处理事件
LaunchedEffect(event) {
when (event) {
is ProductEvent.ShowError -> {
// 显示 Snackbar
// …
}
else -> {}
}
}
Scaffold(
topBar = {
TopAppBar(title = { Text(“Products”) })
},
floatingActionButton = {
FloatingActionButton(onClick = { /* 导航到购物车 */ }) {
Icon(Icons.Default.ShoppingCart, contentDescription = “Cart”)
}
}
) { padding ->
when (val currentState = state) {
is ProductState.Loading -> {
Box(
modifier = Modifier.fillMaxSize(),
contentAlignment = Alignment.Center
) {
CircularProgressIndicator()
}
}
is ProductState.Success -> {
ProductList(
products = currentState.products,
onProductClick = { product ->
// 导航到详情页
},
onAddToCart = { product ->
// 调用 ViewModel 添加到购物车
},
modifier = Modifier.padding(padding)
)
}
is ProductState.Error -> {
ErrorView(
message = currentState.message,
onRetry = { viewModel.refresh() },
modifier = Modifier.padding(padding)
)
}
}
}
}
@Composable
fun ProductList(
products: List
onProductClick: (Product) -> Unit,
onAddToCart: (Product) -> Unit,
modifier: Modifier = Modifier
) {
LazyColumn(
modifier = modifier.fillMaxSize(),
contentPadding = PaddingValues(16.dp),
verticalArrangement = Arrangement.spacedBy(8.dp)
) {
items(products) { product ->
ProductItem(
product = product,
onClick = { onProductClick(product) },
onAddToCart = { onAddToCart(product) }
)
}
}
}
@Composable
fun ProductItem(
product: Product,
onClick: () -> Unit,
onAddToCart: () -> Unit
) {
Card(
modifier = Modifier
.fillMaxWidth()
.clickable(onClick = onClick),
elevation = 4.dp
) {
Row(
modifier = Modifier.padding(16.dp),
horizontalArrangement = Arrangement.spacedBy(12.dp)
) {
// 图片加载使用平台特定实现
AsyncImage(
model = product.imageUrl,
contentDescription = product.name,
modifier = Modifier
.size(80.dp)
.clip(RoundedCornerShape(8.dp))
)
Column(modifier = Modifier.weight(1f)) {
Text(
text = product.name,
style = MaterialTheme.typography.h6,
maxLines = 1,
overflow = TextOverflow.Ellipsis
)
Text(
text = product.description,
style = MaterialTheme.typography.body2,
maxLines = 2,
overflow = TextOverflow.Ellipsis
)
Text(
text = “$${product.price}”,
style = MaterialTheme.typography.subtitle1,
color = MaterialTheme.colors.primary
)
Spacer(modifier = Modifier.height(8.dp))
Button(
onClick = onAddToCart,
modifier = Modifier.fillMaxWidth(),
enabled = product.inStock
) {
Text(if (product.inStock) “Add to Cart” else “Out of Stock”)
}
}
}
}
}
4.5 iOS UI 实现
// iosApp/Sources/App/ProductListView.swift
import SwiftUI
import shared
struct ProductListView: View {
@StateObject private var viewModel = ProductViewModelWrapper()
@State private var showingCart = false
var body: some View {
NavigationView {
Group {
switch viewModel.state {
case .loading:
ProgressView()
.frame(maxWidth: .infinity, maxHeight: .infinity)
case .success(let products):
List(products) { product in
ProductRow(
product: product,
onAddToCart: {
viewModel.addToCart(product: product)
}
)
.listRowSeparator(.hidden)
}
.listStyle(PlainListStyle())
case .error(let message):
ErrorView(message: message) {
viewModel.refresh()
}
}
}
.navigationTitle(“Products”)
.toolbar {
ToolbarItem(placement: .navigationBarTrailing) {
Button(action: { showingCart = true }) {
Image(systemName: “cart”)
}
}
}
.sheet(isPresented: $showingCart) {
CartView()
}
.onAppear {
viewModel.loadProducts()
}
}
}
}
struct ProductRow: View {
let product: Product
let onAddToCart: () -> Void
var body: some View {
HStack(spacing: 12) {
// 使用 Kingfisher 或 SDWebImage 进行图片加载
AsyncImage(url: URL(string: product.imageUrl)) { image in
image.resizable()
.aspectRatio(contentMode: .fill)
} placeholder: {
Rectangle()
.fill(Color.gray.opacity(0.3))
}
.frame(width: 80, height: 80)
.cornerRadius(8)
VStack(alignment: .leading, spacing: 4) {
Text(product.name)
.font(.headline)
.lineLimit(1)
Text(product.description)
.font(.caption)
.foregroundColor(.secondary)
.lineLimit(2)
Text(String(format: “$%.2f”, product.price))
.font(.subheadline)
.fontWeight(.semibold)
.foregroundColor(.blue)
Button(action: onAddToCart) {
Text(product.inStock ? “Add to Cart” : “Out of Stock”)
.font(.caption)
.fontWeight(.bold)
.foregroundColor(.white)
.padding(.horizontal, 12)
.padding(.vertical, 6)
.background(
product.inStock ? Color.blue : Color.gray
)
.cornerRadius(6)
}
.disabled(!product.inStock)
}
Spacer()
}
.padding(.vertical, 4)
}
}
struct ErrorView: View {
let message: String
let retryAction: () -> Void
var body: some View {
VStack(spacing: 16) {
Image(systemName: “exclamationmark.triangle”)
.font(.largeTitle)
.foregroundColor(.orange)
Text(message)
.font(.body)
.multilineTextAlignment(.center)
Button(“Retry”, action: retryAction)
.buttonStyle(.borderedProminent)
}
.padding()
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
}
// ViewModel 包装器
class ProductViewModelWrapper: ObservableObject {
private let viewModel = ServiceLocator.shared.productViewModel
@Published var state: ProductState = .loading
init() {
viewModel.state.collect { newState in
DispatchQueue.main.async {
self.state = newState
}
}
}
func loadProducts() {
viewModel.loadProducts(category: nil)
}
func refresh() {
viewModel.refresh()
}
func addToCart(product: Product) {
// 调用共享的 AddToCartUseCase
let useCase = ServiceLocator.shared.addToCartUseCase
Task {
_ = try await useCase.invoke(product: product, quantity: 1)
}
}
}
5. 性能优化与最佳实践
5.1 内存管理优化
// 共享模块中的内存优化
class ImageCache {
private val cache = mutableMapOf
private val sizeLimit = 50 * 1024 * 1024 // 50MB
private var currentSize = 0
suspend fun get(key: String): ByteArray? = withContext(Dispatchers.Default) {
cache[key]
}
suspend fun put(key: String, data: ByteArray) = withContext(Dispatchers.Default) {
if (data.size > sizeLimit / 10) return@withContext // 太大的图片不缓存
// 清理空间
while (currentSize + data.size > sizeLimit && cache.isNotEmpty()) {
val firstKey = cache.keys.first()
currentSize -= cache[firstKey]?.size ?: 0
cache.remove(firstKey)
}
cache[key] = data
currentSize += data.size
}
fun clear() {
cache.clear()
currentSize = 0
}
}
// 在 ViewModel 中使用弱引用避免内存泄漏
class ProductViewModel private constructor(
private val getProductsUseCase: GetProductsUseCase
) : ViewModel() {
companion object {
private var instance: ProductViewModel? = null
fun getInstance(getProductsUseCase: GetProductsUseCase): ProductViewModel {
return instance ?: ProductViewModel(getProductsUseCase).also { instance = it }
}
}
// … 其他代码
}
5.2 网络请求优化
// 共享模块中的网络优化
class OptimizedHttpClient(
private val delegate: PlatformHttpClient,
private val cache: PlatformCache
) {
private val requestCache = mutableMapOf
private val lastModified = mutableMapOf
suspend fun getWithCache(
url: String,
forceRefresh: Boolean = false,
maxAge: Long = 300 // 5分钟
): String {
val now =.currentTimeMillis()
// 检查内存缓存
val cached = requestCache[url]
if (!forceRefresh && cached != null && (now – cached.timestamp) < maxAge * 1000) {
return cached.data
}
// 检查持久化缓存
val persisted = cache.getString(url)
if (!forceRefresh && persisted != null) {
// 检查 ETag/Last-Modified
val etag = lastModified[url]
if (etag != null) {
// 发送条件请求
val response = delegate.get("$url?if-none-match=$etag")
if (response == "304") {
// 未修改，使用缓存
requestCache[url] = CachedResponse(persisted, now)
return persisted
}
}
requestCache[url] = CachedResponse(persisted, now)
return persisted
}
// 完全重新获取
val response = delegate.get(url)
requestCache[url] = CachedResponse(response, now)
cache.saveString(url, response)
// 提取 ETag
// 实际项目中需要从响应头获取
lastModified[url] = "etag-from-response"
return response
}
data class CachedResponse(val data: String, val timestamp: Long)
}
5.3 并发控制
// 共享模块中的并发优化
class RequestThrottler(
private val maxRequests: Int = 5,
private val timeout: Long = 1000
) {
private val semaphore = Semaphore(maxRequests)
private val lastRequestTime = mutableMapOf
suspend fun
key: String,
block: suspend () -> T
): T {
val now = System.currentTimeMillis()
val lastTime = lastRequestTime[key] ?: 0
// 节流：同一 key 的请求间隔至少 timeout
if (now – lastTime < timeout) {
delay(timeout - (now - lastTime))
}
lastRequestTime[key] = System.currentTimeMillis()
// 限制并发数
semaphore.withPermit {
return block()
}
}
}
// 使用示例
class ProductRepository(
private val api: EcommerceApi,
private val cache: PlatformCache
) {
private val throttler = RequestThrottler(maxRequests = 3)
suspend fun searchProducts(query: String): Result
return throttler.throttle(“search:$query”) {
try {
val results = api.search(query)
cache.saveSearchResults(query, results)
Result.success(results)
} catch (e: Exception) {
// 降级到缓存
val cached = cache.getSearchResults(query)
if (cached.isNotEmpty()) {
Result.success(cached)
} else {
Result.failure(e)
}
}
}
}
}
6. 团队协作与代码共享策略
6.1 模块化设计
// settings.gradle.kts
pluginManagement {
repositories {
gradlePluginPortal()
google()
mavenCentral()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
}
}
rootProject.name = “MyKMPApp”
include(“:androidApp”)
include(“:iosApp”)
include(“:shared”)
include(“:shared-ui”) // 可选：纯 UI 共享（Compose Multiplatform）
include(“:shared-network”) // 网络层
include(“:shared-data”) // 数据层
include(“:shared-domain”) // 领域层
// shared-domain/build.gradle.kts
plugins {
kotlin(“multiplatform”)
}
kotlin {
sourceSets {
commonMain {
dependencies {
// 只依赖纯 Kotlin 库
implementation(“org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0”)
implementation(“org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3”)
}
}
}
}
// shared-network/build.gradle.kts
plugins {
kotlin(“multiplatform”)
}
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(project(“:shared-domain”))
implementation(“org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3”)
}
}
androidMain {
dependencies {
implementation(“com.squareup.okhttp3:okhttp:4.12.0”)
}
}
iosMain {
dependencies {
// iOS 网络库
}
}
}
}
6.2 API 设计原则
// 共享模块中的 API 设计
// 1. 使用密封类表示状态
sealed interface Result
data class Success
data class Error(val exception: Throwable) : Result
object Loading : Result
}
// 2. 使用接口定义契约
interface UserRepository {
suspend fun getUser(id: String): Result
suspend fun updateUser(user: User): Result
suspend fun deleteUser(id: String): Result
}
// 3. 使用工厂模式创建实例
class UserRepositoryFactory {
fun create(cache: PlatformCache): UserRepository {
return when (Platform.current) {
Platform.Android -> AndroidUserRepository(cache)
Platform.IOS -> IOSUserRepository(cache)
}
}
}
// 4. 使用 Builder 模式配置复杂对象
class ApiClientBuilder {
private var baseUrl: String = “”
private var timeout: Long = 30000
private var interceptors: List
fun baseUrl(url: String) = apply { this.baseUrl = url }
fun timeout(millis: Long) = apply { this.timeout = millis }
fun addInterceptor(interceptor: Interceptor) = apply {
this.interceptors = interceptors + interceptor
}
fun build(): PlatformHttpClient {
return PlatformHttpClient(baseUrl, timeout, interceptors)
}
}
6.3 文档与注释规范
/**
* 用户数据仓库接口
*
* 负责用户数据的获取、更新和删除操作。
* 所有方法都返回 [Result] 类型，统一处理成功和失败情况。
*
* @constructor 创建用户仓库实例
* @property cache 用于数据缓存的平台特定实现
*
* @sample UserRepositoryTest
*/
interface UserRepository {
/**
* 根据 ID 获取用户信息
*
* 首先尝试从缓存获取，如果缓存未命中则从网络获取。
* 网络请求失败时会自动重试一次。
*
* @param id 用户唯一标识符
* @return [Result.Success] 包含用户对象，或 [Result.Error] 包含异常信息
*
* @throws IllegalArgumentException 如果 id 为空
* @throws NetworkException 网络连接失败
* @throws SerializationException 数据解析失败
*
* @sample com.example.userRepository.getUser
*/
suspend fun getUser(id: String): Result
/**
* 更新用户信息
*
* 会先进行数据验证，然后同步到服务器和本地缓存。
*
* @param user 要更新的用户对象，必须包含有效的 ID
* @return [Result.Success] 包含更新后的用户对象，或 [Result.Error]
*
* @throws ValidationException 如果用户数据无效
*/
suspend fun updateUser(user: User): Result
}
/**
* 用户验证器
*
* 提供用户数据的验证逻辑，包括：
* – 邮箱格式验证
* – 密码强度检查
* – 必填字段检查
*/
object UserValidator {
/**
* 验证邮箱格式
*
* @param email 要验证的邮箱地址
* @return true 如果邮箱格式有效
*/
fun isValidEmail(email: String): Boolean {
return Regex(“^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$”).matches(email)
}
/**
* 验证密码强度
*
* 要求：至少8位，包含大小写字母和数字
*
* @param password 要验证的密码
* @return [PasswordStrength] 等级
*/
fun validatePasswordStrength(password: String): PasswordStrength {
return when {
password.length < 8 -> PasswordStrength.Weak
!password.any { it.isUpperCase() } -> PasswordStrength.Weak
!password.any { it.isLowerCase() } -> PasswordStrength.Weak
!password.any { it.isDigit() } -> PasswordStrength.Weak
password.length >= 12 -> PasswordStrength.Strong
else -> PasswordStrength.Medium
}
}
}
/**
* 密码强度等级
*/
enum class PasswordStrength {
/** 弱密码：长度不足或缺少字符类型 */
Weak,
/** 中等密码：满足基本要求但长度一般 */
Medium,
/** 强密码：长度足够且包含多种字符类型 */
Strong
}
7. 常见问题与解决方案
7.1 平台特定依赖管理
问题
：某些库只在特定平台可用
解决方案
：
// 使用 expect/actual 包装平台特定依赖
// commonMain
expect class ImageLoader {
fun load(url: String): ImageData
}
// androidMain
actual class ImageLoader actual constructor() {
private val coilLoader = Coil.imageLoader(context)
actual fun load(url: String): ImageData {
// 使用 Coil 加载图片
return coilLoader.load(url)
}
}
// iosMain
actual class ImageLoader actual constructor() {
private val sdWebImageLoader = SDWebImageManager.shared
actual fun load(url: String): ImageData {
// 使用 SDWebImage 加载图片
return sdWebImageLoader.loadImage(url)
}
}
// 在 ViewModel 中使用
class SharedViewModel(private val imageLoader: ImageLoader) {
fun loadImage(url: String) {
val imageData = imageLoader.load(url)
// 处理图片数据
}
}
7.2 序列化问题
问题
：复杂嵌套对象或泛型序列化失败
解决方案
：
// 使用自定义序列化器
@Serializable(with = CustomListSerializer::class)
data class CustomList
class CustomListSerializer
private val listSerializer = ListSerializer(tSerializer)
override val descriptor: SerialDescriptor = listSerializer.descriptor
override fun serialize(encoder: Encoder, value: CustomList
listSerializer.serialize(encoder, value.items)
}
override fun deserialize(decoder: Decoder): CustomList
val items = listSerializer.deserialize(decoder)
return CustomList(items)
}
}
// 处理多态序列化
@Serializable
sealed class PaymentMethod
@Serializable
@SerialName(“credit_card”)
data class CreditCard(
val number: String,
val expiry: String,
val cvv: String
) : PaymentMethod()
@Serializable
@SerialName(“paypal”)
data class PayPal(
val email: String
) : PaymentMethod()
// 使用 PolymorphicSerializer
object PaymentMethodSerializer : JsonContentPolymorphicSerializer
override fun selectDeserializer(element: JsonElement): DeserializationStrategy
return when (element.jsonObject[“type”]?.jsonPrimitive?.content) {
“credit_card” -> CreditCard.serializer()
“paypal” -> PayPal.serializer()
else -> throw SerializationException(“Unknown payment method”)
}
}
}
7.3 测试覆盖问题
问题
：如何确保共享代码在所有平台都能正常工作
解决方案
：
// 使用测试接口
interface TestableRepository {
suspend fun getData(): Result
}
class ProductionRepository : TestableRepository {
override suspend fun getData(): Result
// 实际实现
return Result.success(“data”)
}
}
class MockRepository : TestableRepository {
override suspend fun getData(): Result
return Result.success(“mock data”)
}
}
// 共享测试基类
abstract class BaseRepositoryTest {
protected abstract fun createRepository(): TestableRepository
@Test
fun `should return data`() = runTest {
val repository = createRepository()
val result = repository.getData()
assertTrue(result.isSuccess)
assertEquals(“data”, result.getOrNull())
}
}
// 平台特定测试
class AndroidRepositoryTest : BaseRepositoryTest() {
override fun createRepository(): TestableRepository = ProductionRepository()
}
class IOSRepositoryTest : BaseRepositoryTest() {
override fun createRepository(): TestableRepository = ProductionRepository()
}
// 使用测试配置
class TestConfig {
companion object {
const val USE_MOCK = true
fun
return if (USE_MOCK) {
MockRepository() as T
} else {
creator()
}
}
}
}
8. 未来发展趋势
8.1 Compose Multiplatform
Kotlin Multiplatform 正在向 UI 共享方向发展，Compose Multiplatform 允许在 Android、iOS、桌面和 Web 之间共享 UI 代码：
// 共享 UI 代码示例
@Composable
fun SharedAppTheme(
darkTheme: Boolean = isSystemInDarkTheme(),
content: @Composable () -> Unit
) {
MaterialTheme(
colorScheme = if (darkTheme) darkColors() else lightColors(),
typography = Typography,
content = content
)
}
@Composable
fun SharedApp() {
SharedAppTheme {
Navigator(
screen = HomeScreen(),
backHandler = { /* 处理返回键 */ }
)
}
}
// 在 Android 中使用
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
SharedApp()
}
}
}
// 在 iOS 中使用
struct iOSApp: App {
var body: some Scene {
WindowGroup {
SharedApp()
}
}
}
8.2 WebAssembly 支持
Kotlin/Wasm 正在成为新的跨平台目标：
// 共享业务逻辑，同时支持 WebAssembly
class WebAppViewModel {
suspend fun fetchData(): String {
// 这段代码可以在 JVM, Native, 和 Wasm 中运行
return “Hello from Kotlin/Wasm”
}
}
总结
Kotlin Multiplatform 通过以下方式解决跨平台难题并提升开发效率：
架构设计
：共享核心逻辑，保留原生 UI，平衡性能与复用
语言优势
：Kotlin 的空安全、协程、序列化等特性天然适合跨平台
工具链
：IntelliJ IDEA 的完美支持，Gradle 的灵活配置
生态系统
：与现有 Android 生态无缝集成，逐步完善 iOS 支持
渐进式迁移
：可以逐步引入，不影响现有项目
通过合理运用 Kotlin Multiplatform，团队可以实现
70%+ 的代码复用率
，同时保持
100% 的原生性能
，这是传统跨平台方案难以达到的平衡点。随着 Compose Multiplatform 的成熟，Kotlin 在跨平台开发领域的优势将进一步扩大。