Ce qu'est vraiment expect/actual
expect/actual est le mécanisme de Kotlin Multiplatform permettant d'écrire
une seule déclaration dans le code partagé et de lui donner un corps différent
par plateforme.
- Une déclaration
expectvit danscommonMain. Elle déclare la signature d'une classe, d'une fonction ou d'une propriété sans corps, une promesse qu'une implémentation correspondante existe pour chaque plateforme que le projet compile. - Une déclaration
actualvit dans un de plateforme, tel queandroidMainouiosMain, et tient cette promesse avec l'implémentation réelle pour cette seule plateforme. - Le compilateur vérifie que chaque
expecta unactualcorrespondant pour chaque cible compilée, et fait échouer le build si l'un manque.
C'est le contrat. Ce qu'il ne précise pas, c'est quand cette correspondance se produit, et c'est là que le modèle mental part généralement de travers.
L'intuition
expect/actual se lit comme une interface avec des implémentations par
plateforme : définir une interface, injecter une implémentation différente
sur Android par rapport à iOS. Cette image découle naturellement de
l'injection de dépendances. Elle est fausse d'une manière précise.
- Une interface n'a qu'une seule forme compilée, et quelle implémentation
s'exécute est décidé à
,
par ce que le graphe de DI (ou un simple
if) vous fournit. - Une déclaration
expectn'a aucune forme compilée propre. Chaque cible compile commonMain contre son propreactualcorrespondant, intégré, avant même que le binaire existe. - Il n'y a jamais de moment où l'
actualAndroid et l'actualiOS existent tous les deux dans le même artefact compilé. Le build de chaque cible ne voit jamais qu'un seul des deux, celui qui estactualpour elle.
Donc « échanger l'implémentation » se produit à la compilation, par source set, pas à l'exécution dans un processus en cours. Il n'y a rien à échanger une fois qu'un binaire existe, parce que rien d'autre n'y a jamais été compilé.
Un logger plateforme, la méthode évidente
// 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() est écrit une seule fois dans commonMain et appelle
PlatformLogger().log(...) sans savoir sur quelle plateforme il s'exécutera.
Cette partie ressemble effectivement à un appel via une interface.
La différence apparaît dans ce que le build Android compile réellement :
- Il ne voit jamais la
actual class PlatformLoggerdeiosMain, ni comme code mort, ni comme branche inutilisée, ni compilée nulle part. - L'unité de compilation Android est uniquement
commonMain+androidMain, avec chaqueexpectrésolu directement vers sonactualandroidMainavant que la génération de code n'ait lieu.
Remplacez androidMain par iosMain et vous obtenez un binaire différent,
compilé séparément, pas un chemin d'exécution différent à travers le même
binaire.
Essayer de choisir un actual à l'exécution ne passe pas la vérification de types
// ❌ il n'y a pas d'"interface" PlatformLogger à laquelle garder une référence ;
// les déclarations expect ne sont pas un type qu'on peut remplacer derrière une variable
class Container(private val logger: PlatformLogger)
fun buildForTesting(): Container {
// essayer d'injecter une implémentation factice comme on le ferait
// pour une véritable interface
return Container(logger = FakePlatformLogger()) // erreur de compilation :
// FakePlatformLogger n'est pas un sous-type de PlatformLogger : les
// classes sont final par défaut en Kotlin sauf si marquées open, et
// cette paire expect/actual ne se marque pas open
}C'est l'erreur vers laquelle le modèle mental de la DI conduit directement :
se tourner vers expect/actual pour obtenir une implémentation
factice/interchangeable pour les tests, de la même manière qu'on
remplacerait une interface Repository par un FakeRepository.
PlatformLogger ne peut pas être sous-classé ici, mais c'est un
comportement Kotlin ordinaire (les classes sont final sauf si marquées
open), pas quelque chose qu'expect/actual invente. Marquer
expect open class PlatformLogger() ne sauverait pas non plus ce cas
d'usage de DI : cela permettrait de sous-classer la seule classe actual
qui a fini dans le binaire de cette cible, pas de basculer entre
l'implémentation Android et une factice au même point d'appel. Open ou
non, on n'a jamais qu'un seul type PlatformLogger par compilation.
Si vous voulez une implémentation interchangeable à l'exécution (pour les
tests, les feature flags, ou toute autre chose décidée pendant que le
programme s'exécute), il vous faut toujours une véritable interface
Kotlin. expect/actual ne revient en jeu que pour fournir la
construction spécifique à la plateforme d'une implémentation, si
nécessaire.
// commonMain — une véritable interface, pas besoin d'expect/actual puisqu'elle n'a
// aucun corps spécifique à une plateforme à remplir
interface Logger {
fun log(message: String)
}
class Container(private val logger: Logger)// androidMain — une classe ordinaire qui implémente l'interface
class AndroidLogger : Logger {
override fun log(message: String) = android.util.Log.d("App", message)
}// commonTest — FakePlatformLogger échouait au typecheck plus haut parce que
// PlatformLogger était final ; FakeLogger fonctionne parce que Logger est une interface
class FakeLogger : Logger {
val messages = mutableListOf<String>()
override fun log(message: String) { messages += message }
}
fun buildForTesting(): Container = Container(logger = FakeLogger())expect/actual conserve toute sa pertinence ici, mais à un niveau
au-dessus : choisir quelle implémentation est construite par plateforme,
sans se substituer à l'interface elle-même.
// commonMain
expect fun providePlatformLogger(): Logger
// androidMain
actual fun providePlatformLogger(): Logger = AndroidLogger()
// iosMain
actual fun providePlatformLogger(): Logger = IosLogger()Cas d'usage réels
PlatformLogger est volontairement minimal. Dans les bases de code KMP en
production, expect/actual tend à apparaître sur les mêmes quelques
points de jonction, partout où la logique partagée a besoin d'exactement
une primitive plateforme pour démarrer.
Identifiants uniques
// commonMain
expect fun randomUuid(): String
// androidMain
actual fun randomUuid(): String = java.util.UUID.randomUUID().toString()
// iosMain
actual fun randomUuid(): String = platform.Foundation.NSUUID().UUIDStringLes deux plateformes fournissent déjà un générateur d'UUID.
expect/actual donne simplement au code partagé un seul nom à appeler,
plutôt que de brancher sur la plateforme à l'intérieur de commonMain pour
choisir entre deux fonctions spécifiques à la plateforme.
Lire les informations de la plateforme pour le diagnostic
// 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}" }Celui-ci est fourni dans le modèle de projet Kotlin Multiplatform par défaut, généralement lu dans des rapports de crash ou des événements analytics qui doivent savoir de quel OS ils viennent.
Encodage Base64
// 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)Les deux plateformes disposent déjà d'un encodeur Base64 dans leur
bibliothèque standard. expect/actual donne simplement au code de
sérialisation partagé une seule fonction d'extension à appeler au lieu de
brancher entre les deux.
Horloge murale
// commonMain
expect fun currentTimeMillis(): Long
// androidMain
actual fun currentTimeMillis(): Long = System.currentTimeMillis()
// iosMain
actual fun currentTimeMillis(): Long =
(platform.Foundation.NSDate().timeIntervalSince1970 * 1000).toLong()C'est l'exemple classique d'expect/actual des manuels. Il apparaît
encore dans des bases de code qui n'ont pas encore adopté
Clock.System.now() de kotlinx-datetime, qui résout exactement le même
problème sous forme de bibliothèque portable plutôt que d'expect/actual
local au projet. Même forme que la génération d'UUID : une primitive de
bibliothèque standard qui existe sur chaque plateforme sous un nom
différent, unifiée sous une seule signature commonMain.
UUID, informations plateforme, Base64 et horloge murale suivent tous la même forme : une signature dans commonMain, un corps par plateforme, résolus avant qu'aucun des deux binaires n'existe, parce qu'aucun d'eux n'a besoin d'arguments de constructeur supplémentaires sur un seul côté.
Quand ne pas utiliser expect/actual : le stockage sécurisé d'identifiants
Le code de connexion/session partagé doit persister un token, mais la
façon dont il est stocké de manière sécurisée est intrinsèquement
spécifique à la plateforme. La réponse d'Android a besoin d'un Context
pour y arriver, ce qui brise la forme sur laquelle reposait chaque exemple
précédent.
expect/actual ne peut pas faire passer un Context proprement : chaque
constructeur actual doit correspondre exactement à celui de l'expect,
arguments compris, donc un paramètre propre à Android n'a nulle part où
aller. Le même modèle d'interface que dans l'exemple du Logger ci-dessus
contourne le problème plutôt que d'essayer de le forcer :
// commonMain — une simple interface, même forme que Logger : pas de constructeur
// à synchroniser entre plateformes, donc pas besoin d'expect/actual du tout
interface SecureStorage {
fun save(key: String, value: String)
fun read(key: String): String?
}// androidMain — construit avec Context, que le module DI de cette
// plateforme a sous la main ; adossé à 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 — pas de Context à faire transiter, donc rien à contourner ;
// adossé au Keychain
class IosSecureStorage : SecureStorage {
override fun save(key: String, value: String) { /* SecItemAdd(...) */ }
override fun read(key: String): String? = /* SecItemCopyMatching(...) */ null
}Le module de DI de chaque plateforme (Koin, Kodein, fait main) lie
SecureStorage à son propre appel de constructeur : AndroidSecureStorage(context)
sur Android, IosSecureStorage() sur iOS. L'AuthRepository partagé se
contente d'appeler save(...) sur le SecureStorage que son graphe de DI
lui a fourni, sans jamais savoir quel était le stockage sous-jacent. Le
constructeur d'aucune plateforme n'est jamais contraint par celui de
l'autre.
SecureStorage est le signal qui indique que la forme d'expect/actual
ne convient plus : au moment où l'implémentation d'une plateforme a besoin
de quelque chose (un Context, un handle, n'importe quoi) que l'autre
plateforme n'a pas, tournez-vous vers l'interface plutôt que de forcer le
passage par expect/actual.
Le principe fondamental
C'est du polymorphisme à la compilation : résoudre quelle implémentation un point d'appel utilise dans le cadre de la compilation, en substituant littéralement la bonne déclaration dans le bon source set.
C'est différent du polymorphisme à l'exécution (dynamique), où un point d'appel compilé unique reste ambigu jusqu'à ce qu'une recherche dans la (ou un conteneur de DI) choisisse une implémentation concrète pendant que le programme s'exécute.
expect/actual a un coût d'exécution nul et une flexibilité d'exécution
nulle, par conception : il n'y a exactement qu'un seul actual par
expect par compilation, choisi avant que le binaire n'existe.
C'est aussi pourquoi vous ne pouvez pas avoir deux actuals disponibles dans le même processus en cours d'exécution, comme vous pourriez avoir deux classes implémentant la même interface.
Ailleurs : même principe fondamental, framework différent
- Préprocesseur C/C++ :
#ifdef _WIN32 ... #else ... #endifest résolu par le préprocesseur avant même que le compilateur proprement dit ne s'exécute, substituant textuellement une branche et supprimant l'autre. La même garantie « une seule version est jamais compilée », simplement au niveau du texte plutôt qu'au niveau de la déclaration. #[cfg(...)]de Rust :#[cfg(target_os = "ios")] fn platform_name() -> &'static str { "iOS" }à côté d'une version Android avec la même signature est résolu par le compilateur par cible de build. Seul le bloccfgcorrespondant est jamais compilé ; les autres n'existent pas dans ce binaire, pas même comme code inaccessible.#if os(iOS)/#if canImport(...)de Swift : des directives de compilation qui conservent ou suppriment un bloc par cible avant que le typage n'ait lieu, le même modèle de fichier source par plateforme que reflète la séparationiosMain/androidMainde KMP. Une cible Swift Package Manager qui lie un framework KMP fait, en dessous, exactement le même tour « une seule version de ce symbole n'a jamais été compilée » de son propre côté de la frontière.- Les JAR multi-release de Java (
META-INF/versions/) semblent similaires mais ne le sont pas : la JVM choisit une version de fichier de classe au chargement de la classe, en fonction de la version de la JVM en cours d'exécution, donc un seul JAR expédie véritablement plusieurs versions compilées et reporte le choix à l'exécution. C'est exactement la forme de polymorphisme dynamique qu'expect/actualévite délibérément.
Cas limites
Ajouter une cible plus tard révèle l'actual manquant comme une erreur de build, pas comme un échec de test
e: Expected class 'PlatformLogger' has no actual declaration in module
<app-wasmJsMain> for target WASMSi une nouvelle cible est ajoutée au projet (disons wasmJsMain) et que
personne n'écrit l'actual correspondant, l'échec est une erreur de
compilation sur le build de cette cible, pas un crash à l'exécution ni un
échec de test unitaire.
C'est facile à manquer si la CI ne compile pas réellement chaque cible,
puisque la déclaration expect elle-même se compile sans problème dans
commonMain, quel que soit le nombre d'actual existant pour elle.
Un actual ne peut pas exposer d'API publique supplémentaire que l'expect n'a pas déclarée
// commonMain
expect class PlatformLogger() {
fun log(message: String)
}
// androidMain
actual class PlatformLogger {
actual fun log(message: String) { /* ... */ }
fun logWithTag(tag: String, message: String) { /* ... */ } // se compile sans problème ici
}
// commonMain, code appelant
PlatformLogger().logWithTag("App", "hi") // référence non résoluelogWithTag se compile parce que androidMain est une vraie classe et
peut avoir les membres qu'elle veut. Elle est simplement invisible depuis
commonMain, puisque commonMain ne voit jamais que la forme promise par
expect, pas ce qu'un actual particulier ajoute par ailleurs.
C'est l'échec inverse du cas de l'actual manquant ci-dessus : le code se compile partout, il ne fait simplement pas ce qu'on attendait depuis le point d'appel où on l'a écrit.
actual typealias évite entièrement un corps de classe, et la correspondance doit tout de même être exacte
// commonMain
expect class PlatformDate
// jvmMain, aliasé directement vers un type de plateforme existant plutôt
// que d'écrire une classe wrapper
actual typealias PlatformDate = java.time.LocalDateAucun corps actual class ici, java.time.LocalDate est simplement
l'actual. C'est la solution habituelle quand la plateforme possède déjà
le bon type et qu'envelopper celui-ci serait de la pure cérémonie. C'est
toujours résolu de la même manière, à la compilation, par cible. Le
typealias est simplement un chemin plus court vers la même substitution.
expect/actual est une substitution à la compilation, pas du dispatch :
le compilateur choisit un actual par cible avant que le binaire n'existe,
donc il n'y a jamais de processus en cours d'exécution détenant plus d'une
implémentation entre lesquelles choisir.



