Recomposed
Multiplatform

expect/actual en Kotlin : une interface à la compilation, pas à l'exécution

Oct 29, 2026 · 10 min read

expect/actual en Kotlin : une interface à la compilation, pas à l'exécution

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 expect vit dans commonMain. 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 actual vit dans un de plateforme, tel que androidMain ou iosMain, et tient cette promesse avec l'implémentation réelle pour cette seule plateforme.
  • Le compilateur vérifie que chaque expect a un actual correspondant 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 expect n'a aucune forme compilée propre. Chaque cible compile commonMain contre son propre actual correspondant, intégré, avant même que le binaire existe.
  • Il n'y a jamais de moment où l'actual Android et l'actual iOS 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 est actual pour 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 PlatformLogger de iosMain, ni comme code mort, ni comme branche inutilisée, ni compilée nulle part.
  • L'unité de compilation Android est uniquement commonMain + androidMain, avec chaque expect résolu directement vers son actual androidMain avant 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.

FIG. 01
La compilation de chaque cible ne récupère jamais que commonMain plus son propre actual ; le binaire Android ne contient jamais l'actual iOS, et vice versa

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().UUIDString

Les 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 ... #endif est 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 bloc cfg correspondant 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éparation iosMain/androidMain de 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 WASM

Si 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ésolue

logWithTag 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.LocalDate

Aucun 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.

Keep reading

Related reads

Recevez les nouveaux articles par e-mail