Skip to content

Extension Manager ​

Koinには、ライブラリおよびフレームワークの開発者向けに2つの拡張ポイント(Extension points)が用意されています。KoinExtensionはKoinコンテナに機能を追加し、登録時および終了時のフックを提供します。ResolutionExtensionは、一致する定義が存在しない場合に、Koinへインスタンスの別の取得元を提供します。ほとんどのアプリケーションではどちらも必要ありません。まずは定義(definitions)を使用してください。

KoinExtension ​

KoinExtensionは、IDを指定してコンテナに登録されるオブジェクトです。

kotlin
interface KoinExtension {
    fun onRegister(koin: Koin)
    fun onClose()
}

Koinは、拡張機能が登録されたときにonRegisterを呼び出し、コンテナが終了するとき(stopKoin()またはkoinApplication.close())にonCloseを呼び出します。

Koin自体もこのメカニズムを利用しています。Lazyモジュールの基盤となっているコルーチンエンジンは、KoinCoroutinesEngine拡張機能です。

拡張機能の実装 ​

kotlin
class AuditExtension : KoinExtension {
    private lateinit var koin: Koin

    override fun onRegister(koin: Koin) {
        this.koin = koin
    }

    override fun onClose() {
        // リソースを解放
    }

    fun record(event: String) { ... }
}

拡張機能の登録と取得 ​

拡張機能を登録するための関数をKoinApplicationに追加し、それを取得するためのプロパティをKoinに公開します。

kotlin
private const val AUDIT_EXTENSION = "audit"

fun KoinApplication.audit() {
    with(koin.extensionManager) {
        if (getExtensionOrNull<AuditExtension>(AUDIT_EXTENSION) == null) {
            registerExtension(AUDIT_EXTENSION, AuditExtension())
        }
    }
}

val Koin.audit: AuditExtension
    get() = extensionManager.getExtension(AUDIT_EXTENSION)
kotlin
startKoin {
    audit()
    modules(appModule)
}

getKoin().audit.record("app_started")
関数動作
registerExtension(id, extension)拡張機能を保存し、onRegisterを呼び出します。同じIDを持つ拡張機能は置き換えられます
getExtension<T>(id)拡張機能を返します。存在しない場合は「Koin extension 'id' not found.」というエラーで失敗します
getExtensionOrNull<T>(id)拡張機能を返します。存在しない場合はnullを返します

WARNING

ExtensionManagerには@KoinInternalApiが付与されています。オプトインが必要であり、非推奨化(deprecation)プロセスを経ることなくバージョン間でAPIが変更される可能性があります。

ResolutionExtension ​

ResolutionExtensionは、カレントスコープ、スコープソース、およびルートスコープを含むリンクされたスコープの定義を検索した後に、他に一致するものがない場合にインスタンスの解決を要求されます。

kotlin
interface ResolutionExtension {
    val name: String
    fun resolve(scope: Scope, instanceContext: ResolutionContext): Any?
}

instanceContext.clazz(修飾子を使用する場合はinstanceContext.qualifierも含む)に対応するインスタンスを返すか、Koinに解決処理を継続させてNoDefinitionFoundExceptionで失敗させるためにnullを返します。

Koinは、Ktor DI bridgeにおいてKtorの依存関係注入からインスタンスを読み取るためにこれを使用しています。

例:別のコンテナからのインスタンス取得 ​

kotlin
class LegacyContainerResolution(
    private val legacy: Map<KClass<*>, Any>,
) : ResolutionExtension {

    override val name: String = "legacy-container"

    override fun resolve(scope: Scope, instanceContext: ResolutionContext): Any? =
        legacy[instanceContext.clazz]
}

アプリケーションのkoinインスタンス上でaddResolutionExtensionを使用して登録します。

kotlin
@OptIn(KoinExperimentalAPI::class)
fun startApp(legacy: Map<KClass<*>, Any>) {
    startKoin {
        koin.addResolutionExtension(LegacyContainerResolution(legacy))
        modules(appModule)
    }
}

これにより、レガシーマップにのみ存在する型を必要とするappModule内の定義が、拡張機能からそのインスタンスを取得できるようになります。

Compiler Pluginを使用している場合、拡張機能のみから提供される型はビルド時点では不明であるため、コンパイル時の安全性チェックで不足している依存関係として報告されます。これを外部から提供されるものとしてマークしてください。詳細はコンパイル時の安全性(Compile-Time Safety)を参照してください。

addResolutionExtensionには@KoinExperimentalAPIが付与されています。

制限事項 ​

  • 内部および実験的API:どちらの拡張ポイントも、Koinのバージョン間で変更される可能性があります。
  • 解決用拡張機能のライフサイクルが存在しない:KoinはResolutionExtensionが返したインスタンスをキャッシュしません。必要に応じて独自にキャッシュしてください。
  • 解決順序の最後:定義に一致するものがある場合、解決用拡張機能が呼び出されることはありません。既存の定義をオーバーライドすることはできません。
  • スレッドセーフティ:resolveは複数のスレッドから同時に呼び出される可能性があります。