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 アーティファクトをそのまま維持します。
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 {
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 を持ち、他のアノテーションがないクラスはファクトリを宣言します。
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 の対象となるパッケージ内にある必要があります。
@Module
@ComponentScan("com.example.data")
class DataModule@Singleton は、自身でビルドするオブジェクト向けに、@Module クラス内のプロバイダー関数に対しても機能します。
@Module
class NetworkModule {
@Singleton
fun retrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com")
.build()
}スーパータイプへのバインディングは Koin アノテーションと同様に機能します。クラスはそのインターフェースにバインドされます(定義 を参照)。
修飾子(Qualifiers)
@Named は宣言時およびインジェクションポイントで機能します。
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 のカスタム修飾子と同様に動作します。
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 アノテーションを混在して使用できます。
@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() に渡されたコンテキストを自動で注入します。
@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 によってチェックされます(コンパイル時の安全性 を参照)。
関連情報
- Hilt からの移行: JSR-330 により既存のクラスをそのまま維持できる、ステップバイステップの移行ガイド。
- 定義: 定義の種類とインターフェースバインディング。
- 修飾子(Qualifiers): 名前付き、型、カスタム修飾子。
- アノテーションリファレンス: すべての Koin アノテーション。
- Compiler Plugin のセットアップ: プラグインの導入方法。
