Recomposed
Multiplatform

Kotlinのexpect/actual: コンパイル時のインターフェースであり、ランタイムのインターフェースではない

Oct 29, 2026 · 12 min read

Kotlinのexpect/actual: コンパイル時のインターフェースであり、ランタイムのインターフェースではない

expect/actualの実体

expect/actualは、Kotlin Multiplatformにおいて共有コード内で1つの宣言を書き、プラットフォームごとに異なる本体を与えるための仕組みだ。

  • **expect**宣言はcommonMainに置かれる。本体を持たないクラス、関数、プロパティのシグネチャを宣言するものであり、プロジェクトがビルドするすべてのプラットフォームに対応する実装が存在するという約束だ。
  • **actual**宣言はプラットフォームの 、 例えばandroidMainやiosMainに置かれ、その1つのプラットフォーム向けの実際の実装によってその約束を果たす。
  • コンパイラは、ビルド対象の各ターゲットについて、すべてのexpectに対応するactualが存在することを検証し、不足していればビルドを失敗させる。

これが契約だ。しかし、この説明が教えてくれないのは、マッチングがいつ行われるかであり、そこでメンタルモデルが大抵狂ってしまう。

直感的な理解

expect/actualは、プラットフォームごとに実装を持つインターフェースのように見える。インターフェースを定義し、AndroidとiOSでそれぞれ異なる実装を注入する、というものだ。この構図は依存性注入から自然に持ち込まれる。しかし、ある特定の点において、これは誤りだ。

  • インターフェースはコンパイル後の形がちょうど1つしか存在せず、どの実装が実行されるかは に、DIグラフ(あるいは単純なif)が渡すものによって決まる。
  • expect宣言そのものには、コンパイル後の形が一切存在しない。各ターゲットは、バイナリが存在する前に、自分に対応するactualを組み込んだ状態でcommonMainをコンパイルする。
  • AndroidのactualとiOSのactualが同じコンパイル済みアーティファクトの中に両方存在する瞬間は決してない。各ターゲットのビルドは、自分にとっての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ビルドが実際にコンパイルする内容だ。

  • iosMainのactual class PlatformLoggerをまったく目にすることはない。デッドコードとしても、使われない分岐としても、どこにもコンパイルされない。
  • Androidのコンパイル単位はcommonMain + androidMainのみであり、その中のすべてのexpectは、コード生成が行われる前に直接androidMainのactualへと解決される。

androidMainをiosMainに置き換えると、同じバイナリの中の異なるランタイムパスではなく、別々に、個別にコンパイルされたバイナリが得られる。

FIG. 01
各ターゲットのコンパイルは、常にcommonMainと自身のactualのみを取り込む。Androidバイナリは決してiOSのactualを含まず、その逆も同様だ

実行時にactualを選ぼうとしても型チェックは通らない

// ❌ 参照を保持できるPlatformLoggerの「インターフェース」は存在しない。
// expect宣言は、変数の裏側で差し替えられる型ではない
class Container(private val logger: PlatformLogger)
 
fun buildForTesting(): Container {
    // 本物のインターフェースであれば行うように、フェイク実装を注入しようとしている
    return Container(logger = FakePlatformLogger()) // コンパイルエラー:
    // FakePlatformLoggerはPlatformLoggerのサブタイプではない。Kotlinの
    // クラスはopenを付けない限りデフォルトでfinalであり、この
    // expect/actualのペアはopenになっていないからだ
}

これは、DIのメンタルモデルがまさに導いてしまう間違いだ。RepositoryインターフェースをFakeRepositoryに差し替えるのと同じように、テスト用のフェイク/差し替え可能な実装を得ようとしてexpect/actualに手を伸ばしてしまう。PlatformLoggerをここでサブクラス化できないのは、ごく普通のKotlinの挙動(クラスはopenを付けない限りfinal)であって、expect/actualが生み出した制約ではない。expect open class PlatformLogger()と書いても、このDIのユースケースは救えない。それをしても、そのターゲットのバイナリに入った1つのactualクラスをサブクラス化できるようになるだけで、同じ呼び出し箇所でAndroid版とフェイク版を切り替えられるようにはならない。openであろうとなかろうと、コンパイル単位ごとにPlatformLogger型は結局1つしか存在しない。

実行時に差し替え可能な実装(テスト、フィーチャーフラグ、あるいはプログラム実行中に決まるその他何であれ)が必要な場合は、やはり本物のKotlinのinterfaceが必要だ。expect/actualが再び登場するのは、必要であれば、ある1つの実装のプラットフォーム固有の構築を提供する場面だけだ。

// 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はまだ存在価値がある。ただ1段階上、つまりインターフェース自体の代わりになるのではなく、プラットフォームごとにどの実装を構築するかを選ぶ役割だ。

