expect/actual는 실제로 무엇인가
expect/actual는 공유 코드에서 하나의 선언을 작성하고, 플랫폼별로 다른 본문을
부여할 수 있게 해주는 코틀린 멀티플랫폼의 메커니즘이다.
expect선언은commonMain에 위치한다. 본문 없이 클래스, 함수, 프로퍼티의 시그니처만 선언하며, 프로젝트가 빌드하는 모든 플랫폼에 대해 그에 대응하는 구현이 존재한다는 약속이다.actual선언은 플랫폼 , 즉androidMain이나iosMain같은 곳에 위치하며, 해당 플랫폼에 대한 실제 구현으로 그 약속을 이행한다.- 컴파일러는 빌드하는 각 타겟에 대해 모든
expect에 대응하는actual이 존재하는지 확인하며, 하나라도 없으면 빌드를 실패시킨다.
이것이 계약이다. 하지만 이 설명이 말해주지 않는 것은 그 매칭이 언제 일어나는지이며, 바로 여기서 사고 모델이 흔히 어긋난다.
직관
expect/actual는 플랫폼별 구현을 가진 인터페이스처럼 읽힌다: 인터페이스를
정의하고, Android와 iOS에 각기 다른 구현을 주입한다. 이 그림은 의존성 주입에서
자연스럽게 넘어온 것이다. 하지만 이는 특정한 방식으로 틀렸다.
- 인터페이스는 정확히 하나의 컴파일된 형태를 가지며, 어떤 구현이 실행되는지는
에,
DI 그래프(또는 단순한
if)가 무엇을 건네주는지에 따라 결정된다. expect선언은 그 자체의 컴파일된 형태를 전혀 갖지 않는다. 각 타겟은 바이너리가 존재하기 전에, 이미 그 안에 녹아든 자신만의 대응actual을 기준으로 commonMain을 컴파일한다.- Android
actual과 iOSactual이 동시에 같은 컴파일 결과물 안에 존재하는 순간은 결코 없다. 각 타겟의 빌드는 오직 자신에게 해당하는actual하나만을 본다.
따라서 "구현을 교체한다"는 것은 실행 중인 프로세스 안에서 런타임에 일어나는 일이 아니라, 소스 세트별로 컴파일 타임에 일어나는 일이다. 바이너리가 만들어진 이후에는 교체할 것이 아무것도 없다. 애초에 그 안에는 다른 것이 컴파일된 적이 없기 때문이다.
플랫폼 로거, 당연한 방식
// 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()는 commonMain에 단 한 번만 작성되며, 자신이 어느 플랫폼에서 실행될지
모른 채 PlatformLogger().log(...)를 호출한다. 이 부분만 보면 인터페이스를
통해 호출하는 것처럼 보인다.
차이는 Android 빌드가 실제로 무엇을 컴파일하는지에서 드러난다:
- Android 빌드는
iosMain의actual class PlatformLogger를 전혀 보지 못한다. 죽은 코드로도, 사용되지 않는 분기로도, 어디에도 컴파일되지 않는다. - Android 컴파일 단위는 오직
commonMain+androidMain뿐이며, 그 안의 모든expect는 코드 생성이 일어나기 전에 해당androidMain의actual로 직접 해석된다.
androidMain을 iosMain으로 바꾸면 다른, 별도로 컴파일된 바이너리가 만들어지는
것이지, 같은 바이너리 안에서 다른 런타임 경로를 타는 것이 아니다.
런타임에 actual을 고르려고 하면 타입체크를 통과하지 못한다
// ❌ 참조를 들고 있을 PlatformLogger "인터페이스" 같은 건 없다;
// expect 선언은 변수 뒤에서 교체할 수 있는 타입이 아니다
class Container(private val logger: PlatformLogger)
fun buildForTesting(): Container {
// 진짜 인터페이스였다면 그렇게 하듯
// 가짜(fake) 구현을 주입해보려는 시도지만
return Container(logger = FakePlatformLogger()) // 컴파일 오류:
// FakePlatformLogger는 PlatformLogger의 서브타입이 아니다. 코틀린의
// 클래스는 open으로 선언하지 않으면 기본적으로 final이고, 이
// expect/actual 쌍은 open으로 선언되어 있지 않기 때문이다
}이것이 DI 사고 모델이 곧바로 이끄는 실수다: 테스트를 위해 가짜/교체 가능한
구현을 얻으려고 expect/actual에 손을 뻗는 것인데, 이는 Repository
인터페이스를 FakeRepository로 바꿔치는 것과 같은 방식이다.
PlatformLogger를 여기서 서브클래싱할 수 없는 건, expect/actual이
만들어낸 제약이 아니라 코틀린의 일반적인 동작(클래스는 open으로 선언하지
않으면 final이다)일 뿐이다. expect open class PlatformLogger()로
선언해도 이 DI 용례는 구해내지 못한다. 그렇게 하면 해당 타겟의 바이너리에
들어간 그 하나의 actual 클래스를 서브클래싱할 수 있게 될 뿐, 같은 호출
지점에서 안드로이드 구현과 가짜 구현을 바꿔 끼우게 해주지는 않는다. open
이든 아니든, 컴파일 단위마다 PlatformLogger 타입은 결국 하나뿐이다.
런타임에 교체 가능한 구현(테스트, 기능 플래그, 또는 프로그램이 실행되는 동안
결정되는 그 외의 어떤 것을 위해)이 필요하다면, 여전히 실제 코틀린 interface가
필요하다. expect/actual은 필요한 경우 한 구현의 플랫폼별 생성을 제공하기
위해서만 다시 등장한다.
// commonMain — 실제 인터페이스이며, 채워야 할 플랫폼별 본문이 없으므로
// expect/actual이 필요하지 않다
interface Logger {
fun log(message: String)
}
class Container(private val logger: Logger)// androidMain — 인터페이스를 구현하는 평범한 클래스
class AndroidLogger : Logger {
override fun log(message: String) = android.util.Log.d("App", message)
}// commonTest — FakePlatformLogger는 앞서 PlatformLogger가 final이었기
// 때문에 타입체크에 실패했다; FakeLogger는 Logger가 인터페이스이므로 동작한다
class FakeLogger : Logger {
val messages = mutableListOf<String>()
override fun log(message: String) { messages += message }
}
fun buildForTesting(): Container = Container(logger = FakeLogger())expect/actual은 여기서도 여전히 제 역할을 한다. 다만 한 단계 위에서다:
인터페이스 자체를 대신하는 것이 아니라, 플랫폼별로 어떤 구현이 생성될지를
고르는 역할이다.
// commonMain
expect fun providePlatformLogger(): Logger
// androidMain
actual fun providePlatformLogger(): Logger = AndroidLogger()
// iosMain
actual fun providePlatformLogger(): Logger = IosLogger()실제 사용 사례
PlatformLogger는 의도적으로 최소화된 예시다. 실제 운영 중인 KMP 코드베이스에서는
expect/actual이 몇 가지 정해진 지점에서 반복적으로 나타나는데, 공유 로직이
시작점으로 삼을 플랫폼 프리미티브가 정확히 하나 필요한 곳이면 어디든 그렇다.
고유 식별자
// commonMain
expect fun randomUuid(): String
// androidMain
actual fun randomUuid(): String = java.util.UUID.randomUUID().toString()
// iosMain
actual fun randomUuid(): String = platform.Foundation.NSUUID().UUIDString두 플랫폼 모두 이미 UUID 생성기를 기본으로 제공한다. expect/actual은
commonMain 안에서 플랫폼을 분기해서 두 가지 플랫폼별 구현 중 하나를 고르는 대신,
공유 코드에 호출할 이름 하나를 제공해줄 뿐이다.
진단을 위한 플랫폼 정보 읽기
// 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}" }이 예시는 기본 Kotlin Multiplatform 프로젝트 템플릿에 포함되어 있으며, 보통 어떤 OS에서 발생했는지 알아야 하는 크래시 리포트나 애널리틱스 이벤트에 읽혀 들어간다.
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)두 플랫폼 모두 표준 라이브러리에 이미 Base64 인코더를 갖추고 있다.
expect/actual은 둘 사이를 분기하는 대신, 공유 직렬화 코드에 호출할 확장
함수 하나를 제공해줄 뿐이다.
실제 시각(Wall-clock Time)
// commonMain
expect fun currentTimeMillis(): Long
// androidMain
actual fun currentTimeMillis(): Long = System.currentTimeMillis()
// iosMain
actual fun currentTimeMillis(): Long =
(platform.Foundation.NSDate().timeIntervalSince1970 * 1000).toLong()이것은 교과서적인 expect/actual 예시다. 아직 kotlinx-datetime의
Clock.System.now()를 도입하지 않은 코드베이스에서는 여전히 등장하는데, 이
라이브러리는 프로젝트 전용 expect/actual 대신 포터블 라이브러리로서 정확히
같은 문제를 해결한다. UUID 생성과 동일한 형태다: 모든 플랫폼에 서로 다른
이름으로 존재하는 표준 라이브러리 프리미티브를, 하나의 commonMain 시그니처
아래 통합하는 것이다.
UUID, 플랫폼 정보, Base64, 그리고 실제 시각은 모두 같은 형태를 따른다: commonMain에 시그니처 하나, 플랫폼마다 본문 하나, 어느 쪽 바이너리도 존재하기 전에 해석되는 것이다. 어느 쪽도 한쪽에만 추가 생성자 인자를 필요로 하지 않기 때문이다.
expect/actual을 쓰지 말아야 할 때: 보안 자격 증명 저장
공유 로그인/세션 코드는 토큰을 영속화해야 하지만, 그것을 안전하게 저장하는
방법은 본질적으로 플랫폼마다 다르다. Android의 해법은 이를 위해 Context가
필요하고, 이는 위의 모든 예시가 의존했던 형태를 깨뜨린다.
expect/actual은 Context를 깔끔하게 전달할 방법이 없다: 모든 actual
생성자는 인자까지 포함해 expect의 것과 정확히 일치해야 하므로, Android
전용 매개변수는 갈 곳이 없다. 앞서 Logger 예시에서 쓰인 동일한 인터페이스
패턴은, 이 문제를 임시방편으로 회피하는 대신 근본적으로 피해간다:
// commonMain — Logger와 같은 형태의 평범한 인터페이스: 플랫폼 간에
// 동기화해야 할 생성자가 없으므로, expect/actual이 전혀 필요하지 않다
interface SecureStorage {
fun save(key: String, value: String)
fun read(key: String): String?
}// androidMain — 이 플랫폼의 DI 모듈이 가지고 있는 Context로 생성되며,
// 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 — 전달해야 할 Context가 없으므로 돌아갈 일도 없으며,
// Keychain을 기반으로 한다
class IosSecureStorage : SecureStorage {
override fun save(key: String, value: String) { /* SecItemAdd(...) */ }
override fun read(key: String): String? = /* SecItemCopyMatching(...) */ null
}각 플랫폼의 DI 모듈(Koin, Kodein, 직접 구현한 것 등)은 SecureStorage를
자신만의 생성자 호출에 바인딩한다: Android에서는 AndroidSecureStorage(context),
iOS에서는 IosSecureStorage()다. 공유된 AuthRepository는 자신의 DI
그래프가 건네준 SecureStorage가 무엇이든 그 위에서 save(...)를 호출할
뿐, 그것이 어떤 저장소였는지는 전혀 알지 못한다. 어느 플랫폼의 생성자도
다른 플랫폼의 생성자에 의해 제약받지 않는다.
SecureStorage는 expect/actual의 형태가 더는 맞지 않게 되는 지점을
보여주는 신호다: 한 플랫폼의 구현이 다른 플랫폼에는 없는 무언가(Context,
핸들, 그 무엇이든)를 필요로 하는 순간, expect/actual로 억지로 밀어붙이는
대신 인터페이스를 쓰는 게 맞다.
핵심 원리
이것이 **컴파일타임 다형성(compile-time polymorphism)**이다: 호출 지점이 어떤 구현을 사용할지를, 올바른 선언을 올바른 소스 세트에 말 그대로 대입함으로써 컴파일 과정의 일부로 해결하는 것이다.
이는 **런타임(동적) 다형성(runtime (dynamic) polymorphism)**과 다르다. 여기서는 하나의 컴파일된 호출 지점이, 조회(또는 DI 컨테이너)가 프로그램이 실행되는 동안 구체적인 구현을 선택하기까지 모호한 상태로 남아 있다.
expect/actual은 설계상 런타임 비용이 전혀 없고 런타임 유연성도 전혀
없다: 컴파일 한 번당 expect 하나에 정확히 actual 하나만 존재하며, 이는
바이너리가 존재하기 전에 결정된다.
바로 이것이, 같은 인터페이스를 구현하는 두 클래스를 가질 수 있는 것과 달리, 같은 실행 중인 프로세스 안에 두 개의 actual을 동시에 사용 가능하게 둘 수 없는 이유이기도 하다.
다른 곳에서도: 같은 근본 원리, 다른 프레임워크
- C/C++ 전처리기:
#ifdef _WIN32 ... #else ... #endif는 진짜 컴파일러가 동작하기 전에 전처리기에 의해 해석되며, 텍스트 수준에서 한쪽 분기를 대입하고 다른 쪽은 삭제한다. "오직 한 버전만 컴파일된다"는 동일한 보장을, 선언 수준이 아니라 텍스트 수준에서 제공하는 것이다. - Rust의
#[cfg(...)]:#[cfg(target_os = "ios")] fn platform_name() -> &'static str { "iOS" }와 동일한 시그니처를 가진 Android 버전은 빌드 타겟별로 컴파일러에 의해 해석된다. 일치하는cfg블록만 컴파일되어 들어가며, 나머지는 도달 불가능한 코드로조차 그 바이너리 안에 존재하지 않는다. - Swift의
#if os(iOS)/#if canImport(...): 타입 검사가 일어나기 전에 타겟별로 블록을 유지하거나 제거하는 컴파일러 지시문으로, KMP의iosMain/androidMain분리가 그대로 비추는 플랫폼별 소스 파일 패턴과 같다. KMP 프레임워크를 링크하는 Swift Package Manager 타겟도, 경계의 자기 쪽에서 내부적으로 똑같이 "이 심볼의 버전은 오직 하나만 컴파일되었다"는 트릭을 쓰고 있는 것이다. - Java의 멀티 릴리즈 JAR(
META-INF/versions/)는 비슷해 보이지만 다르다: JVM은 실행 중인 JVM의 버전에 따라 클래스 로드 시점에 클래스 파일 버전을 고르므로, 하나의 JAR는 실제로 여러 개의 컴파일된 버전을 함께 담아 보내고, 그 선택을 런타임으로 미룬다. 이것이 바로expect/actual이 의도적으로 피하는 동적 다형성의 형태다.
엣지 케이스
나중에 타겟을 추가하면, 누락된 actual은 테스트 실패가 아니라 빌드 오류로 드러난다
e: Expected class 'PlatformLogger' has no actual declaration in module
<app-wasmJsMain> for target WASM프로젝트에 새 타겟(예: wasmJsMain)이 추가되고 아무도 대응하는 actual을
작성하지 않으면, 실패는 그 타겟의 빌드에서 발생하는 컴파일 오류이며, 런타임
크래시도 아니고 단위 테스트 실패도 아니다.
CI가 실제로 모든 타겟을 빌드하지 않는다면 이는 놓치기 쉽다. expect 선언
자체는 그것에 대응하는 actual이 몇 개 존재하든 상관없이 commonMain에서
문제없이 컴파일되기 때문이다.
actual은 expect가 선언하지 않은 추가 공개 API를 노출할 수 없다
// commonMain
expect class PlatformLogger() {
fun log(message: String)
}
// androidMain
actual class PlatformLogger {
actual fun log(message: String) { /* ... */ }
fun logWithTag(tag: String, message: String) { /* ... */ } // 여기서는 문제없이 컴파일된다
}
// commonMain, 호출하는 코드
PlatformLogger().logWithTag("App", "hi") // 참조 해결 불가 (unresolved reference)logWithTag가 컴파일되는 이유는 androidMain이 실제 클래스이고 원하는
멤버를 얼마든지 가질 수 있기 때문이다. 다만 commonMain에서는 보이지
않는다. commonMain은 오직 expect가 약속한 형태만을 보며, 특정 actual이
어떤 것을 추가로 덧붙였는지는 전혀 보지 못하기 때문이다.
이것은 위에서 다룬 actual 누락 사례와 반대되는 실패 양상이다: 코드는 어디서든 컴파일되지만, 작성한 호출 지점에서 기대했던 동작을 하지 않을 뿐이다.
actual typealias는 클래스 본문을 완전히 건너뛰지만, 그래도 정확히 일치해야 한다
// commonMain
expect class PlatformDate
// jvmMain, 래퍼 클래스를 작성하는 대신 기존 플랫폼 타입에
// 직접 별칭(alias)을 지정한다
actual typealias PlatformDate = java.time.LocalDate여기에는 actual class 본문이 전혀 없다. java.time.LocalDate가 그냥
그 자체로 actual인 것이다. 이는 플랫폼이 이미 딱 맞는 타입을 가지고
있고, 이를 감싸는 것이 순전히 형식적인 절차에 불과할 때 흔히 쓰는 방법이다.
해석되는 방식은 여전히 동일하다, 컴파일 타임에, 타겟별로. typealias는
같은 대입에 이르는 더 짧은 경로일 뿐이다.
expect/actual은 디스패치가 아니라 컴파일타임 대입이다: 컴파일러는
바이너리가 존재하기 전에 타겟마다 하나의 actual을 고르므로, 실행 중인
프로세스가 선택할 구현을 두 개 이상 들고 있는 경우는 결코 없다.



