在 Android 專案中導入 Hilt 依賴注入框架指南

【Android Hilt 依賴注入完整教學】系列文章目錄：連結

Youtube 教學頻道：HKT線上教室

在開發 Android 應用程式時，相依性注入（Dependency Injection）是一個非常重要的設計模式，能夠幫助我們建立更好的程式架構。今天要介紹的 Hilt 是由 Google 官方推出的相依性注入框架，它是基於 Dagger 所開發的，但提供了更簡單的使用方式。

Hilt 的優勢

相較於其他相依性注入框架（如 Dagger、Koin 等），Hilt 具有以下優點：

• 設定簡單，學習曲線較緩
• 與 Android 架構元件完美整合
• Google 官方維護，確保長期支援
• 基於 Dagger 開發，效能優異

專案設定步驟

本篇教學採用 Kotlin DSL 語法來撰寫 Gradle 設定檔。如果你的專案還在使用傳統的 Groovy 語法，可以參考 Android Developer 官方文件的說明來調整語法。由於目前業界主流已逐漸轉向使用 Kotlin DSL，本文將著重介紹這個版本的設定方式。

1. 在根目錄的 build.gradle 加入 Hilt 外掛程式

首先，在專案根目錄的 build.gradle 檔案中加入以下設定：

plugins {
    // 其他外掛程式...
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
}

2. 設定應用程式模組的 build.gradle

在應用程式模組的 build.gradle 中，需要啟用以下外掛程式並加入相依套件：

plugins {
    id("kotlin-kapt")  // 用於註解處理
    id("com.google.dagger.hilt.android")
}

android {
    // 啟用 Java 17 功能支援
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

dependencies {
    implementation("com.google.dagger:hilt-android:2.51.1")
    kapt("com.google.dagger:hilt-android-compiler:2.51.1")
}

// 允許參考產生的程式碼
kapt {
    correctErrorTypes = true
}

3. 建立應用程式類別

建立一個繼承 Application 的類別，並加上 @HiltAndroidApp 註解：

@HiltAndroidApp
class MyApplication : Application() {
}

4. 在 AndroidManifest.xml 中註冊

在 AndroidManifest.xml 中設定應用程式類別：

<application
    android:name=".MyApplication"
    ... >

5. 在元件中使用相依性注入

要在 Activity、Fragment、Service 或 BroadcastReceiver 中使用相依性注入，需要加上 @AndroidEntryPoint 註解：

@AndroidEntryPoint
class MainActivity : AppCompatActivity() {
    // 在這裡進行相依性注入
}

使用 Version Catalog 管理相依性

如果你的專案使用了 Gradle 的 Version Catalog 功能（即 libs.versions.toml），以下是建議的設定方式：

在 gradle/libs.versions.toml 中宣告版本

[versions]
hilt = "2.51.1"
hiltExt = "1.2.0"
agp = "8.2.2"  # Android Gradle Plugin 版本
kotlin = "1.9.22"  # Kotlin 版本

[libraries]
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-android-compiler", version.ref = "hilt" }
# Hilt Extensions 相關套件
hilt-ext-compiler = { group = "androidx.hilt", name = "hilt-compiler", version.ref = "hiltExt" }
hilt-ext-work = { group = "androidx.hilt", name = "hilt-work", version.ref = "hiltExt" }
hilt-ext-navigation = { group = "androidx.hilt", name = "hilt-navigation-compose", version.ref = "hiltExt" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version = "1.9.22-1.0.17" }  # KSP 版本需要與 Kotlin 版本相匹配
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }

在應用程式模組的 build.gradle.kts 中使用

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.ksp)  // 使用 KSP 取代 kapt
    alias(libs.plugins.hilt)
}

android {
    // 啟用 Java 17 功能支援
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)  // 使用 KSP 取代 kapt
    
    // Hilt Extensions 相關依賴
    ksp(libs.hilt.ext.compiler)  // 使用 KSP 取代 kapt
    
    // 根據需求選擇性添加：
    // WorkManager 整合
    implementation(libs.hilt.ext.work)
    // Jetpack Compose Navigation 整合
    implementation(libs.hilt.ext.navigation)
}

結語

以上就是在 Android 專案中設定 Hilt 的基本步驟。相較於直接使用 Dagger，Hilt 大幅簡化了相依性注入的設定流程。在下一篇文章中，我們將介紹如何使用 Hilt 進行欄位注入（Field Injection）的實作。