// commonMain
expect fun providePlatformLogger(): Logger
 
// androidMain
actual fun providePlatformLogger(): Logger = AndroidLogger()
 
// iosMain
actual fun providePlatformLogger(): Logger = IosLogger()

実際の使用例

PlatformLoggerは意図的に最小限にしてある。実際のKMPコードベースでは、expect/actualは決まった少数の接点に現れる傾向がある。共有ロジックが出発点として、たった1つのプラットフォームプリミティブを必要とする場所だ。

一意な識別子

// 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の内部でプラットフォームによる分岐を行って2つのプラットフォーム固有の実装を切り替える代わりに、共有コードに呼び出すための1つの名前を与えるだけだ。

診断用にプラットフォーム情報を読み取る

// 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は、2つを切り替える分岐の代わりに、共有のシリアライズコードに呼び出すための1つの拡張関数を与えるだけだ。

ウォールクロック時間

// 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()を導入していないコードベースでは今でも見られる。Clock.System.now()は、プロジェクトローカルのexpect/actualではなく、ポータブルなライブラリとして、まったく同じ問題を解決する。UUID生成と同じ形だ。各プラットフォームに異なる名前で存在するstdlibのプリミティブを、commonMainの1つのシグネチャに統一している。

UUID、プラットフォーム情報、Base64、そしてウォールクロック時間は、すべて同じ形をたどる。commonMainに1つのシグネチャ、プラットフォームごとに1つの本体、どちらのバイナリが存在する前にも解決される。これは、どれも片方の側だけに追加のコンストラクタ引数を必要としないからだ。

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に無理やり押し込むのではなく、インターフェースに手を伸ばすべきだ。

基本原則

これはコンパイル時ポリモーフィズムだ。呼び出し箇所がどの実装を使うかを、コンパイルの一部として、正しい宣言を正しいソースセットへ文字通り置き換えることで解決する。

それはランタイム(動的)ポリモーフィズムとは異なる。動的ポリモーフィズムでは、1つのコンパイル済みの呼び出し箇所は、プログラムが実行中にのルックアップ (あるいはDIコンテナ)が具体的な実装を選ぶまで曖昧なままだ。

expect/actualは設計上、ランタイムコストもランタイムの柔軟性もゼロだ。コンパイルごとに、1つのexpectに対してちょうど1つのactualが、バイナリが存在する前に選ばれる。

それが、同じインターフェースを実装する2つのクラスを持てるのと同じようには、同じ実行中のプロセス内で2つのactualを利用可能にすることができない理由でもある。

他の言語でも: 同じ基本原理、異なる枠組み

  • C/C++のプリプロセッサ: #ifdef _WIN32 ... #else ... #endifは、本体のコンパイラが動く前にプリプロセッサによって解決され、片方の分岐をテキストとして置き換え、もう片方を削除する。「コンパイルされるバージョンは常に1つだけ」という同じ保証が、宣言レベルではなくテキストレベルで成立している。
  • 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のターゲットは、裏側では境界の自分の側で同じ「このシンボルのバージョンは常に1つしかコンパイルされない」というトリックを行っている。
  • Javaのマルチリリースjar(META-INF/versions/)は似ているが実は異なる。JVMは、実行中のJVMのバージョンに基づいてクラスロード時にクラスファイルのバージョンを選ぶ。つまり1つの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が宣言していない追加のpublic 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") // 未解決の参照

logWithTagがコンパイルできるのは、androidMainが本物のクラスであり、好きなメンバーを持てるからだ。ただそれはcommonMainからは見えない。commonMainが目にするのは、expectが約束した形だけであり、個々のactualがたまたま追加したものは見えないからだ。

これは、先ほどの「actualが不足している」ケースとは正反対の失敗だ。コードはどこでもコンパイルは通るが、呼び出し箇所で期待していた動作をしないだけだ。

actual typealiasはクラス本体を完全にスキップするが、それでも一致は厳密でなければならない

// commonMain
expect class PlatformDate
 
// jvmMain, ラッパークラスを書く代わりに、既存のプラットフォーム型へ
// 直接エイリアスする
actual typealias PlatformDate = java.time.LocalDate

ここにはactual classの本体がまったくない。java.time.LocalDateそのものがactualなのだ。これは、プラットフォームがすでに適切な型を持っていて、それをラップするのが単なる儀式になってしまう場合によく使われる手法だ。それでも解決の仕方は同じで、コンパイル時に、ターゲットごとに行われる。typealiasは、同じ置き換えへの単に短い道だ。

expect/actualはディスパッチではなくコンパイル時の置き換えだ。コンパイラはバイナリが存在する前に、ターゲットごとに1つのactualを選ぶ。そのため、実行中のプロセスが複数の実装を保持して、その中から選ぶということは決して起きない。

Keep reading

Related reads

新しい記事をメールで受け取る