Skip to content

アノテーションリファレンス ​

このページでは、すべての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 / @Singleorg.koin.core.annotationsingle 定義
@Factoryorg.koin.core.annotationfactory 定義
@Scopedorg.koin.core.annotationscoped 定義
@KoinViewModelorg.koin.core.annotationviewModel 定義
@KoinWorkerorg.koin.android.annotationWorkManager の worker 定義
@Scopeorg.koin.core.annotation定義が属するスコープ
@ViewModelScopeorg.koin.core.annotationViewModel スコープ内の定義
@ActivityScopeorg.koin.android.annotationActivity スコープ内の定義
@ActivityRetainedScopeorg.koin.android.annotation保持される(retained)Activity スコープ内の定義
@FragmentScopeorg.koin.android.annotationFragment スコープ内の定義
@ScopeIdorg.koin.core.annotation指定されたスコープから解決されるパラメータ
@Namedorg.koin.core.annotation文字列クオリファイア
@Qualifierorg.koin.core.annotation型または文字列クオリファイア
@InjectedParamorg.koin.core.annotation呼び出し元から渡されるパラメータ
@Propertyorg.koin.core.annotationKoin プロパティから読み取られるパラメータ
@PropertyValueorg.koin.core.annotationプロパティのデフォルト値
@Providedorg.koin.core.annotationチェック対象グラフの外部から提供される型
@Moduleorg.koin.core.annotationモジュールクラス
@ComponentScanorg.koin.core.annotation定義をスキャンするパッケージ
@Configurationorg.koin.core.annotationモジュールの構成ラベル
@KoinApplicationorg.koin.core.annotationアプリケーションのエントリポイント
@Monitororg.koin.core.annotationKotzilla SDK によってトレースされる関数

定義(Definitions) ​

定義アノテーションは、クラス(Koinがそのコンストラクタを呼び出します)または関数(Koinがトップレベルまたは @Module クラス内のその関数を呼び出します)に付与します。コンストラクタおよび関数のパラメータはコンテナから解決されます。各パラメータ型の解決方法については、Definitionsを参照してください。

binds が空の場合、定義はそのクラス自身およびそのすべてのスーパータイプにバインドされます。特定の型のみにバインドしたい場合は、binds に型をリストします。

@Singleton / @Single ​

ターゲット: CLASS, FUNCTION

パラメータ型デフォルト値説明
bindsArray<KClass<*>>[]バインドする型。空の場合はすべてのスーパータイプをバインドします
createdAtStartBooleanfalseKoin起動時にインスタンスを生成します
kotlin
@Singleton(binds = [UserRepository::class])
class UserRepositoryImpl(private val api: ApiService) : UserRepository

@Singleton と @Single は等価です。JSR-330 の名称である @Singleton の使用が推奨されます。コンテナのライフタイム中に1つのインスタンスのみが保持されます。概念については Definitions を参照してください。

@Factory ​

ターゲット: CLASS, FUNCTION

パラメータ型デフォルト値説明
bindsArray<KClass<*>>[]バインドする型。空の場合はすべてのスーパータイプをバインドします
kotlin
@Factory
class UserPresenter(private val repository: UserRepository)

リクエストごとに新しいインスタンスが作成されます。概念については Definitions を参照してください。

@Scoped ​

ターゲット: CLASS, FUNCTION

パラメータ型デフォルト値説明
bindsArray<KClass<*>>[]バインドする型。空の場合はすべてのスーパータイプをバインドします
kotlin
@Scope(UserSession::class)
@Scoped
class SessionCache(private val repository: UserRepository)

スコープごとに1つのインスタンスが作成され、そのスコープが閉じられると解放されます。@Scope またはスコープアーキタイプ(@ViewModelScope、@ActivityScope など)と一緒に使用します。概念については Scopes を参照してください。

@KoinViewModel ​

ターゲット: CLASS, FUNCTION

パラメータ型デフォルト値説明
bindsArray<KClass<*>>[]バインドする型。空の場合はすべてのスーパータイプをバインドします
kotlin
@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

パラメータ型デフォルト値説明
bindsArray<KClass<*>>[]バインドする型
kotlin
@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

パラメータ型デフォルト値説明
valueKClass<*>Unit::classスコープの型
nameString""型の代わりに使用するスコープ名
kotlin
@Scope(UserSession::class)
class SessionCache(private val repository: UserRepository)

@Scope(name = "checkout")
class CheckoutState

定義を指定されたスコープに配置します。単体で使用した場合、@Scope は scoped 定義を宣言します。別の種類の定義を選択する場合や binds を設定する場合は、@Scoped、@Factory、または @KoinViewModel を追加してください。概念については Scopes を参照してください。

@ViewModelScope ​

ターゲット: CLASS, FUNCTION。パラメータなし。

kotlin
@ViewModelScope
class UserSessionCache(private val repository: UserRepository)

ViewModel のスコープ内に scoped 定義を宣言します。ViewModel と共に作成され、ViewModel が破棄(クリア)されるときに閉じられます。概念については Scopes を参照してください。

@ActivityScope ​

パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。

kotlin
@ActivityScope
class ScreenTracker(private val analytics: Analytics)

Activity スコープ内に scoped 定義を宣言します。Activity はそのスコープを提供する必要があります(Android Scopes を参照)。

@ActivityRetainedScope ​

パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。

