Skip to content

JSR-330 アノテーション ​

Koin Compiler Plugin は、jakarta.inject および javax.inject からの標準 JSR-330 アノテーションを読み取ります。@Singleton または @Inject constructor を持つクラスは、Koin アノテーションが付いていなくても Koin 定義(definition)になります。このページでは、サポートされている内容とそのセットアップ方法を一覧で示します。これはアノテーションスタイルに適用されます。Compiler Plugin と @ComponentScan を持つモジュールが必要です(モジュール を参照)。

主な用途は、他の JSR-330 フレームワークと共有されるコード、または既存のクラスを変更せずに維持する Hilt や Dagger からの移行です(Hilt からの移行 を参照)。

セットアップ ​

JVM および Android では、すでに使用している JSR-330 アーティファクトをそのまま維持します。

kotlin
dependencies {
    implementation("jakarta.inject:jakarta.inject-api:2.0.1")
    // またはレガシーなパッケージ
    implementation("javax.inject:javax.inject:1")
}

Kotlin Multiplatform コードでは、これらの Java アーティファクトは利用できません。すべての Kotlin ターゲットに対して jakarta.inject アノテーションを提供する koin-jsr330 を追加します。

kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.insert-koin:koin-jsr330:$koin_annotations_version")
        }
    }
}

NOTE

koin-jsr330 は Koin BOM ではなく、Koin Annotations と一緒に公開されます。Koin Annotations のバージョンを使用してください。

サポートされているアノテーション ​

JSR-330 アノテーションKoin での同等機能適用対象
@Singleton@Singleton / @Singleクラス、@Module 内の関数
コンストラクタ上の @Inject@Factoryクラス
@Named("x")@Named("x")クラス、関数、パラメータ
@Qualifier@Qualifier独自の修飾子(qualifier)アノテーションクラス

jakarta.inject.* と javax.inject.* の両方のパッケージが動作します。同じクラスに Koin アノテーションがある場合は、それが優先されます。例えば、@Inject constructor を持つクラスに @KoinViewModel が付いている場合、ファクトリではなく ViewModel を宣言します。

JSR-330 の @Scope は Koin スコープには影響を与えません。Koin の @Scope および @Scoped、または @ActivityScope などのスコープアーキタイプを使用してください(スコープ を参照)。

定義 ​

@Singleton は single を宣言します。@Inject constructor を持ち、他のアノテーションがないクラスはファクトリを宣言します。

kotlin
import jakarta.inject.Inject
import jakarta.inject.Singleton

@Singleton
class UserRepository @Inject constructor(
    private val api: ApiService,
    private val database: UserDatabase,
)

// リクエストごとに新しいインスタンスを生成
class GetUserUseCase @Inject constructor(
    private val repository: UserRepository,
)

クラスに @Singleton アノテーションが付いている場合、@Inject は省略可能です。Koin はプライマリコンストラクタを使用します。クラスに複数のコンストラクタがある場合、Koin は @Inject でアノテーションされたコンストラクタを使用します。

これらのクラスは、他のアノテーション付きクラスと同様に、@ComponentScan の対象となるパッケージ内にある必要があります。

kotlin
@Module
@ComponentScan("com.example.data")
class DataModule

@Singleton は、自身でビルドするオブジェクト向けに、@Module クラス内のプロバイダー関数に対しても機能します。

kotlin
@Module
class NetworkModule {

    @Singleton
    fun retrofit(): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .build()
}

スーパータイプへのバインディングは Koin アノテーションと同様に機能します。クラスはそのインターフェースにバインドされます(定義 を参照)。

修飾子(Qualifiers) ​

@Named は宣言時およびインジェクションポイントで機能します。

kotlin
import jakarta.inject.Inject
import jakarta.inject.Named
import jakarta.inject.Singleton

@Singleton
@Named("inMemory")
class InMemoryCache @Inject constructor() : Cache

@Singleton
@Named("disk")
class DiskCache @Inject constructor(private val context: Context) : Cache

@Singleton
class ImageLoader @Inject constructor(
    @Named("inMemory") private val memoryCache: Cache,
    @Named("disk") private val diskCache: Cache,
)

JSR-330 の @Qualifier でマークされたカスタム修飾子アノテーションは、Koin のカスタム修飾子と同様に動作します。

kotlin
import jakarta.inject.Qualifier

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Module
class DispatcherModule {

    @Singleton
    @IoDispatcher
    fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
}

@Singleton
class SyncManager @Inject constructor(
    @IoDispatcher private val dispatcher: CoroutineDispatcher,
)

修飾子がどのように解決されるかについては、修飾子(Qualifiers) を参照してください。

Koin アノテーションとの混在 ​

同じプロジェクト内、さらには同じクラス上で JSR-330 と Koin アノテーションを混在して使用できます。

kotlin
@Singleton // jakarta.inject
@Named("local")
class LocalDatabase @Inject constructor() : Database

@Single // Koin
@Named("remote")
class RemoteDatabase(private val api: ApiService) : Database

@Factory // Koin(JSR-330 コンストラクタを併用)
class DatabaseManager @Inject constructor(
    @Named("local") private val local: Database,
    @Named("remote") private val remote: Database,
)

JSR-330 には ViewModel、Worker、またはインジェクションされたパラメータ用のアノテーションがありません。それらには Koin アノテーション(@KoinViewModel、@KoinWorker、@InjectedParam)を使用してください。Context パラメータには修飾子は不要です。Koin は androidContext() に渡されたコンテキストを自動で注入します。

kotlin
@KoinViewModel
class UserViewModel @Inject constructor(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

制限事項 ​

  • フィールドおよびメソッドインジェクション: @Inject lateinit var フィールドおよび @Inject メソッドはサポートされていません。コンストラクタ経由で注入するか、Android コンポーネントで by inject() を使用してください(エントリーポイント を参照)。
  • Provider<T>: jakarta.inject.Provider<T> パラメータは解決されません。Lazy<T> パラメータを使用するか、高度なパターン にあるプロバイダーパターンを使用してください。
  • アノテーションスタイルのみ: @Singleton と @Inject が定義を宣言するのは @ComponentScan を通じてのみです。DSL モジュールでは従来通り single<T>() を記述します。その際、Compiler Plugin DSL がパラメータの @Named を読み取り、@Inject コンストラクタを使用します。
  • コンパイル時の安全性: JSR-330 の定義は、Koin アノテーションと同様に Compiler Plugin によってチェックされます(コンパイル時の安全性 を参照)。