アノテーションリファレンス
このページでは、すべてのKoinアノテーションについて、所属パッケージ、付与可能な場所、パラメータ、および使用例を網羅しています。各項目には、その概念を説明するページへのリンクが含まれています。アノテーションのセットアップ方法についてはCompiler Plugin Setupを、DSLとの比較についてはChoosing your styleを参照してください。
これらのアノテーションは io.insert-koin:koin-annotations アーティファクト(Koinと同じバージョン)から提供されます。Koin Compiler Pluginはビルド時にこれらを読み取り、定義を生成します。ほとんどのアノテーションは org.koin.core.annotation にあり、Android専用のものは org.koin.android.annotation に配置されています。
早見表
| アノテーション | パッケージ | 宣言内容 |
|---|---|---|
@Singleton / @Single | org.koin.core.annotation | single 定義 |
@Factory | org.koin.core.annotation | factory 定義 |
@Scoped | org.koin.core.annotation | scoped 定義 |
@KoinViewModel | org.koin.core.annotation | viewModel 定義 |
@KoinWorker | org.koin.android.annotation | WorkManager の worker 定義 |
@Scope | org.koin.core.annotation | 定義が属するスコープ |
@ViewModelScope | org.koin.core.annotation | ViewModel スコープ内の定義 |
@ActivityScope | org.koin.android.annotation | Activity スコープ内の定義 |
@ActivityRetainedScope | org.koin.android.annotation | 保持される(retained)Activity スコープ内の定義 |
@FragmentScope | org.koin.android.annotation | Fragment スコープ内の定義 |
@ScopeId | org.koin.core.annotation | 指定されたスコープから解決されるパラメータ |
@Named | org.koin.core.annotation | 文字列クオリファイア |
@Qualifier | org.koin.core.annotation | 型または文字列クオリファイア |
@InjectedParam | org.koin.core.annotation | 呼び出し元から渡されるパラメータ |
@Property | org.koin.core.annotation | Koin プロパティから読み取られるパラメータ |
@PropertyValue | org.koin.core.annotation | プロパティのデフォルト値 |
@Provided | org.koin.core.annotation | チェック対象グラフの外部から提供される型 |
@Module | org.koin.core.annotation | モジュールクラス |
@ComponentScan | org.koin.core.annotation | 定義をスキャンするパッケージ |
@Configuration | org.koin.core.annotation | モジュールの構成ラベル |
@KoinApplication | org.koin.core.annotation | アプリケーションのエントリポイント |
@Monitor | org.koin.core.annotation | Kotzilla SDK によってトレースされる関数 |
定義(Definitions)
定義アノテーションは、クラス(Koinがそのコンストラクタを呼び出します)または関数(Koinがトップレベルまたは @Module クラス内のその関数を呼び出します)に付与します。コンストラクタおよび関数のパラメータはコンテナから解決されます。各パラメータ型の解決方法については、Definitionsを参照してください。
binds が空の場合、定義はそのクラス自身およびそのすべてのスーパータイプにバインドされます。特定の型のみにバインドしたい場合は、binds に型をリストします。
@Singleton / @Single
ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
binds | Array<KClass<*>> | [] | バインドする型。空の場合はすべてのスーパータイプをバインドします |
createdAtStart | Boolean | false | Koin起動時にインスタンスを生成します |
@Singleton(binds = [UserRepository::class])
class UserRepositoryImpl(private val api: ApiService) : UserRepository@Singleton と @Single は等価です。JSR-330 の名称である @Singleton の使用が推奨されます。コンテナのライフタイム中に1つのインスタンスのみが保持されます。概念については Definitions を参照してください。
@Factory
ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
binds | Array<KClass<*>> | [] | バインドする型。空の場合はすべてのスーパータイプをバインドします |
@Factory
class UserPresenter(private val repository: UserRepository)リクエストごとに新しいインスタンスが作成されます。概念については Definitions を参照してください。
@Scoped
ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
binds | Array<KClass<*>> | [] | バインドする型。空の場合はすべてのスーパータイプをバインドします |
@Scope(UserSession::class)
@Scoped
class SessionCache(private val repository: UserRepository)スコープごとに1つのインスタンスが作成され、そのスコープが閉じられると解放されます。@Scope またはスコープアーキタイプ(@ViewModelScope、@ActivityScope など)と一緒に使用します。概念については Scopes を参照してください。
@KoinViewModel
ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
binds | Array<KClass<*>> | [] | バインドする型。空の場合はすべてのスーパータイプをバインドします |
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()Android および Compose Multiplatform ターゲットで動作します。クラスパスに io.insert-koin:koin-core-viewmodel が必要です(存在しない場合、ビルドは KOIN-A001 で失敗します)。概念については ViewModel を参照してください。
NOTE
Compiler Plugin では、@KoinViewModel は org.koin.core.annotation に配置されています。KSPプロセッサでは org.koin.android.annotation.KoinViewModel が使用されていたため、移行時にはインポートを更新してください(Migrating from KSP を参照)。
@KoinWorker
パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
binds | Array<KClass<*>> | [] | バインドする型 |
@KoinWorker
class SyncWorker(
context: Context,
params: WorkerParameters,
private val repository: UserRepository,
) : CoroutineWorker(context, params)io.insert-koin:koin-android-workmanager が必要です(存在しない場合、ビルドは KOIN-A002 で失敗します)。概念については WorkManager を参照してください。
スコープ(Scopes)
@Scope
ターゲット: CLASS, FUNCTION
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | KClass<*> | Unit::class | スコープの型 |
name | String | "" | 型の代わりに使用するスコープ名 |
@Scope(UserSession::class)
class SessionCache(private val repository: UserRepository)
@Scope(name = "checkout")
class CheckoutState定義を指定されたスコープに配置します。単体で使用した場合、@Scope は scoped 定義を宣言します。別の種類の定義を選択する場合や binds を設定する場合は、@Scoped、@Factory、または @KoinViewModel を追加してください。概念については Scopes を参照してください。
@ViewModelScope
ターゲット: CLASS, FUNCTION。パラメータなし。
@ViewModelScope
class UserSessionCache(private val repository: UserRepository)ViewModel のスコープ内に scoped 定義を宣言します。ViewModel と共に作成され、ViewModel が破棄(クリア)されるときに閉じられます。概念については Scopes を参照してください。
@ActivityScope
パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。
@ActivityScope
class ScreenTracker(private val analytics: Analytics)Activity スコープ内に scoped 定義を宣言します。Activity はそのスコープを提供する必要があります(Android Scopes を参照)。
@ActivityRetainedScope
パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。
@ActivityRetainedScope
class FormState構成変更(Configuration Changes)後も維持される、保持された Activity スコープ内に scoped 定義を宣言します。Android Scopes を参照してください。
@FragmentScope
パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。
@FragmentScope
class ListAdapterFactoryFragment スコープ内に scoped 定義を宣言します。Android Scopes を参照してください。
@ScopeId
ターゲット: VALUE_PARAMETER
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | KClass<*> | Unit::class | スコープの型。スコープIDはクラスの完全修飾名になります |
name | String | "" | スコープID |
@Factory
class ProfileService(@ScopeId(name = "user_session") val session: UserSession)現在のスコープではなく、該当するIDを持つスコープからパラメータを解決します(getScope("user_session").get() として生成されます)。スコープは実行時にしか存在しないため、コンパイル時安全性チェックの対象外となります。概念については Scopes を参照してください。
クオリファイア(Qualifiers)
@Named
ターゲット: CLASS, FUNCTION, VALUE_PARAMETER
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | String | "" | 文字列クオリファイア |
type | KClass<*> | Unit::class | 型クオリファイア。Compiler Plugin では代わりに @Qualifier(Type::class) を使用してください |
@Singleton
@Named("local")
class LocalDatabase : Database
@Singleton
class UserRepository(@Named("local") private val database: Database)定義とパラメータに同じ文字列を付けることで、それらが関連付けられます。jakarta.inject.Named および javax.inject.Named も同様に解釈されます。概念については Qualifiers を参照してください。
@Qualifier
ターゲット: CLASS, FUNCTION, VALUE_PARAMETER
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | KClass<*> | Unit::class | 型クオリファイア |
name | String | "" | 文字列クオリファイア |
@Singleton
@Qualifier(Remote::class)
class RemoteDataSource : DataSource
@Singleton
class UserRepository(@Qualifier(Remote::class) private val source: DataSource)@Qualifier は、カスタムクオリファイアアノテーションをマークするためにも使用できます。@Qualifier または @Named(あるいは jakarta.inject.Qualifier、javax.inject.Qualifier)が付与されたアノテーションクラスは、すべてクオリファイアになります。
@Qualifier
annotation class IoDispatcher
@Singleton
@IoDispatcher
fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO引数のないカスタムクオリファイアは、アノテーションクラスに対する型クオリファイアとなります。文字列またはenum引数を持つ場合(@Dispatcher(AppDispatchers.IO) など)、その引数の値がクオリファイアとなります。概念については Qualifiers を参照してください。
パラメータ(Parameters)
@InjectedParam
ターゲット: VALUE_PARAMETER。パラメータなし。
@Factory
class UserPresenter(@InjectedParam val userId: String, private val repository: UserRepository)
// 呼び出し側
val presenter: UserPresenter = get { parametersOf("user-42") }値はコンテナからではなく、呼び出し元の parametersOf(...) から渡されます。コンパイル時安全性チェックにより、呼び出し側が正しい個数と型の値を渡しているかが検証されます(KOIN-D005、KOIN-D006)。概念については Injected Parameters を参照してください。
@Property
ターゲット: VALUE_PARAMETER
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | String | 必須 | プロパティキー |
@Factory
class ApiClient(@Property("api_url") val url: String)getProperty("api_url") を使用してパラメータを解決します。同じキーを持つ @PropertyValue が存在する場合、それがフォールバック値となります。存在しない場合、ビルド時に警告 KOIN-P001 が表示され、起動時にプロパティを設定する必要があります。概念については Properties を参照してください。
@PropertyValue
ターゲット: FIELD
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | String | 必須 | プロパティキー |
@PropertyValue("api_url")
val defaultApiUrl = "https://api.example.com"
@Factory
class ApiClient(@Property("api_url") val url: String)プロパティが設定されていない場合に使用されるデフォルト値を宣言します(getProperty("api_url", defaultApiUrl) として生成されます)。
@Provided
ターゲット: CLASS, FUNCTION, VALUE_PARAMETER。パラメータなし。
@Singleton
class AnalyticsService(@Provided val firebase: FirebaseAnalytics)コンパイラプラグインが見通せる宣言が存在しない場合でも、その型が実行時に利用可能であることをコンパイル時安全性チェックに伝えます(プラットフォームオブジェクト、SDK、後からロードされるモジュールなど)。クラスに付与した場合はその型のすべての使用箇所のチェックがスキップされ、パラメータに付与した場合はそのパラメータのみがスキップされます。実行時の解決ロジックに変更はありません。一般的な Android の型(Context、Activity、Fragment、SavedStateHandle、WorkerParameters など)には付与する必要はありません。概念については Compile-Time Safety を参照してください。
モジュールとアプリケーション(Modules and application)
@Module
ターゲット: CLASS
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
includes | Array<KClass<*>> | [] | インクルードする他の @Module クラス |
createdAtStart | Boolean | false | Koin起動時にモジュールの single 定義を生成します |
@Module(includes = [NetworkModule::class])
class DataModule {
@Singleton
fun database(context: Context): AppDatabase =
Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()
}定義をグループ化します。クラス内のアノテーション付き関数に加え、@ComponentScan によって検出されたアノテーション付きクラスが含まれます。概念については Modules を参照してください。
@ComponentScan
ターゲット: CLASS, FIELD
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | vararg String | 空 | スキャンするパッケージ。空の場合はアノテーション付きクラスのパッケージをスキャンします |
@Module
@ComponentScan("com.myapp.data", "com.myapp.domain")
class AppModule指定されたパッケージおよびそのサブパッケージ内のすべてのアノテーション付きクラスとトップレベル関数を、Gradleモジュールを横断してモジュールに追加します。概念については Modules を参照してください。
NOTE
Compiler Plugin はパッケージ名とそのサブパッケージにマッチします。KSPプロセッサの glob パターン(com.example.**、com.*.service)はサポートされていないため、代わりにパッケージを明示的にリストしてください。
@Configuration
ターゲット: CLASS, FIELD
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
value | vararg String | 空 | 構成ラベル。空の場合は "default" を意味します |
@Module
@ComponentScan
@Configuration
class CoreModule // ラベル "default"
@Module
@Configuration("default", "test")
class FakeDataModule // ラベル "default" および "test"@KoinApplication は、自身の構成ラベルのいずれかを持つすべてのモジュール(他の Gradle モジュールからのモジュールを含む)を、明示的にリストすることなく読み込みます。@Configuration("default") は @Configuration と同等です。概念については Modules を参照してください。
@KoinApplication
ターゲット: CLASS
| パラメータ | 型 | デフォルト値 | 説明 |
|---|---|---|---|
configurations | Array<String> | [] | 読み込む構成ラベル。空の場合は "default" を読み込みます |
modules | Array<KClass<*>> | [Unit::class](なし) | 追加で読み込む @Module クラス |
@KoinApplication(modules = [AppModule::class])
object MyApp
fun main() {
startKoin<MyApp> {
printLogger()
}
}エントリポイントをマークします。startKoin<MyApp>()、koinApplication<MyApp>()、または koinConfiguration<MyApp>()(org.koin.plugin.module.dsl パッケージ)を使用して開始します。ここで、コンパイル時安全性チェックによってグラフ全体が検証されます。@Configuration によるモジュールが最初にロードされ、その後に modules リストがその順序でロードされるため、上書き(オーバーライド)が発生した場合は明示的なリストが優先されます。概念については Starting Koin を参照してください。
モニタリング(Monitoring)
@Monitor
ターゲット: CLASS, FUNCTION。パラメータなし。
@Monitor
class UserService(private val repository: UserRepository) {
fun findUser(id: String): User? = repository.findById(id)
}Compiler Plugin は関数の本体(またはクラスのすべての public 関数)を Kotzilla SDK のトレースでラップします。クラスパスに Kotzilla SDK(io.kotzilla:kotzilla-core)が必要です。存在しない場合、ビルド時に警告 KOIN-M001 が表示され、トレースは行われません。セットアップと収集されるデータについては Monitor を参照してください。
JSR-330 アノテーション
Compiler Plugin は、jakarta.inject および javax.inject のアノテーション(@Singleton、@Named、@Inject、@Qualifier)も解釈します。JSR-330 を参照してください。
削除されたアノテーション
@ExternalDefinition、@MetaDefinition、@MetaModule、および @MetaApplication(org.koin.meta.annotations パッケージ)は、KSPプロセッサが自身の用途のために生成していたものです。Compiler Plugin ではこれらを使用しておらず、手動で記述することもありません。
関連情報
- Definitions: 定義の種類、バインディング、コンストラクタパラメータ。
- Modules: 実践における
@Module、@ComponentScan、および@Configuration。 - Compile-Time Safety: プラグインがこれらのアノテーションから検証する内容。
- Compiler Plugin Options: プラグインの Gradle オプション。
- DSL Reference: 各アノテーションに対応する DSL の同等機能。
