La estructura: commonMain, los source sets y expect/actual

La estructura de un proyecto multiplataforma parece burocracia de configuración hasta que se entiende lo que realmente codifica: un sistema de visibilidad. Cada conjunto de fuentes declara, por su mera posición en la jerarquía, qué tiene derecho a ver. El conjunto común no ve Android ni iOS, y esa ceguera no es una limitación sino el mecanismo entero: es lo que garantiza que el código de dominio no pueda depender accidentalmente de un Context, y por tanto lo que hace que compile en las dos plataformas sin que nadie tenga que vigilarlo. Cuando ese código común necesita algo que solo existe en un sistema concreto, el lenguaje ofrece una salida tipada —declarar la forma en común y la implementación en cada plataforma— que resuelve el problema sin abrir la puerta a que todo lo demás se cuele por el mismo hueco.

La jerarquía de conjuntos de fuentes

Un módulo multiplataforma se organiza en conjuntos de fuentes que forman un árbol. En la raíz está commonMain, cuyo código se compila una vez por cada destino y que solo puede usar la biblioteca estándar de Kotlin y dependencias que declaren soporte multiplataforma. Debajo cuelgan los conjuntos de plataforma —androidMain, iosMain y sus variantes por arquitectura— que heredan todo lo común y añaden acceso a las interfaces nativas correspondientes. Entre medias pueden existir conjuntos intermedios, como uno que agrupe todas las variantes de Apple, para compartir código que solo tiene sentido en ese subconjunto.

flowchart TB
CM[commonMain] --> AM[androidMain]
CM --> AP[appleMain]
AP --> I1[iosArm64Main]
AP --> I2[iosSimulatorArm64Main]
CT[commonTest] --> AT[androidUnitTest]
CT --> IT[iosTest]
style CM fill:#a6e3a1,color:#11111b
style AM fill:#89b4fa,color:#11111b
style AP fill:#f9e2af,color:#11111b

La regla de visibilidad es unidireccional y no admite excepciones: un conjunto ve lo que hay por encima de él y nunca lo que hay al lado o por debajo. Desde androidMain puedes usar cualquier cosa de commonMain; desde commonMain no puedes ver nada de androidMain. Esa asimetría es lo que convierte la arquitectura en una propiedad verificada por el compilador en lugar de en una recomendación escrita en un documento que nadie lee.

// build.gradle.kts del modulo compartido
kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()

    sourceSets {
        commonMain.dependencies {
            implementation(libs.kotlinx.coroutines.core)
            implementation(libs.kotlinx.serialization.json)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
    }
}

Merece atención el conjunto intermedio, porque resuelve un problema que aparece pronto y que sin él obliga a duplicar ficheros. Los destinos de Apple son varios —dispositivo, simulador, arquitecturas distintas— y comparten prácticamente todo su código de plataforma. Agruparlos bajo un conjunto común a todos ellos permite escribir una sola vez lo que de otro modo habría que copiar tres veces, con la garantía de que las tres copias no puedan divergir por el simple hecho de que no existen.

Conviene notar que el conjunto de tests replica la misma jerarquía. Un test escrito en commonTest se ejecuta una vez por destino, de modo que la misma suite valida la lógica compartida tanto sobre la máquina virtual de Android como sobre el binario nativo de iOS. Ese detalle, que parece menor, es en la práctica una de las razones más sólidas para adoptar el enfoque: los desacuerdos entre plataformas dejan de descubrirse en producción.

Declaraciones esperadas y reales

Cuando el código común necesita algo que no existe en la biblioteca estándar, se declara su forma con expect y se proporciona una implementación con actual en cada conjunto de plataforma. El compilador verifica que exista exactamente una implementación por destino y que la firma coincida; si falta una, el proyecto no compila.

// commonMain
expect class Almacen {
    fun guardar(clave: String, valor: String)
    fun leer(clave: String): String?
}

expect fun identificadorDeDispositivo(): String

// androidMain
actual class Almacen(private val prefs: android.content.SharedPreferences) {
    actual fun guardar(clave: String, valor: String) {
        prefs.edit().putString(clave, valor).apply()
    }
    actual fun leer(clave: String): String? = prefs.getString(clave, null)
}

El detalle que suele pasarse por alto es el del constructor. Una clase esperada no puede exigir parámetros que solo una plataforma necesita, de modo que la implementación de Android acaba requiriendo un objeto que el código común no puede construir. Ese roce es real y tiene dos salidas: declarar la parte esperada como interfaz y crear la instancia en el arranque de cada aplicación, o recurrir a alguna forma de inicialización por plataforma. La primera es más limpia casi siempre.

La alternativa preferible: interfaz en común, implementación inyectada

En la mayoría de los casos, lo que se necesita no es una construcción del lenguaje sino una abstracción ordinaria. Se define una interfaz en commonMain, cada plataforma la implementa en su propio conjunto de fuentes, y el objeto se entrega al container por constructor. El resultado es indistinguible desde el punto de vista del código común, pero mucho mejor desde el punto de vista de las pruebas y de la evolución.

// commonMain
interface Reloj { fun ahora(): Long }
interface Almacen {
    suspend fun guardar(clave: String, valor: String)
    suspend fun leer(clave: String): String?
}

class SesionContainer(
    private val almacen: Almacen,
    private val reloj: Reloj,
)

Hay un segundo motivo, menos obvio pero igual de decisivo: la interfaz admite más de una implementación por plataforma. Una declaración esperada fija exactamente una realización por destino, de modo que si mañana necesitas dos almacenes distintos en Android —uno cifrado y otro no— el mecanismo se te queda corto y hay que rehacerlo. Con una interfaz, es simplemente otra clase que implementa el mismo contrato y otra línea en el grafo de dependencias.

La ventaja decisiva es la sustituibilidad. Una interfaz admite un doble de prueba trivial en commonTest; una declaración esperada, no, porque el compilador ya ha fijado cuál es la implementación real de cada destino y no hay forma de interponer otra sin acrobacias. Como el objetivo del reparto era precisamente poder probar la política una sola vez, cualquier mecanismo que dificulte esa prueba se paga en el sitio equivocado.