Recomposed
Multiplatform

expect/actual do Kotlin: Uma Interface em Tempo de Compilação, Não em Tempo de Execução

Oct 29, 2026 · 10 min read

expect/actual do Kotlin: Uma Interface em Tempo de Compilação, Não em Tempo de Execução

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 expect vive em commonMain. 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 actual vive em um de plataforma, como androidMain ou iosMain, e cumpre essa promessa com a implementação real para aquela única plataforma.
  • O compilador verifica que todo expect tem um actual correspondente 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 expect não tem forma compilada própria alguma. Todo alvo compila o commonMain contra seu próprio actual correspondente, já embutido, antes de o binário existir.
  • Nunca há um momento em que tanto o actual do Android quanto o actual do iOS existam no mesmo artefato compilado. O build de cada alvo só vê um deles, aquele que é actual para 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 PlatformLogger do iosMain, 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 todo expect nela resolvido diretamente para seu actual em androidMain antes 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.

FIG. 01
A compilação de cada alvo só traz commonMain mais seu próprio actual; o binário do Android nunca contém o actual do iOS, e vice-versa

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

Ambas 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 bloco cfg correspondente é 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ão iosMain/androidMain do 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 que expect/actual deliberadamente 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 WASM

Se 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 resolvida

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

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

Keep reading

Related reads

Receba novos posts no seu e-mail