基本概念
このページでは、ひとつの小さなサンプルをステップバイステップで構築しながら、他のすべてのページのベースとなる概念(定義、モジュール、Koinコンテナ、インジェクション、スコープ、クォリファイア、コンパイル時チェック)について解説します。各セクションは簡潔にまとめられており、詳細を説明するページへのリンクが含まれています。なお、依存性の注入(Dependency Injection)についての知識があることを前提としています(依存性の注入とは? を参照)。
コードサンプルは、「Compiler Plugin DSL」、「Annotations」、「Constructor / Classic DSL」の3つのタブで提供されています。好みのスタイルを選択してください。この選択はすべてのページに共通して適用されます。どのスタイルを使用すべきか迷った場合は、スタイルの選択 をお読みください。
サンプル
3つの純粋なKotlinクラスです。それぞれがコンストラクタで必要な依存関係を受け取り、Koinについては何も知りません:
class ApiService
class UserRepository(private val api: ApiService)
class UserViewModel(private val repository: UserRepository) : ViewModel()Koinの役割は、手動で依存関係の配線(ワイヤリング)を書くことなく、ApiService を作成してそれを UserRepository に渡し、さらにそれを UserViewModel に渡すことです。
定義(Definition)
定義(definition)は、Koinに対して特定の型のインスタンスをどのように作成し、そのインスタンスをどのくらいの期間保持するかを伝えます:
single<ApiService>()
single<UserRepository>()
viewModel<UserViewModel>()@Singleton
class ApiService
@Singleton
class UserRepository(private val api: ApiService)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()singleOf(::ApiService)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)キーワードによってライフタイム(生存期間)が設定されます。single はコンテナ全体で単一のインスタンスを保持します。factory はリクエストごとに新しいインスタンスを作成します。viewModel はViewModelのライフサイクルに従います。Koinは UserRepository のコンストラクタを読み取り、ApiService が必要であることを認識して、コンテナからそれを解決します。
詳細: 定義
モジュール(Module)
モジュール(module)は定義をグループ化します。通常、機能やレイヤーごとに1つのモジュールを作成します:
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*
val appModule = module {
single<ApiService>()
single<UserRepository>()
viewModel<UserViewModel>()
}@Module
@ComponentScan("com.example.app")
class AppModule@ComponentScan は、パッケージ com.example.app とそのサブパッケージ内にあるすべてのアノテーション付きクラスを収集します。
import org.koin.dsl.module
import org.koin.core.module.dsl.*
val appModule = module {
singleOf(::ApiService)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
}モジュールは単なる宣言にすぎません。Koinが起動し、誰かがインスタンスを要求するまでは何も作成されません。モジュールには他のモジュールを含めることができるため、大規模なアプリは小さなモジュールのツリー構造になります。
詳細: モジュール
Koinコンテナ
startKoin はコンテナ(KoinApplication)を作成し、そこにモジュールをロードします。アプリのエントリポイントで1回だけ呼び出します:
fun main() {
startKoin {
modules(appModule)
}
}import org.koin.plugin.module.dsl.startKoin
@KoinApplication(modules = [AppModule::class])
class MyApp
fun main() {
startKoin<MyApp>()
}fun main() {
startKoin {
modules(appModule)
}
}Androidでは Application.onCreate() 内で呼び出し、androidContext(this) でAndroidコンテキストを渡します。コンテナは定義とこれまでに作成されたインスタンスを保持します。stopKoin() を呼び出すとコンテナが閉じられ、すべての single が解放されます。
詳細: Koinの起動、および AndroidでのKoinの起動
インジェクション(Injection)
オブジェクトが依存関係を取得する方法には2つあります。
コンストラクタインジェクション(Constructor injection):依存関係はコンストラクタのパラメータとなり、Koinがオブジェクトを作成する際にそれを渡します。このサンプルの UserRepository と UserViewModel はすでにこれを使用しています。これがデフォルトの方法です。クラスは純粋なKotlinのままであり、フェイク(モック)を渡してコンストラクタを呼び出すことでテストできます。
コンテナからの取得(Retrieving from the container):一部のクラスは、Koinではなくフレームワークによって作成されます(Androidの Activity、Composable、Ktorのルートなど)。これらは get()(即時)または inject()(初回アクセス時の遅延初期化)を使ってコンテナに問い合わせます:
import org.koin.androidx.viewmodel.ext.android.viewModel
class UserActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
}import org.koin.compose.viewmodel.koinViewModel
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
...
}コンテナからの取得方法はどのスタイルでも同じです。この取得処理はこれらのエントリポイントに限定し、それ以降の階層ではすべてコンストラクタインジェクションを使用するようにしてください。
詳細: 依存関係の取得、Androidエントリポイント、Compose向けKoin
グラフ(The graph)
これらをまとめると、コンテナは次のようなグラフを保持します:
startKoin
└── appModule
├── single ApiService
├── single UserRepository ── needs ── ApiService
└── viewModel UserViewModel ── needs ── UserRepository
UserActivity ── by viewModel() ──> UserViewModelUserActivity が UserViewModel を要求すると、Koinは ApiService を(1回だけ)作成し、次に UserRepository を(1回だけ)作成し、最後にActivityのViewModelライフサイクルにバインドされた UserViewModel を作成します。
スコープ(Scope)
single はコンテナが存在する限り存続し、factory は呼び出し元が保持している間のみ存続します。スコープ(scope)はその中間をカバーするもので、ユーザーセッション、画面、リクエストなど、特定のライフサイクルに合わせて存続するインスタンスを扱います。
例えば、ユーザーがログインしている間だけ CartRepository が存在すべきだとします:
class UserSession
class CartRepository(private val api: ApiService)
val sessionModule = module {
scope<UserSession> {
scoped<CartRepository>()
}
}class UserSession
@Scope(UserSession::class)
@Scoped
class CartRepository(private val api: ApiService)class UserSession
class CartRepository(private val api: ApiService)
val sessionModule = module {
scope<UserSession> {
scopedOf(::CartRepository)
}
}セッション開始時にスコープを開き、セッション終了時にそれを閉じます:
// KoinComponentの内部
val sessionScope = getKoin().createScope<UserSession>("session-42")
val cart: CartRepository = sessionScope.get()
sessionScope.close() // CartRepositoryを解放スコープ付きの定義は、ルートコンテナの定義(ここでは ApiService)を利用できます。Androidでは、KoinがActivity、Fragment、ViewModel向けの定義済みスコープを提供しているため、手動でスコープを作成することはほとんどありません。
詳細: スコープ、および Androidスコープ
クォリファイア(Qualifier)
Koinは型によって定義を検索します。2つの定義が同じ型を提供する場合は、クォリファイア(qualifier)を使ってそれぞれに名前を付与します:
interface NetworkClient
@Named("auth")
class AuthClient : NetworkClient
@Named("public")
class PublicClient : NetworkClient
class UserRepository(@Named("auth") private val client: NetworkClient)
val networkModule = module {
single<AuthClient>() bind NetworkClient::class
single<PublicClient>() bind NetworkClient::class
single<UserRepository>()
}@Singleton
@Named("auth")
class AuthClient : NetworkClient
@Singleton
@Named("public")
class PublicClient : NetworkClient
@Singleton
class UserRepository(@Named("auth") private val client: NetworkClient)val networkModule = module {
single<NetworkClient>(named("auth")) { AuthClient() }
single<NetworkClient>(named("public")) { PublicClient() }
single { UserRepository(get(named("auth"))) }
}詳細: クォリファイア
コンパイル時チェック
Compiler Pluginを使用しない場合、定義の不足はコードの実行時に発覚します(get() が NoDefinitionFoundException をスローします)。Koin Compiler Plugin を使用すると、同じミスでもビルド時に失敗するようになります。もし appModule から single<ApiService>() を削除すると、コンパイルは次のように停止します:
[Koin][KOIN-D001] Missing dependency: ApiService
required by: UserRepository (parameter 'api')
in module: ...プラグインは、各エントリポイント(startKoin、@KoinApplication、Ktorの install(Koin))およびすべての get()、inject()、koinViewModel() の呼び出しにおいて、グラフ全体をチェックします。プラグインを使用せずにConstructor DSLまたはClassic DSLを使用する場合は、ユニットテスト内で verify() を使用することで同様のチェックを行えます。
詳細: コンパイル時の安全性、Koin設定の検証