kotlin
@ActivityRetainedScope
class FormState

構成変更(Configuration Changes)後も維持される、保持された Activity スコープ内に scoped 定義を宣言します。Android Scopes を参照してください。

@FragmentScope ​

パッケージ: org.koin.android.annotation(Android のみ)。ターゲット: CLASS, FUNCTION。パラメータなし。

kotlin
@FragmentScope
class ListAdapterFactory

Fragment スコープ内に scoped 定義を宣言します。Android Scopes を参照してください。

@ScopeId ​

ターゲット: VALUE_PARAMETER

パラメータ型デフォルト値説明
valueKClass<*>Unit::classスコープの型。スコープIDはクラスの完全修飾名になります
nameString""スコープID
kotlin
@Factory
class ProfileService(@ScopeId(name = "user_session") val session: UserSession)

現在のスコープではなく、該当するIDを持つスコープからパラメータを解決します(getScope("user_session").get() として生成されます)。スコープは実行時にしか存在しないため、コンパイル時安全性チェックの対象外となります。概念については Scopes を参照してください。

クオリファイア(Qualifiers) ​

@Named ​

ターゲット: CLASS, FUNCTION, VALUE_PARAMETER

パラメータ型デフォルト値説明
valueString""文字列クオリファイア
typeKClass<*>Unit::class型クオリファイア。Compiler Plugin では代わりに @Qualifier(Type::class) を使用してください
kotlin
@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

パラメータ型デフォルト値説明
valueKClass<*>Unit::class型クオリファイア
nameString""文字列クオリファイア
kotlin
@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)が付与されたアノテーションクラスは、すべてクオリファイアになります。

kotlin
@Qualifier
annotation class IoDispatcher

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

引数のないカスタムクオリファイアは、アノテーションクラスに対する型クオリファイアとなります。文字列またはenum引数を持つ場合(@Dispatcher(AppDispatchers.IO) など)、その引数の値がクオリファイアとなります。概念については Qualifiers を参照してください。

パラメータ(Parameters) ​

@InjectedParam ​

ターゲット: VALUE_PARAMETER。パラメータなし。

kotlin
@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

パラメータ型デフォルト値説明
valueString必須プロパティキー
kotlin
@Factory
class ApiClient(@Property("api_url") val url: String)

getProperty("api_url") を使用してパラメータを解決します。同じキーを持つ @PropertyValue が存在する場合、それがフォールバック値となります。存在しない場合、ビルド時に警告 KOIN-P001 が表示され、起動時にプロパティを設定する必要があります。概念については Properties を参照してください。

@PropertyValue ​

ターゲット: FIELD

パラメータ型デフォルト値説明
valueString必須プロパティキー
kotlin
@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。パラメータなし。

kotlin
@Singleton
class AnalyticsService(@Provided val firebase: FirebaseAnalytics)

コンパイラプラグインが見通せる宣言が存在しない場合でも、その型が実行時に利用可能であることをコンパイル時安全性チェックに伝えます(プラットフォームオブジェクト、SDK、後からロードされるモジュールなど)。クラスに付与した場合はその型のすべての使用箇所のチェックがスキップされ、パラメータに付与した場合はそのパラメータのみがスキップされます。実行時の解決ロジックに変更はありません。一般的な Android の型(Context、Activity、Fragment、SavedStateHandle、WorkerParameters など)には付与する必要はありません。概念については Compile-Time Safety を参照してください。

モジュールとアプリケーション(Modules and application) ​

@Module ​

ターゲット: CLASS

パラメータ型デフォルト値説明
includesArray<KClass<*>>[]インクルードする他の @Module クラス
createdAtStartBooleanfalseKoin起動時にモジュールの single 定義を生成します
kotlin
@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

パラメータ型デフォルト値説明
valuevararg String空スキャンするパッケージ。空の場合はアノテーション付きクラスのパッケージをスキャンします
kotlin
@Module
@ComponentScan("com.myapp.data", "com.myapp.domain")
class AppModule

指定されたパッケージおよびそのサブパッケージ内のすべてのアノテーション付きクラスとトップレベル関数を、Gradleモジュールを横断してモジュールに追加します。概念については Modules を参照してください。

NOTE

Compiler Plugin はパッケージ名とそのサブパッケージにマッチします。KSPプロセッサの glob パターン(com.example.**、com.*.service)はサポートされていないため、代わりにパッケージを明示的にリストしてください。

@Configuration ​

ターゲット: CLASS, FIELD

パラメータ型デフォルト値説明
valuevararg String空構成ラベル。空の場合は "default" を意味します
kotlin
@Module
@ComponentScan
@Configuration
class CoreModule            // ラベル "default"

@Module
@Configuration("default", "test")
class FakeDataModule        // ラベル "default" および "test"

@KoinApplication は、自身の構成ラベルのいずれかを持つすべてのモジュール(他の Gradle モジュールからのモジュールを含む)を、明示的にリストすることなく読み込みます。@Configuration("default") は @Configuration と同等です。概念については Modules を参照してください。

@KoinApplication ​

ターゲット: CLASS

パラメータ型デフォルト値説明
configurationsArray<String>[]読み込む構成ラベル。空の場合は "default" を読み込みます
modulesArray<KClass<*>>[Unit::class](なし)追加で読み込む @Module クラス
kotlin
@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。パラメータなし。

kotlin
@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 の同等機能。