Was expect/actual tatsächlich ist
expect/actual ist Kotlin Multiplatforms Mechanismus, um eine Deklaration einmal im geteilten Code zu schreiben und ihr pro Plattform einen eigenen Körper zu geben.
- Eine
expect-Deklaration lebt incommonMain. Sie deklariert die Signatur einer Klasse, Funktion oder Property ohne Körper – ein Versprechen, dass für jede Plattform, die das Projekt baut, eine passende Implementierung existiert. - Eine
actual-Deklaration lebt in einem plattformspezifischen , etwaandroidMainoderiosMain, und erfüllt dieses Versprechen mit der echten Implementierung für genau diese eine Plattform. - Der Compiler prüft, dass jedes
expectfür jedes gebaute Target ein passendesactualhat, und lässt den Build scheitern, falls eines fehlt.
Das ist der Vertrag. Was er nicht sagt, ist wann dieses Matching passiert – und genau dort geht das mentale Modell meist schief.
Die Intuition
expect/actual liest sich wie ein Interface mit plattformspezifischen Implementierungen: Interface definieren, auf Android eine andere Implementierung injizieren als auf iOS. Dieses Bild übertragen wir ganz natürlich aus Dependency Injection. Es ist auf eine bestimmte Art falsch.
- Ein Interface hat genau eine kompilierte Form, und welche Implementierung läuft, wird zur
entschieden, von dem, was der DI-Graph (oder ein simples
if) liefert. - Eine
expect-Deklaration hat überhaupt keine eigene kompilierte Form. Jedes Target kompiliert commonMain gegen sein eigenes passendesactual, fest eingebaut, bevor das Binary existiert. - Es gibt nie einen Moment, in dem sowohl das Android-
actualals auch das iOS-actualim selben kompilierten Artefakt existieren. Der Build jedes Targets sieht immer nur eines von beiden – das, welches für dieses Targetactualist.
Das „Austauschen der Implementierung" passiert also zur Compile-Zeit, pro Source Set, nicht zur Laufzeit innerhalb eines laufenden Prozesses. Es gibt nichts auszutauschen, sobald ein Binary existiert, weil nie etwas anderes in es hineinkompiliert wurde.
Ein Plattform-Logger, der naheliegende Weg
// commonMain
expect class PlatformLogger() {
fun log(message: String)
}
fun greet() {
PlatformLogger().log("Hello from commonMain")
}// androidMain
actual class PlatformLogger {
actual fun log(message: String) {
android.util.Log.d("App", message)
}
}// iosMain
actual class PlatformLogger {
actual fun log(message: String) {
platform.Foundation.NSLog(message)
}
}greet() wird einmal in commonMain geschrieben und ruft PlatformLogger().log(...) auf, ohne zu wissen, auf welcher Plattform es laufen wird. Dieser Teil sieht tatsächlich aus wie ein Aufruf über ein Interface.
Der Unterschied zeigt sich in dem, was der Android-Build tatsächlich kompiliert:
- Er sieht
iosMainsactual class PlatformLoggerüberhaupt nie – nicht als toten Code, nicht als unbenutzten Zweig, nirgendwo kompiliert. - Die Android-Kompilationseinheit ist nur
commonMain+androidMain, wobei jedesexpectdarin direkt auf seinandroidMain-actualaufgelöst wird, bevor die Codegenerierung passiert.
Tausche androidMain gegen iosMain aus, und du bekommst ein anderes, separat kompiliertes Binary, nicht einen anderen Laufzeitpfad durch dasselbe.
Der Versuch, ein actual zur Laufzeit auszuwählen, scheitert am Typecheck
// ❌ es gibt kein PlatformLogger-"Interface", auf das man eine Referenz halten könnte;
// expect-Deklarationen sind kein Typ, den man hinter einer Variable austauschen kann
class Container(private val logger: PlatformLogger)
fun buildForTesting(): Container {
// der Versuch, eine Fake-Implementierung so zu injizieren, wie man es
// bei einem echten Interface tun würde
return Container(logger = FakePlatformLogger()) // Compile-Fehler:
// FakePlatformLogger ist kein Subtyp von PlatformLogger: Klassen
// sind in Kotlin standardmäßig final, sofern nicht open markiert,
// und dieses expect/actual-Paar markiert sich nicht als open
}Das ist genau der Fehler, zu dem das DI-mentale-Modell direkt führt: zu expect/actual greifen, um für Tests eine Fake/austauschbare Implementierung zu bekommen, genauso wie man ein Repository-Interface gegen ein FakeRepository tauschen würde. PlatformLogger lässt sich hier nicht unterklassen, aber das ist gewöhnliches Kotlin-Verhalten (Klassen sind final, sofern nicht open markiert), nichts, was expect/actual erfindet. Auch expect open class PlatformLogger() würde den DI-Anwendungsfall nicht retten: Es würde erlauben, die eine actual-Klasse zu unterklassen, die es in das Binary dieses Targets geschafft hat, nicht zwischen Androids und einer Fake-Implementierung an derselben Aufrufstelle zu wechseln. Ob open oder nicht, man bekommt pro Compilation immer nur einen PlatformLogger-Typ.
Wenn du eine zur Laufzeit austauschbare Implementierung willst (für Tests, Feature-Flags oder irgendetwas anderes, das während das Programm läuft entschieden wird), brauchst du trotzdem ein echtes Kotlin-interface. expect/actual kommt nur wieder ins Spiel, um die plattformspezifische Konstruktion einer Implementierung zu liefern, falls das nötig ist.
// commonMain — ein echtes Interface, kein expect/actual nötig, da es
// keinen plattformspezifischen Körper zu füllen gibt
interface Logger {
fun log(message: String)
}
class Container(private val logger: Logger)// androidMain — eine gewöhnliche Klasse, die das Interface implementiert
class AndroidLogger : Logger {
override fun log(message: String) = android.util.Log.d("App", message)
}// commonTest — FakePlatformLogger scheiterte vorhin am Typecheck, weil
// PlatformLogger final ist; FakeLogger funktioniert, weil Logger ein Interface ist
class FakeLogger : Logger {
val messages = mutableListOf<String>()
override fun log(message: String) { messages += message }
}
fun buildForTesting(): Container = Container(logger = FakeLogger())expect/actual verdient sich seinen Platz auch hier, nur eine Ebene höher: auszuwählen, welche Implementierung pro Plattform konstruiert wird, statt für das Interface selbst einzustehen.
// commonMain
expect fun providePlatformLogger(): Logger
// androidMain
actual fun providePlatformLogger(): Logger = AndroidLogger()
// iosMain
actual fun providePlatformLogger(): Logger = IosLogger()Anwendungsfälle aus der Praxis
PlatformLogger ist bewusst minimal gehalten. In produktiven KMP-Codebasen taucht expect/actual meist an denselben Nahtstellen auf – überall dort, wo geteilte Logik genau eine Plattform-Primitive braucht, um loszulegen.
Eindeutige Identifikatoren
// commonMain
expect fun randomUuid(): String
// androidMain
actual fun randomUuid(): String = java.util.UUID.randomUUID().toString()
// iosMain
actual fun randomUuid(): String = platform.Foundation.NSUUID().UUIDStringBeide Plattformen bringen bereits einen UUID-Generator mit. expect/actual gibt dem geteilten Code nur einen Namen zum Aufrufen, statt in commonMain zu verzweigen, um zwischen zwei plattformspezifischen zu wählen.
Plattforminformationen für Diagnosezwecke auslesen
// commonMain
expect fun platformName(): String
// androidMain
actual fun platformName(): String = "Android ${android.os.Build.VERSION.SDK_INT}"
// iosMain
actual fun platformName(): String =
platform.UIKit.UIDevice.currentDevice.let { "${it.systemName} ${it.systemVersion}" }Dieses Beispiel ist im Standard-Projekttemplate von Kotlin Multiplatform enthalten und wird meist in Crash-Reports oder Analytics-Events eingelesen, die wissen müssen, von welchem Betriebssystem sie stammen.
Base64-Kodierung
// commonMain
expect fun String.encodeBase64(): String
// androidMain
actual fun String.encodeBase64(): String =
android.util.Base64.encodeToString(encodeToByteArray(), android.util.Base64.NO_WRAP)
// iosMain
actual fun String.encodeBase64(): String =
(this as platform.Foundation.NSString)
.dataUsingEncoding(platform.Foundation.NSUTF8StringEncoding)!!
.base64EncodedStringWithOptions(0u)Beide Plattformen haben bereits einen Base64-Encoder in ihrer Standardbibliothek. expect/actual gibt dem geteilten Serialisierungscode nur eine Extension-Funktion zum Aufrufen, statt zwischen zweien zu verzweigen.
Wall-Clock-Zeit
// commonMain
expect fun currentTimeMillis(): Long
// androidMain
actual fun currentTimeMillis(): Long = System.currentTimeMillis()
// iosMain
actual fun currentTimeMillis(): Long =
(platform.Foundation.NSDate().timeIntervalSince1970 * 1000).toLong()Das ist das Lehrbuchbeispiel für expect/actual. Es taucht immer noch in Codebasen auf, die kotlinx-datetimes Clock.System.now() noch nicht eingebunden haben – das löst genau dasselbe Problem als portable Bibliothek statt als projektlokales expect/actual. Gleiche Form wie bei der UUID-Erzeugung: eine Stdlib-Primitive, die auf jeder Plattform unter einem anderen Namen existiert, vereinheitlicht unter einer Signatur in commonMain.
UUIDs, Plattforminformationen, Base64 und Wall-Clock-Zeit folgen alle derselben Form: eine Signatur in commonMain, ein Körper pro Plattform, aufgelöst, bevor eines der beiden Binaries existiert, weil keines von ihnen zusätzliche Konstruktor-Argumente nur auf einer Seite braucht.
Wann man expect/actual nicht verwenden sollte: sichere Credential-Speicherung
Geteilter Login-/Session-Code muss ein Token persistieren, aber wie es sicher gespeichert wird, ist von Natur aus plattformspezifisch. Androids Antwort braucht einen Context, um dorthin zu kommen, und das bricht die Form, auf die sich jedes Beispiel oben verlassen hat.
expect/actual kann einen Context nicht sauber durchreichen: Jeder actual-Konstruktor muss exakt zum expect passen, Argumente eingeschlossen, sodass ein Android-exklusiver Parameter nirgendwo hin kann. Dasselbe Interface-Muster aus dem Logger-Beispiel vorhin umgeht das Problem, statt es zu umschiffen:
// commonMain — ein schlichtes Interface, gleiche Form wie Logger: kein
// Konstruktor, der plattformübergreifend synchron gehalten werden muss,
// also überhaupt kein expect/actual nötig
interface SecureStorage {
fun save(key: String, value: String)
fun read(key: String): String?
}// androidMain — konstruiert mit Context, den das DI-Modul dieser
// Plattform zur Hand hat; unterlegt mit EncryptedSharedPreferences
class AndroidSecureStorage(private val context: Context) : SecureStorage {
private val prefs = EncryptedSharedPreferences.create(context, /* ... */)
override fun save(key: String, value: String) = prefs.edit().putString(key, value).apply()
override fun read(key: String): String? = prefs.getString(key, null)
}// iosMain — kein Context zum Durchreichen, also nichts zu umgehen;
// unterlegt mit dem Keychain
class IosSecureStorage : SecureStorage {
override fun save(key: String, value: String) { /* SecItemAdd(...) */ }
override fun read(key: String): String? = /* SecItemCopyMatching(...) */ null
}Das DI-Modul jeder Plattform (Koin, Kodein, handgebaut) bindet SecureStorage an seinen eigenen Konstruktoraufruf: AndroidSecureStorage(context) auf Android, IosSecureStorage() auf iOS. Das geteilte AuthRepository ruft einfach save(...) auf dem jeweiligen SecureStorage auf, das ihm sein DI-Graph gegeben hat, ohne jemals zu wissen, welcher Speicher dahintersteckte. Der Konstruktor keiner der beiden Plattformen wird je durch den der anderen eingeschränkt.
SecureStorage ist das Erkennungsmerkmal dafür, wann die Form von expect/actual nicht mehr passt: In dem Moment, in dem die Implementierung einer Plattform etwas braucht (einen Context, ein Handle, irgendetwas), das die andere Plattform nicht braucht, greife zum Interface, statt es durch expect/actual zu zwingen.
Das Fundamentale
Das ist Compile-Time-Polymorphismus: Es wird als Teil der Kompilierung aufgelöst, welche Implementierung eine Aufrufstelle verwendet, indem buchstäblich die richtige Deklaration in das richtige Source Set eingesetzt wird.
Das unterscheidet sich von Laufzeit-(dynamischem)-Polymorphismus, bei dem eine kompilierte Aufrufstelle ambig bleibt, bis ein -Lookup (oder ein DI-Container) eine konkrete Implementierung auswählt, während das Programm läuft.
expect/actual hat per Design null Laufzeitkosten und null Laufzeitflexibilität: Es gibt pro Kompilierung genau ein actual pro expect, ausgewählt, bevor das Binary existiert.
Deshalb kann man auch nicht zwei actuals im selben laufenden Prozess verfügbar haben, so wie man zwei Klassen haben kann, die dasselbe Interface implementieren.
Anderswo: gleiches Fundament, anderes Framework
- C/C++-Präprozessor:
#ifdef _WIN32 ... #else ... #endifwird vom Präprozessor aufgelöst, bevor der eigentliche Compiler überhaupt läuft – textuell wird ein Zweig eingesetzt und der andere gelöscht. Dieselbe „nur eine Version wird je kompiliert"-Garantie, nur auf Textebene statt auf Deklarationsebene. - Rusts
#[cfg(...)]:#[cfg(target_os = "ios")] fn platform_name() -> &'static str { "iOS" }neben einer Android-Version mit derselben Signatur wird vom Compiler pro Build-Target aufgelöst. Nur der passendecfg-Block wird je einkompiliert; die anderen existieren in diesem Binary nicht, nicht einmal als unreachable Code. - Swifts
#if os(iOS)/#if canImport(...): Compiler-Direktiven, die einen Block pro Target behalten oder verwerfen, bevor das Type-Checking passiert – dasselbe Pro-Plattform-Source-File-Muster, das KMPsiosMain/androidMain-Aufteilung spiegelt. Ein Swift-Package-Manager-Target, das ein KMP-Framework linkt, macht darunter auf seiner eigenen Seite der Grenze denselben Trick „nur eine Version dieses Symbols wurde je kompiliert". - Javas Multi-Release-JARs (
META-INF/versions/) sehen ähnlich aus, sind es aber nicht: Die JVM wählt eine Klassendatei-Version zur Klassenladezeit, basierend auf der Version der laufenden JVM, sodass ein einzelnes JAR tatsächlich mehrere kompilierte Versionen mitliefert und die Wahl auf die Laufzeit verschiebt. Das ist genau die dynamische-Polymorphismus-Form, dieexpect/actualbewusst vermeidet.
Edge Cases
Ein Target später hinzuzufügen, bringt das fehlende actual als Build-Fehler zum Vorschein, nicht als Testfehler
e: Expected class 'PlatformLogger' has no actual declaration in module
<app-wasmJsMain> for target WASMWird dem Projekt später ein neues Target hinzugefügt (sagen wir wasmJsMain) und niemand schreibt ein passendes actual, ist der Fehlschlag ein Compile-Fehler im Build dieses Targets, kein Laufzeit-Crash und kein Fehlschlag in einem Unit-Test.
Das ist leicht zu übersehen, wenn die CI nicht wirklich jedes Target baut, da die expect-Deklaration selbst in commonMain problemlos kompiliert, unabhängig davon, wie viele actuals dafür existieren.
Ein actual kann keine zusätzliche öffentliche API freilegen, die das expect nicht deklariert hat
// commonMain
expect class PlatformLogger() {
fun log(message: String)
}
// androidMain
actual class PlatformLogger {
actual fun log(message: String) { /* ... */ }
fun logWithTag(tag: String, message: String) { /* ... */ } // kompiliert hier problemlos
}
// commonMain, aufrufender Code
PlatformLogger().logWithTag("App", "hi") // unresolved referencelogWithTag kompiliert, weil androidMain eine echte Klasse ist und beliebige Member haben kann. Es ist nur von commonMain aus unsichtbar, da commonMain immer nur die Form sieht, die expect versprochen hat, nicht das, was ein bestimmtes actual zufällig hinzufügt.
Das ist der entgegengesetzte Fehler zum fehlenden-actual-Fall oben: Der Code kompiliert überall, er tut nur nicht das, was man an der Aufrufstelle erwartet hätte, an der man ihn geschrieben hat.
actual typealias überspringt einen Klassenkörper komplett, und das Matching muss trotzdem exakt sein
// commonMain
expect class PlatformDate
// jvmMain, direkt auf einen bestehenden Plattformtyp verweisend, statt
// eine Wrapper-Klasse zu schreiben
actual typealias PlatformDate = java.time.LocalDateHier gibt es überhaupt keinen actual class-Körper, java.time.LocalDate ist einfach das actual. Das ist der übliche Schritt, wenn die Plattform bereits den richtigen Typ hat und ihn zu wrappen pure Förmelei wäre. Es wird trotzdem auf dieselbe Weise aufgelöst, zur Compile-Zeit, pro Target. Das Typealias ist nur ein kürzerer Weg zur selben Substitution.
expect/actual ist Compile-Time-Substitution, kein Dispatch: Der Compiler wählt pro Target ein actual, bevor das Binary existiert, sodass es nie einen laufenden Prozess gibt, der zwischen mehr als einer Implementierung wählen könnte.



