Extension Manager
Koinには、ライブラリおよびフレームワークの開発者向けに2つの拡張ポイント(Extension points)が用意されています。KoinExtensionはKoinコンテナに機能を追加し、登録時および終了時のフックを提供します。ResolutionExtensionは、一致する定義が存在しない場合に、Koinへインスタンスの別の取得元を提供します。ほとんどのアプリケーションではどちらも必要ありません。まずは定義(definitions)を使用してください。
KoinExtension
KoinExtensionは、IDを指定してコンテナに登録されるオブジェクトです。
interface KoinExtension {
fun onRegister(koin: Koin)
fun onClose()
}Koinは、拡張機能が登録されたときにonRegisterを呼び出し、コンテナが終了するとき(stopKoin()またはkoinApplication.close())にonCloseを呼び出します。
Koin自体もこのメカニズムを利用しています。Lazyモジュールの基盤となっているコルーチンエンジンは、KoinCoroutinesEngine拡張機能です。
拡張機能の実装
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に公開します。
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)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は、カレントスコープ、スコープソース、およびルートスコープを含むリンクされたスコープの定義を検索した後に、他に一致するものがない場合にインスタンスの解決を要求されます。
interface ResolutionExtension {
val name: String
fun resolve(scope: Scope, instanceContext: ResolutionContext): Any?
}instanceContext.clazz(修飾子を使用する場合はinstanceContext.qualifierも含む)に対応するインスタンスを返すか、Koinに解決処理を継続させてNoDefinitionFoundExceptionで失敗させるためにnullを返します。
Koinは、Ktor DI bridgeにおいてKtorの依存関係注入からインスタンスを読み取るためにこれを使用しています。
例:別のコンテナからのインスタンス取得
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を使用して登録します。
@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は複数のスレッドから同時に呼び出される可能性があります。
関連情報
- Lazyモジュール:コルーチンエンジン拡張機能に基づいて構築された機能。
- Ktor DI Bridge:解決用拡張機能の実践例。
- コンパイル時の安全性:Koinの外部から提供される依存関係の宣言。
- Koinの起動:拡張機能を登録するアプリケーションDSL。
- スコープ:スコープ内での解決順序。
