O que expect/actual realmente é
expect/actual é o mecanismo do Kotlin Multiplatform para escrever uma
declaração no código compartilhado e dar a ela um corpo diferente por plataforma.
- Uma declaração
expectvive emcommonMain. Ela declara a assinatura de uma classe, função ou propriedade sem corpo, uma promessa de que existe uma implementação correspondente para cada plataforma que o projeto compila. - Uma declaração
actualvive em um de plataforma, comoandroidMainouiosMain, e cumpre essa promessa com a implementação real para aquela única plataforma. - O compilador verifica que todo
expecttem umactualcorrespondente para cada alvo que está sendo compilado, e falha o build se algum estiver faltando.
Esse é o contrato. O que ele não diz é quando essa correspondência acontece, e é aí que o modelo mental geralmente vai por caminhos errados.
A intuição
expect/actual parece uma interface com implementações por plataforma:
defina uma interface, injete uma implementação diferente no Android vs. iOS.
Essa imagem vem naturalmente da injeção de dependência. Ela está errada
de uma forma específica.
- Uma interface tem exatamente uma forma compilada, e qual implementação
é executada é decidido em
,
pelo que o grafo de DI (ou um simples
if) entregar a você. - Uma declaração
expectnão tem forma compilada própria alguma. Todo alvo compila o commonMain contra seu próprioactualcorrespondente, já embutido, antes de o binário existir. - Nunca há um momento em que tanto o
actualdo Android quanto oactualdo iOS existam no mesmo artefato compilado. O build de cada alvo só vê um deles, aquele que éactualpara ele.
Então "trocar a implementação" acontece em tempo de compilação, por source set, não em tempo de execução dentro de um processo em execução. Não há nada para trocar quando um binário já existe, porque nada mais foi compilado nele.
Um logger de plataforma, da forma óbvia
// 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() é escrita uma vez em commonMain e chama PlatformLogger().log(...)
sem saber em qual plataforma vai rodar. Essa parte realmente parece
chamar através de uma interface.
A diferença aparece no que o build do Android de fato compila:
- Ele nunca vê o
actual class PlatformLoggerdoiosMain, nem mesmo como código morto, nem como um branch não usado, não compilado em lugar nenhum. - A unidade de compilação do Android é apenas
commonMain+androidMain, com todoexpectnela resolvido diretamente para seuactualemandroidMainantes de a geração de código acontecer.
Troque androidMain por iosMain e você obtém um binário diferente,
compilado separadamente, não um caminho de execução diferente através
do mesmo binário.
Tentar escolher um actual em tempo de execução não passa pela checagem de tipos
// ❌ não existe uma "interface" PlatformLogger para manter uma referência;
// declarações expect não são um tipo que você pode trocar por trás de uma variável
class Container(private val logger: PlatformLogger)
fun buildForTesting(): Container {
// tentando injetar uma implementação falsa da forma que você faria
// para uma interface real
return Container(logger = FakePlatformLogger()) // erro de compilação:
// FakePlatformLogger não é um subtipo de PlatformLogger: classes
// são final por padrão no Kotlin a menos que marcadas open, e esse
// par expect/actual não se marca como open
}Esse é o erro para o qual o modelo mental de DI leva diretamente: recorrer
a expect/actual para obter uma implementação falsa/trocável para
testes, da mesma forma que você trocaria uma interface Repository por
um FakeRepository. PlatformLogger não pode ser subclassificado aqui,
mas isso é comportamento comum do Kotlin (classes são final a menos que
marcadas open), não algo que expect/actual inventa. Marcar
expect open class PlatformLogger() também não resolveria o caso de uso
de DI: isso permitiria subclassificar a única classe actual que entrou
no binário daquele alvo, não trocar entre a implementação do Android e
uma falsa no mesmo ponto de chamada. Open ou não, você sempre tem apenas
um tipo PlatformLogger por compilação.
Se você quer uma implementação trocável em tempo de execução (para testes,
feature flags, ou qualquer outra coisa decidida enquanto o programa está
em execução), você ainda precisa de uma interface Kotlin real.
expect/actual só volta à cena para fornecer a construção específica
de plataforma de uma implementação, se isso for necessário.
// commonMain — uma interface real, sem necessidade de expect/actual, já que
// não tem corpo específico de plataforma para preencher
interface Logger {
fun log(message: String)
}
class Container(private val logger: Logger)// androidMain — uma classe comum implementando a interface
class AndroidLogger : Logger {
override fun log(message: String) = android.util.Log.d("App", message)
}// commonTest — FakePlatformLogger falhou na checagem de tipos antes porque
// PlatformLogger era final; FakeLogger funciona porque Logger é uma interface
class FakeLogger : Logger {
val messages = mutableListOf<String>()
override fun log(message: String) { messages += message }
}
fun buildForTesting(): Container = Container(logger = FakeLogger())expect/actual ainda ganha seu lugar aqui, só um nível acima: escolhendo
qual implementação é construída por plataforma, não substituindo a
própria interface.
// commonMain
expect fun providePlatformLogger(): Logger
// androidMain
actual fun providePlatformLogger(): Logger = AndroidLogger()
// iosMain
actual fun providePlatformLogger(): Logger = IosLogger()Casos de uso do mundo real
PlatformLogger é deliberadamente mínimo. Em bases de código KMP de
produção, expect/actual tende a aparecer nas mesmas poucas costuras,
onde quer que a lógica compartilhada precise de exatamente uma primitiva
de plataforma para começar.
Identificadores únicos
// commonMain
expect fun randomUuid(): String
// androidMain
actual fun randomUuid(): String = java.util.UUID.randomUUID().toString()
// iosMain
actual fun randomUuid(): String = platform.Foundation.NSUUID().UUIDStringAmbas as plataformas já vêm com um gerador de UUID. expect/actual
apenas dá ao código compartilhado um nome para chamar, em vez de
ramificar com base na plataforma dentro do commonMain para escolher
entre dois específicos de plataforma.
Lendo informações de plataforma para diagnóstico
// 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}" }Este vem no template padrão de projeto Kotlin Multiplatform, geralmente lido em relatórios de crash ou eventos de analytics que precisam saber de qual SO vieram.
Codificação 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)Ambas as plataformas já têm um codificador Base64 em sua biblioteca
padrão. expect/actual apenas dá ao código de serialização
compartilhado uma função de extensão para chamar em vez de ramificar
entre duas.
Tempo do relógio (wall-clock)
// commonMain
expect fun currentTimeMillis(): Long
// androidMain
actual fun currentTimeMillis(): Long = System.currentTimeMillis()
// iosMain
actual fun currentTimeMillis(): Long =
(platform.Foundation.NSDate().timeIntervalSince1970 * 1000).toLong()Este é o exemplo clássico de expect/actual dos livros. Ele ainda
aparece em bases de código que não adotaram Clock.System.now() do
kotlinx-datetime, que resolve exatamente o mesmo problema como uma
biblioteca portável em vez de um expect/actual local ao projeto.
Mesma forma da geração de UUID: uma primitiva da stdlib que existe em
toda plataforma sob um nome diferente, unificada sob uma única
assinatura no commonMain.
UUIDs, informações de plataforma, Base64 e tempo do relógio todos seguem a mesma forma: uma assinatura no commonMain, um corpo por plataforma, resolvido antes de qualquer um dos binários existir, porque nenhum deles precisa de argumentos extras de construtor em apenas um dos lados.
Quando não usar expect/actual: armazenamento seguro de credenciais
O código compartilhado de login/sessão precisa persistir um token, mas
como ele é armazenado de forma segura é inerentemente específico de
plataforma. A resposta do Android precisa de um Context para chegar
lá, e isso quebra a forma que cada exemplo acima dependia.
expect/actual não consegue passar um Context de forma limpa: todo
construtor actual precisa corresponder exatamente ao do expect,
argumentos e tudo, então um parâmetro só do Android não tem para onde
ir. O mesmo padrão de interface do exemplo do Logger anterior evita o
problema em vez de contorná-lo:
// commonMain — uma interface simples, mesma forma que Logger: nenhum
// construtor para manter sincronizado entre plataformas, então nenhum
// expect/actual é necessário
interface SecureStorage {
fun save(key: String, value: String)
fun read(key: String): String?
}// androidMain — construído com Context, que o módulo de DI desta
// plataforma tem disponível; apoiado por 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 — nenhum Context para passar, então nada para contornar;
// apoiado pelo Keychain
class IosSecureStorage : SecureStorage {
override fun save(key: String, value: String) { /* SecItemAdd(...) */ }
override fun read(key: String): String? = /* SecItemCopyMatching(...) */ null
}O módulo de DI de cada plataforma (Koin, Kodein, feito à mão) vincula
SecureStorage à sua própria chamada de construtor:
AndroidSecureStorage(context) no Android, IosSecureStorage() no iOS.
O AuthRepository compartilhado apenas chama save(...) em qualquer
SecureStorage que seu grafo de DI tenha entregado, nunca sabendo qual
foi o armazenamento subjacente. O construtor de nenhuma das plataformas
é restringido pelo do outro.
SecureStorage é o sinal de quando a forma de expect/actual deixa
de se encaixar: no momento em que a implementação de uma plataforma
precisa de algo (um Context, um handle, qualquer coisa) que a outra
plataforma não tem, recorra à interface em vez de forçar via
expect/actual.
O fundamento
Isso é polimorfismo em tempo de compilação: resolver qual implementação um ponto de chamada usa como parte da compilação, substituindo literalmente a declaração certa no source set certo.
Isso é diferente do polimorfismo em tempo de execução (dinâmico), onde um ponto de chamada compilado permanece ambíguo até que uma busca em (ou um container de DI) escolha uma implementação concreta enquanto o programa está em execução.
expect/actual tem custo zero em tempo de execução e flexibilidade zero
em tempo de execução por design: existe exatamente um actual por
expect por compilação, escolhido antes de o binário existir.
É também por isso que você não pode ter dois actuals disponíveis no mesmo processo em execução da forma que você pode ter duas classes implementando a mesma interface.
Em outros lugares: o mesmo fundamento, framework diferente
- Pré-processador C/C++:
#ifdef _WIN32 ... #else ... #endifé resolvido pelo pré-processador antes mesmo de o compilador propriamente dito rodar, substituindo textualmente um ramo e apagando o outro. Mesma garantia de "só uma versão é compilada", só que no nível do texto em vez do nível da declaração. #[cfg(...)]do Rust:#[cfg(target_os = "ios")] fn platform_name() -> &'static str { "iOS" }junto com uma versão Android com a mesma assinatura é resolvido pelo compilador por alvo de build. Apenas o blococfgcorrespondente é compilado; os outros não existem naquele binário, nem mesmo como código inalcançável.#if os(iOS)/#if canImport(...)do Swift: diretivas de compilador que mantêm ou descartam um bloco por alvo antes de a checagem de tipos acontecer, o mesmo padrão de arquivo-fonte-por-plataforma que a divisãoiosMain/androidMaindo KMP espelha. Um alvo do Swift Package Manager que vincula um framework KMP está, por baixo, fazendo o mesmo truque de "só uma versão deste símbolo foi compilada" em seu próprio lado da fronteira.- JARs multi-release do Java (
META-INF/versions/) parecem semelhantes, mas não são: a JVM escolhe uma versão de arquivo de classe em tempo de carregamento de classe, com base na versão da JVM em execução, então um único JAR genuinamente envia múltiplas versões compiladas e adia a escolha para o tempo de execução. Essa é a forma de polimorfismo dinâmico queexpect/actualdeliberadamente evita.
Casos de borda
Adicionar um alvo depois faz o actual faltante aparecer como erro de build, não como falha de teste
e: Expected class 'PlatformLogger' has no actual declaration in module
<app-wasmJsMain> for target WASMSe um novo alvo for adicionado ao projeto (digamos, wasmJsMain) e
ninguém escrever um actual correspondente, a falha é um erro de
compilação no build daquele alvo, não um crash em tempo de execução e
não uma falha de teste unitário.
É fácil não perceber isso se o CI não compila de fato todos os alvos,
já que a declaração expect em si compila sem problemas no commonMain
independentemente de quantos actuals existam para ela.
Um actual não pode expor API pública extra que o expect não declarou
// commonMain
expect class PlatformLogger() {
fun log(message: String)
}
// androidMain
actual class PlatformLogger {
actual fun log(message: String) { /* ... */ }
fun logWithTag(tag: String, message: String) { /* ... */ } // compila bem aqui
}
// commonMain, código que chama
PlatformLogger().logWithTag("App", "hi") // referência não resolvidalogWithTag compila porque androidMain é uma classe real e pode ter
quaisquer membros que quiser. Ela só é invisível a partir do
commonMain, já que o commonMain só vê a forma que o expect prometeu,
não o que um actual específico por acaso adiciona.
Essa é a falha oposta ao caso do actual faltante acima: o código compila em todos os lugares, só não faz o que você esperava a partir do ponto de chamada em que o escreveu.
actual typealias ignora completamente um corpo de classe, e a correspondência ainda precisa ser exata
// commonMain
expect class PlatformDate
// jvmMain, apontando diretamente para um tipo de plataforma existente
// em vez de escrever uma classe wrapper
actual typealias PlatformDate = java.time.LocalDateNenhum corpo de actual class aqui, java.time.LocalDate simplesmente
é o actual. Essa é a jogada usual quando a plataforma já tem o tipo
certo e envolvê-lo seria pura cerimônia. Ainda é resolvido da mesma
forma, em tempo de compilação, por alvo. O typealias é apenas um caminho
mais curto para a mesma substituição.
expect/actual é substituição em tempo de compilação, não despacho: o
compilador escolhe um actual por alvo antes de o binário existir, então
nunca há um processo em execução mantendo mais de uma implementação
entre as quais escolher.



