Hilt 依赖注入基础

Hilt 是 Android 官方基于 Dagger 打造的依赖注入（DI）框架，专为 Android 组件生命周期做了深度集成。本章将围绕 Hilt 的核心概念、组件层级、作用域规则以及模块编写方式展开，为后续的懒加载与启动优化打下理论基石。

核心概念

• 依赖注入（DI）：对象不自行创建依赖，而是通过外部传入。Hilt 在编译期生成代码，运行时为 Android 组件自动注入依赖。
• 组件（Component）：Hilt 预定义的容器，每个 Android 组件（Application、Activity、Fragment、View、Service 等）都对应一个 Hilt 组件，负责管理该组件生命周期内的依赖实例。
• 模块（Module）：用 @Module 标注的类，告诉 Hilt 如何提供无法通过 @Inject 构造的类的实例（如第三方库或接口实现）。
• 作用域（Scope）：通过 @Singleton、@ActivityScoped 等注解，控制依赖实例在指定组件生命周期内是单例还是每次注入都新建。

Hilt 组件层级与生命周期

Hilt 按照 Android 组件树预定义了一套组件层级图，每个组件对应一个生命周期作用域。下图展示了主要组件及其层级关系：

作用域规则

Hilt 提供了 6 个预定义的作用域注解，它们与组件生命周期严格绑定：

模块与提供方式

当依赖无法通过 @Inject 构造函数标注时（如接口、第三方库类），需要编写模块。

模块声明

@Module
@InstallIn(ApplicationComponent.class)
public class NetworkModule {

    @Provides
    @Singleton
    public OkHttpClient provideOkHttpClient() {
        return new OkHttpClient.Builder()
                .connectTimeout(30, TimeUnit.SECONDS)
                .build();
    }

    @Provides
    @Singleton
    public Retrofit provideRetrofit(OkHttpClient client) {
        return new Retrofit.Builder()
                .baseUrl("https://api.example.com")
                .client(client)
                .addConverterFactory(GsonConverterFactory.create())
                .build();
    }
}

绑定接口实现

@Module
@InstallIn(ActivityComponent.class)
public abstract class AuthModule {

    @Binds
    @ActivityScoped
    public abstract AuthService bindAuthService(AuthServiceImpl impl);
}

常见错误与调试

• MissingBinding：编译期报错，Hilt 无法找到某个依赖的提供者。检查是否漏加 @Inject 构造函数或模块。
• DuplicateBinding：同一类型有多个提供者。使用 @Qualifier（如 @Named("cache")）区分。
• ComponentTree 不一致：如在 Application 中注入 @ActivityScoped 的依赖，编译期直接报错。遵循组件层级注入。
• 调试技巧：启用 Hilt 编译器参数 -Adagger.fastInit=ENABLED 可以加速编译；使用 @HiltViewModel 结合 hiltViewModel() 在 Fragment 中获取 ViewModel 时，确保 ViewModel 所在 Fragment 使用 @AndroidEntryPoint 注解。

// 典型调试日志（编译期）
error: [Dagger/MissingBinding] com.example.data.Repository cannot be provided without an @Provides-annotated method.
// 解决方案：在模块中添加 @Provides Repository provideRepository(...)