依赖注入

// ❌ 传统方式：LoginViewModel 自己"控制"着所有依赖的创建
class LoginViewModel {
    // LoginViewModel 主动创建了 LoginRepository 实例
    private val repository = LoginRepository(
        // LoginRepository 又需要自己创建 RemoteDataSource
        RemoteDataSource(
            // RemoteDataSource 内部还需要自己创建 Retrofit 实例
            RetrofitClient.create()
        ),
        // 同时还需要自己创建 LocalDataSource
        LocalDataSource(
            // LocalDataSource 需要 Room 数据库实例
            AppDatabase.getInstance().loginDao()
        )
    )
}

// ✅ IoC 方式：LoginViewModel 不再控制依赖创建，而是被动接收
class LoginViewModel(
    // 依赖由外部传入，LoginViewModel 不关心它是怎么创建的
    private val repository: LoginRepository
) {
    // 直接使用 repository，无需了解其内部结构
    fun login(username: String, password: String) {
        // repository 已经被正确初始化，直接调用即可
        repository.authenticate(username, password)
    }
}

// ❌ 违反 DIP：高层 ViewModel 直接依赖低层的具体实现类
class OrderViewModel(
    // 直接依赖具体类 OrderRepositoryImpl，而非抽象接口
    private val repository: OrderRepositoryImpl
)
 
// 具体实现类，内部绑定了 Retrofit 和 Room
class OrderRepositoryImpl(
    // 直接依赖具体的 Retrofit 接口实现
    private val api: OrderRetrofitService,
    // 直接依赖具体的 Room DAO 实现
    private val dao: OrderDao
) {
    // 获取订单的具体实现
    fun getOrders(): List<Order> {
        // 先尝试从网络获取
        val remote = api.fetchOrders()
        // 缓存到本地数据库
        dao.insertAll(remote)
        // 返回结果
        return remote
    }
}

// ✅ 遵守 DIP：定义抽象接口，高层和低层都依赖它
 
// 抽象层：定义 Repository 的契约（接口）
interface OrderRepository {
    // 只声明"做什么"，不关心"怎么做"
    suspend fun getOrders(): List<Order>
}
 
// 低层模块：实现具体细节，依赖于上面定义的抽象
class OrderRepositoryImpl(
    // 同样，DataSource 也应该是抽象接口
    private val remoteSource: OrderRemoteDataSource,
    private val localSource: OrderLocalDataSource
) : OrderRepository {
    // 实现接口定义的方法
    override suspend fun getOrders(): List<Order> {
        // 从远程数据源获取
        val orders = remoteSource.fetch()
        // 存入本地数据源
        localSource.save(orders)
        // 返回订单列表
        return orders
    }
}
 
// 高层模块：只依赖抽象接口 OrderRepository
class OrderViewModel(
    // 注入的是接口类型，而非具体实现
    private val repository: OrderRepository
) : ViewModel() {
    // 使用接口方法，完全不知道底层是 Retrofit + Room 还是其他技术
    fun loadOrders() {
        viewModelScope.launch {
            // 通过抽象接口调用，与具体实现解耦
            val orders = repository.getOrders()
            // 更新 UI 状态...
        }
    }
}

// ✅ 构造器注入：通过 @Inject constructor 声明依赖
class OrderRepository @Inject constructor(
    // Hilt 在创建 OrderRepository 时，会自动提供 OrderApi 的实例
    private val api: OrderApi,
    // 同时自动提供 OrderDao 的实例
    private val dao: OrderDao,
    // 以及 CoroutineDispatcher 的实例（需要通过 @Qualifier 指定具体类型）
    @IoDispatcher private val dispatcher: CoroutineDispatcher
) {
    // 所有依赖在对象诞生的那一刻就已经准备好了
    // 不存在"对象已创建但依赖还没到位"的中间状态
    suspend fun getOrders(): List<Order> = withContext(dispatcher) {
        // 安全地使用 api 和 dao，它们一定不为 null
        val remote = api.fetchOrders()
        dao.insertAll(remote)
        remote
    }
}

// 测试时直接通过构造函数传入假依赖，无需 Hilt 或任何框架
@Test
fun `getOrders returns remote data`() = runTest {
    // 创建一个假的 API 实现
    val fakeApi = FakeOrderApi(testOrders)
    // 创建一个假的 DAO 实现
    val fakeDao = FakeOrderDao()
    // 直接通过构造器注入假依赖
    val repository = OrderRepository(
        api = fakeApi,
        dao = fakeDao,
        dispatcher = testDispatcher
    )
    // 调用被测方法
    val result = repository.getOrders()
    // 断言结果
    assertEquals(testOrders, result)
}

// ⚠️ 字段注入：依赖通过 @Inject 标注在属性上
@AndroidEntryPoint
class OrderActivity : AppCompatActivity() {
    // Hilt 会在 Activity 创建后，通过生成的代码为该字段赋值
    // 注意：必须是 lateinit var，不能是 private，不能是 val
    @Inject
    lateinit var repository: OrderRepository
 
    // 同样通过字段注入获取 Analytics 实例
    @Inject
    lateinit var analytics: Analytics
 
    override fun onCreate(savedInstanceState: Bundle?) {
        // super.onCreate() 内部会触发 Hilt 的注入逻辑
        // 在此之后 repository 和 analytics 才可安全使用
        super.onCreate(savedInstanceState)
        // 此时字段已被注入，可以安全调用
        repository.getOrders()
    }
}

class OrderProcessor @Inject constructor(
    // 主要依赖通过构造器注入
    private val repository: OrderRepository
) {
    // 声明一个 lateinit 变量来接收方法注入的依赖
    private lateinit var logger: Logger
 
    // @Inject 标注在方法上：Hilt 在完成构造器注入后，会自动调用此方法
    // 适用于需要在注入阶段执行某些初始化逻辑的场景
    @Inject
    fun init(logger: Logger) {
        // 方法体内既可以赋值，也可以执行额外的初始化操作
        this.logger = logger
        // 比如根据注入的 logger 配置打印日志
        logger.d("OrderProcessor initialized")
    }
}

// @Module 标记此类为 Hilt 模块，是绑定声明的容器
@Module
// @InstallIn 指定此模块中的所有绑定安装到 SingletonComponent 中
// 即这些绑定的可见性和最长生命周期与 Application 一致
@InstallIn(SingletonComponent::class)
object NetworkModule {
 
    // @Provides 告诉 Hilt：当有人需要 OkHttpClient 时，调用此方法创建
    // @Singleton 保证在整个 SingletonComponent 中只创建一次
    @Provides
    @Singleton
    fun provideOkHttpClient(): OkHttpClient {
        // 使用 Builder 模式构造 OkHttpClient 实例
        return OkHttpClient.Builder()
            // 设置连接超时为 30 秒
            .connectTimeout(30, TimeUnit.SECONDS)
            // 设置读取超时为 30 秒
            .readTimeout(30, TimeUnit.SECONDS)
            // 构建最终的 OkHttpClient 实例
            .build()
    }
 
    // 当需要 Retrofit 实例时，Hilt 会自动先解析参数 okHttpClient
    // 由于上面已经声明了 OkHttpClient 的提供方式，Hilt 能自动注入此参数
    @Provides
    @Singleton
    fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit {
        // 使用 Retrofit Builder 构建实例
        return Retrofit.Builder()
            // 设置基础 URL
            .baseUrl("https://api.example.com/")
            // 将上面提供的 OkHttpClient 设置为网络客户端
            .client(okHttpClient)
            // 添加 Gson 作为 JSON 转换器
            .addConverterFactory(GsonConverterFactory.create())
            // 构建最终的 Retrofit 实例
            .build()
    }
 
    // 从 Retrofit 实例中创建具体的 API 接口代理
    @Provides
    @Singleton
    fun provideUserApi(retrofit: Retrofit): UserApi {
        // Retrofit 的 create 方法通过动态代理生成接口实现
        return retrofit.create(UserApi::class.java)
    }
}

// 使用 abstract class 因为包含 @Binds 抽象方法
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
 
    // @Binds 将接口 UserRepository 绑定到实现类 UserRepositoryImpl
    // 当有人注入 UserRepository 时，Hilt 会提供 UserRepositoryImpl 的实例
    @Binds
    @Singleton
    abstract fun bindUserRepository(
        // 参数是具体实现类，Hilt 通过其构造器注入来创建
        impl: UserRepositoryImpl
    ): UserRepository
 
    // companion object 中放置 @Provides 方法
    companion object {
        // 提供需要特殊配置的依赖
        @Provides
        @Singleton
        fun provideUserDao(database: AppDatabase): UserDao {
            // 从 Room Database 获取 DAO 实例
            return database.userDao()
        }
    }
}

// 安装到单个 Component
// 此模块中的所有绑定在 SingletonComponent 及其所有子 Component 中可见
@Module
@InstallIn(SingletonComponent::class)
object SingleModule { /* ... */ }
 
// 安装到多个 Component（较少使用）
// 此模块的绑定在 ActivityComponent 和 ServiceComponent 中均可见
// 但不在 SingletonComponent 中可见（除非它是父 Component）
@Module
@InstallIn(ActivityComponent::class, ServiceComponent::class)
object MultiInstallModule { /* ... */ }

// 定义一个 EntryPoint 接口
// @EntryPoint 标记此接口为 Hilt 的入口点
@EntryPoint
// @InstallIn 指定此入口点安装到 SingletonComponent
// 意味着只能访问 SingletonComponent 中可见的绑定
@InstallIn(SingletonComponent::class)
interface AnalyticsEntryPoint {
    // 声明需要获取的依赖类型
    // 方法名任意，返回类型决定了获取哪个绑定
    fun analyticsService(): AnalyticsService
 
    // 可以声明多个依赖获取方法
    fun crashReporter(): CrashReporter
}

// 在 ContentProvider 中使用 EntryPoint
class MyContentProvider : ContentProvider() {
 
    override fun onCreate(): Boolean {
        // 通过 EntryPointAccessors 从 Application context 获取入口点
        // fromApplication() 对应 SingletonComponent
        val entryPoint = EntryPointAccessors.fromApplication(
            // 获取 Application Context
            context!!.applicationContext,
            // 传入 EntryPoint 接口的 Class
            AnalyticsEntryPoint::class.java
        )
        // 通过接口方法获取依赖实例
        val analyticsService = entryPoint.analyticsService()
        // 现在可以正常使用 analyticsService
        analyticsService.trackEvent("content_provider_created")
        return true
    }
 
    // ... 其他 ContentProvider 方法
    override fun query(uri: Uri, proj: Array<String>?, sel: String?,
                       selArgs: Array<String>?, sort: String?): Cursor? = null
    override fun getType(uri: Uri): String? = null
    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
    override fun delete(uri: Uri, sel: String?, selArgs: Array<String>?): Int = 0
    override fun update(uri: Uri, values: ContentValues?,
                        sel: String?, selArgs: Array<String>?): Int = 0
}

// 从 Application 获取 —— 访问 SingletonComponent 中的绑定
val singletonEntryPoint = EntryPointAccessors.fromApplication(
    context.applicationContext,       // Application Context
    MySingletonEntryPoint::class.java // EntryPoint 接口
)
 
// 从 Activity 获取 —— 访问 ActivityComponent 中的绑定
val activityEntryPoint = EntryPointAccessors.fromActivity(
    activity,                         // Activity 实例
    MyActivityEntryPoint::class.java  // EntryPoint 接口
)
 
// 从 Fragment 获取 —— 访问 FragmentComponent 中的绑定
val fragmentEntryPoint = EntryPointAccessors.fromFragment(
    fragment,                          // Fragment 实例
    MyFragmentEntryPoint::class.java   // EntryPoint 接口
)

// 自定义 WorkManager 的初始化器
// 此类由 AndroidX Startup 库实例化，不受 Hilt 管控
class CustomWorkManagerInitializer : Initializer<WorkManager> {
 
    override fun create(context: Context): WorkManager {
        // 通过 EntryPoint 获取自定义的 WorkerFactory
        val entryPoint = EntryPointAccessors.fromApplication(
            // 使用 applicationContext 确保获取的是 Application 级别 Context
            context.applicationContext,
            // 指定 EntryPoint 接口
            WorkManagerEntryPoint::class.java
        )
 
        // 构建 WorkManager 的自定义配置
        val config = Configuration.Builder()
            // 使用通过 EntryPoint 获取的 WorkerFactory
            .setWorkerFactory(entryPoint.workerFactory())
            // 设置最小日志级别
            .setMinimumLoggingLevel(Log.INFO)
            // 构建配置
            .build()
 
        // 用自定义配置初始化 WorkManager
        WorkManager.initialize(context, config)
        // 返回 WorkManager 实例
        return WorkManager.getInstance(context)
    }
 
    // 声明此初始化器没有依赖其他初始化器
    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
}
 
// 对应的 EntryPoint 接口定义
@EntryPoint
@InstallIn(SingletonComponent::class)
interface WorkManagerEntryPoint {
    // 获取 Hilt 管理的 HiltWorkerFactory
    fun workerFactory(): HiltWorkerFactory
}

@Module
@InstallIn(SingletonComponent::class)
object CacheModule {
    @Provides
    fun provideImageCache(): ImageCache {
        return ImageCache(maxSize = 50 * 1024 * 1024)
    }
}

// Dagger 生成代码的简化逻辑 (DoubleCheck.java)
class DoubleCheck<T>(
    private var provider: Provider<T>? // 原始的创建逻辑 Provider
) : Provider<T> {
 
    // 使用 volatile 修饰，确保多线程可见性
    @Volatile
    private var instance: Any? = UNINITIALIZED
 
    override fun get(): T {
        // 第一次检查：如果已经初始化，直接返回（无锁，高性能）
        var result = instance
        if (result == UNINITIALIZED) {
            // 未初始化，进入同步块
            synchronized(this) {
                // 第二次检查：防止其他线程已经在等待锁的过程中完成了初始化
                result = instance
                if (result == UNINITIALIZED) {
                    // 真正调用 Provider 创建实例
                    result = provider!!.get()
                    // 缓存实例
                    instance = result
                    // 释放 provider 引用，帮助 GC（因为以后不再需要创建逻辑了）
                    provider = null
                }
            }
        }
        @Suppress("UNCHECKED_CAST")
        return result as T // 返回缓存的单例实例
    }
}

// 使用 @Singleton 标注 Module 中的 @Provides 方法
@Module
@InstallIn(SingletonComponent::class) // 安装到 SingletonComponent
object NetworkModule {
 
    @Provides
    @Singleton // 标注作用域：整个 App 生命周期内只创建一次
    fun provideOkHttpClient(): OkHttpClient {
        // 构建 OkHttpClient，配置超时、拦截器等
        return OkHttpClient.Builder()
            .connectTimeout(30, TimeUnit.SECONDS) // 连接超时 30 秒
            .readTimeout(30, TimeUnit.SECONDS)    // 读取超时 30 秒
            .addInterceptor(HttpLoggingInterceptor()) // 添加日志拦截器
            .build()
    }
 
    @Provides
    @Singleton // 同样是单例，因为 Retrofit 内部依赖 OkHttpClient
    fun provideRetrofit(
        client: OkHttpClient // Hilt 自动注入上面提供的单例 OkHttpClient
    ): Retrofit {
        return Retrofit.Builder()
            .baseUrl("https://api.example.com/") // 设置基础 URL
            .client(client)                       // 使用注入的 OkHttpClient
            .addConverterFactory(GsonConverterFactory.create()) // Gson 转换器
            .build()
    }
}

// 一个 Activity 级别的导航协调器
@ActivityScoped // 绑定到当前 Activity 的生命周期
class NavigationCoordinator @Inject constructor(
    private val activity: Activity // Hilt 自动提供当前 Activity 实例
) {
    // 记录当前导航栈的状态
    private val backStack = mutableListOf<String>()
 
    // 导航到指定页面
    fun navigateTo(destination: String) {
        backStack.add(destination) // 记录到栈中
        // 执行实际的 Fragment 切换或其他导航操作
    }
 
    // 返回上一页
    fun goBack(): Boolean {
        // 如果栈中有记录，弹出最后一个并执行返回
        return if (backStack.isNotEmpty()) {
            backStack.removeLast() // 移除栈顶
            true // 表示成功返回
        } else {
            false // 栈为空，无法返回
        }
    }
}

// Fragment A 和 Fragment B 在同一个 Activity 中
// 它们注入的是同一个 NavigationCoordinator 实例
@AndroidEntryPoint
class FragmentA : Fragment() {
    // 由于 NavigationCoordinator 是 @ActivityScoped
    // 同一个 Activity 下的 FragmentA 和 FragmentB 拿到的是同一个实例
    @Inject lateinit var navCoordinator: NavigationCoordinator
 
    fun onButtonClick() {
        navCoordinator.navigateTo("detail_page") // 使用共享的协调器导航
    }
}
 
@AndroidEntryPoint
class FragmentB : Fragment() {
    @Inject lateinit var navCoordinator: NavigationCoordinator // 同一个实例
 
    fun onBackPressed() {
        navCoordinator.goBack() // 共享同一份导航栈状态
    }
}

// Fragment 级别的表单验证器
@FragmentScoped // 每个 Fragment 实例持有自己独立的验证器
class FormValidator @Inject constructor() {
 
    // 存储各字段的验证错误信息
    private val errors = mutableMapOf<String, String>()
 
    // 验证指定字段
    fun validateField(fieldName: String, value: String): Boolean {
        // 根据字段名应用不同的验证规则
        return when (fieldName) {
            "email" -> {
                // 验证邮箱格式
                val isValid = android.util.Patterns.EMAIL_ADDRESS.matcher(value).matches()
                if (!isValid) errors[fieldName] = "邮箱格式不正确" // 记录错误
                else errors.remove(fieldName) // 清除之前的错误
                isValid
            }
            "password" -> {
                // 验证密码长度
                val isValid = value.length >= 8
                if (!isValid) errors[fieldName] = "密码至少 8 位" // 记录错误
                else errors.remove(fieldName) // 清除错误
                isValid
            }
            else -> true // 未知字段默认通过
        }
    }
 
    // 获取所有验证错误
    fun getAllErrors(): Map<String, String> = errors.toMap() // 返回不可变副本
 
    // 检查是否所有字段都通过验证
    fun isFormValid(): Boolean = errors.isEmpty() // 无错误则有效
}

@AndroidEntryPoint
class RegistrationFragment : Fragment() {
 
    // 每个 RegistrationFragment 实例都有自己独立的 FormValidator
    // 如果 ViewPager 中有两个 RegistrationFragment，它们的 validator 互不影响
    @Inject lateinit var formValidator: FormValidator
 
    private fun onSubmitClick() {
        // 使用该 Fragment 专属的验证器
        formValidator.validateField("email", emailInput.text.toString())
        formValidator.validateField("password", passwordInput.text.toString())
 
        if (formValidator.isFormValid()) {
            // 所有验证通过，提交表单
            submitRegistration()
        } else {
            // 显示错误信息
            showErrors(formValidator.getAllErrors())
        }
    }
}

// 一个用于获取用户资料的 UseCase
@ViewModelScoped // 绑定到使用它的 ViewModel 的生命周期
class GetUserProfileUseCase @Inject constructor(
    private val userRepository: UserRepository, // 注入 Repository（可能是 @Singleton 的）
    private val analyticsTracker: AnalyticsTracker // 注入分析追踪器
) {
    // 内存缓存：在 ViewModel 存活期间（包括配置变更后）保持有效
    private var cachedProfile: UserProfile? = null
 
    // 执行获取用户资料的逻辑
    suspend fun execute(userId: String, forceRefresh: Boolean = false): Result<UserProfile> {
        // 如果有缓存且不强制刷新，直接返回缓存
        if (!forceRefresh && cachedProfile != null) {
            return Result.success(cachedProfile!!) // 返回缓存的资料
        }
 
        // 从 Repository 获取最新数据
        return userRepository.getUserProfile(userId)
            .onSuccess { profile ->
                cachedProfile = profile // 更新缓存
                analyticsTracker.trackProfileLoaded(userId) // 记录分析事件
            }
        // 当 ViewModel 被 clear 时，此 UseCase 也被回收
        // cachedProfile 自然被 GC，无需手动清理
    }
}

// ViewModel 中注入 @ViewModelScoped 的 UseCase
@HiltViewModel // 标注为 Hilt 管理的 ViewModel
class ProfileViewModel @Inject constructor(
    private val getUserProfile: GetUserProfileUseCase, // 注入 UseCase
    private val savedStateHandle: SavedStateHandle     // Hilt 自动提供 SavedStateHandle
) : ViewModel() {
 
    // UI 状态 Flow
    private val _uiState = MutableStateFlow<ProfileUiState>(ProfileUiState.Loading)
    val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow() // 暴露不可变版本
 
    init {
        // ViewModel 创建时自动加载
        loadProfile()
    }
 
    fun loadProfile(forceRefresh: Boolean = false) {
        viewModelScope.launch { // 在 ViewModel 的协程作用域中执行
            _uiState.value = ProfileUiState.Loading // 切换到加载状态
 
            // 从 SavedStateHandle 获取 userId（由导航参数传入）
            val userId = savedStateHandle.get<String>("userId") ?: return@launch
 
            // 执行 UseCase（如果旋转后再次调用，UseCase 的缓存仍在）
            getUserProfile.execute(userId, forceRefresh)
                .onSuccess { profile ->
                    _uiState.value = ProfileUiState.Success(profile) // 成功状态
                }
                .onFailure { error ->
                    _uiState.value = ProfileUiState.Error(error.message) // 错误状态
                }
        }
    }
}

// ❌ 错误：@Singleton 只能用于 SingletonComponent
@Module
@InstallIn(ActivityComponent::class) // 安装到 ActivityComponent
object WrongModule {
    @Provides
    @Singleton // 编译错误！Scope 与 Component 不匹配
    fun provideSomething(): Something = Something()
}
 
// ✅ 正确：@ActivityScoped 对应 ActivityComponent
@Module
@InstallIn(ActivityComponent::class) // 安装到 ActivityComponent
object CorrectModule {
    @Provides
    @ActivityScoped // 正确！Scope 与 Component 匹配
    fun provideSomething(): Something = Something()
}

@Module
@InstallIn(SingletonComponent::class)
object AppModule {
    @Provides
    @ActivityScoped
    fun provideAnalytics(): AnalyticsService = AnalyticsServiceImpl()
}

// --- 1. 定义接口 ---
// 用户仓库的抽象契约，ViewModel 只依赖此接口
interface UserRepository {
    // 挂起函数，按 ID 获取用户
    suspend fun getUser(id: String): User
}
 
// --- 2. 实现类 ---
// 通过 @Inject 标记构造器，让 Hilt 知道如何创建此类
class UserRepositoryImpl @Inject constructor(
    // Hilt 会自动提供 UserApi 和 UserDao（前提是它们也已绑定到图中）
    private val api: UserApi,
    private val dao: UserDao
) : UserRepository {
    // 实现接口方法：先查本地缓存，无则请求网络
    override suspend fun getUser(id: String): User {
        // 先从 Room 数据库查询
        return dao.findById(id) ?: api.fetchUser(id).also {
            // 网络数据回写本地
            dao.insert(it)
        }
    }
}
 
// --- 3. Module 中使用 @Binds ---
@Module
// 安装到 SingletonComponent，全局可用
@InstallIn(SingletonComponent::class)
// 包含 @Binds 的 Module 必须声明为 abstract
abstract class RepositoryModule {
 
    // 告诉 Hilt：当有人需要 UserRepository 接口时，
    // 去找 UserRepositoryImpl 的绑定（即通过其 @Inject 构造器创建）
    @Binds
    abstract fun bindUserRepository(
        // 参数：具体实现类（必须已可被 Hilt 构造）
        impl: UserRepositoryImpl
    ): UserRepository  // 返回值：暴露给依赖图的抽象类型
}

@Module
// 安装到 SingletonComponent —— 网络客户端通常全局单例
@InstallIn(SingletonComponent::class)
object NetworkModule {
 
    // --- 提供 OkHttpClient ---
    @Provides
    // @Singleton 确保整个 App 进程中只创建一个 OkHttpClient
    @Singleton
    fun provideOkHttpClient(
        // 参数由 Hilt 自动从图中获取（需要有对应绑定）
        interceptor: AuthInterceptor
    ): OkHttpClient {
        // 使用 Builder 模式构建 —— 这正是 @Binds 无法表达的场景
        return OkHttpClient.Builder()
            // 添加认证拦截器
            .addInterceptor(interceptor)
            // 设置 30 秒连接超时
            .connectTimeout(30, TimeUnit.SECONDS)
            // 设置 30 秒读取超时
            .readTimeout(30, TimeUnit.SECONDS)
            // 构建最终实例
            .build()
    }
 
    // --- 提供 Retrofit ---
    @Provides
    @Singleton
    fun provideRetrofit(
        // 上面刚提供的 OkHttpClient 会被自动注入到这里
        client: OkHttpClient
    ): Retrofit {
        return Retrofit.Builder()
            // 设置 API 基础地址
            .baseUrl("https://api.example.com/v1/")
            // 使用上面构建的 OkHttpClient
            .client(client)
            // 添加 Kotlin Serialization 或 Gson 转换器
            .addConverterFactory(Json.asConverterFactory("application/json".toMediaType()))
            // 构建 Retrofit 实例
            .build()
    }
 
    // --- 提供具体的 API Service 接口 ---
    @Provides
    @Singleton
    fun provideUserApi(
        // 注入上面创建的 Retrofit 实例
        retrofit: Retrofit
    ): UserApi {
        // 通过 Retrofit 的动态代理机制创建接口实现
        return retrofit.create(UserApi::class.java)
    }
}

@Module
@InstallIn(SingletonComponent::class)
// abstract class 以容纳 @Binds 抽象方法
abstract class DataModule {
 
    // --- @Binds：接口绑定 ---
    @Binds
    // 将 OfflineFirstUserRepository 绑定为 UserRepository
    abstract fun bindUserRepo(
        impl: OfflineFirstUserRepository
    ): UserRepository
 
    companion object {
        // --- @Provides：需要 Builder 构建的第三方库 ---
        @Provides
        @Singleton
        fun provideDatabase(
            // @ApplicationContext 由 Hilt 内置提供
            @ApplicationContext context: Context
        ): AppDatabase {
            // Room 必须用 Builder 创建，不可能用 @Binds
            return Room.databaseBuilder(
                context,
                AppDatabase::class.java,
                // 数据库文件名
                "app_database"
            )
                // 版本升级时的破坏性迁移策略（仅示例，生产慎用）
                .fallbackToDestructiveMigration()
                // 构建数据库实例
                .build()
        }
 
        @Provides
        fun provideUserDao(
            // 参数：上面提供的 AppDatabase 实例
            db: AppDatabase
        ): UserDao {
            // 从 Database 获取 DAO —— 又一个只能用 @Provides 的典型场景
            return db.userDao()
        }
    }
}

// 定义限定符：标识用于 API 请求的 OkHttpClient
@Qualifier
// @Retention(BINARY) 表示注解保留到编译产物中（class 文件），
// 但运行时不可通过反射获取 —— Dagger 只需编译期可见
@Retention(AnnotationRetention.BINARY)
annotation class ApiClient   // 仅是一个标签，无需任何属性
 
// 定义限定符：标识用于图片加载的 OkHttpClient
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class ImageClient

@Module
@InstallIn(SingletonComponent::class)
object HttpClientModule {
 
    // --- 提供 API 专用客户端 ---
    @ApiClient               // ← 限定符标签
    @Provides
    @Singleton
    fun provideApiClient(
        // AuthInterceptor 由 Hilt 图中其他绑定提供
        authInterceptor: AuthInterceptor
    ): OkHttpClient {
        return OkHttpClient.Builder()
            // API 客户端需要认证拦截器
            .addInterceptor(authInterceptor)
            // 30 秒超时
            .connectTimeout(30, TimeUnit.SECONDS)
            .build()
    }
 
    // --- 提供图片加载专用客户端 ---
    @ImageClient             // ← 另一个限定符标签
    @Provides
    @Singleton
    fun provideImageClient(
        // CacheInterceptor 为自定义拦截器
        cacheInterceptor: CacheInterceptor
    ): OkHttpClient {
        return OkHttpClient.Builder()
            // 图片客户端需要缓存拦截器
            .addInterceptor(cacheInterceptor)
            // 图片下载允许更长超时
            .connectTimeout(60, TimeUnit.SECONDS)
            .build()
    }
}

// Retrofit 构建时需要 API 客户端
class ApiService @Inject constructor(
    @ApiClient              // ← 告诉 Hilt：我要的是带 @ApiClient 标签的那个 OkHttpClient
    private val client: OkHttpClient
)
 
// 图片加载器需要图片客户端
class ImageLoader @Inject constructor(
    @ImageClient            // ← 告诉 Hilt：我要的是带 @ImageClient 标签的那个 OkHttpClient
    private val client: OkHttpClient
)

BindingKey = (Type, Optional<Qualifier>)

// javax.inject 包中的源码（简化）
@Qualifier                    // 本身就是一个 Qualifier
@Documented
@Retention(RUNTIME)
public @interface Named {
    String value() default "";  // 用字符串作为区分标签
}

@Module
@InstallIn(SingletonComponent::class)
object ConfigModule {
 
    // 提供 API 基础地址
    @Named("baseUrl")       // ← 用字符串 "baseUrl" 做标签
    @Provides
    fun provideBaseUrl(): String {
        // 返回 API 地址字符串
        return "https://api.example.com/v1/"
    }
 
    // 提供 API Key
    @Named("apiKey")        // ← 用字符串 "apiKey" 做标签
    @Provides
    fun provideApiKey(): String {
        // 返回密钥字符串（实际应从 BuildConfig 或安全存储读取）
        return BuildConfig.API_KEY
    }
}
 
// 注入点使用相同的 @Named 字符串
class ApiClient @Inject constructor(
    @Named("baseUrl")       // ← 精确匹配 "baseUrl" 绑定
    private val baseUrl: String,
    @Named("apiKey")        // ← 精确匹配 "apiKey" 绑定
    private val apiKey: String
)

// ========== 1. Qualifier 定义 ==========
 
// 标识远程数据源
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class RemoteDataSource
 
// 标识本地数据源
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class LocalDataSource
 
 
// ========== 2. 数据源接口与实现 ==========
 
// 统一的数据源抽象
interface UserDataSource {
    suspend fun getUser(id: String): User?
    suspend fun saveUser(user: User)
}
 
// 远程数据源实现：从网络 API 获取数据
class RemoteUserDataSource @Inject constructor(
    // 注入 Retrofit 生成的 API 接口
    private val api: UserApi
) : UserDataSource {
    override suspend fun getUser(id: String): User? {
        // 调用网络接口
        return api.fetchUser(id)
    }
    override suspend fun saveUser(user: User) {
        // 上传到服务器
        api.updateUser(user)
    }
}
 
// 本地数据源实现：从 Room 数据库读写
class LocalUserDataSource @Inject constructor(
    // 注入 Room DAO
    private val dao: UserDao
) : UserDataSource {
    override suspend fun getUser(id: String): User? {
        // 查询本地数据库
        return dao.findById(id)
    }
    override suspend fun saveUser(user: User) {
        // 写入本地数据库
        dao.insertOrUpdate(user)
    }
}
 
 
// ========== 3. Repository 接口与实现 ==========
 
interface UserRepository {
    suspend fun getUser(id: String): User
}
 
// 离线优先策略的 Repository 实现
class OfflineFirstUserRepository @Inject constructor(
    @RemoteDataSource           // ← Qualifier 指定远程数据源
    private val remote: UserDataSource,
    @LocalDataSource            // ← Qualifier 指定本地数据源
    private val local: UserDataSource
) : UserRepository {
    override suspend fun getUser(id: String): User {
        // 优先查本地
        local.getUser(id)?.let { return it }
        // 本地无数据，查远程
        val user = remote.getUser(id)
            // 远程也没有，抛出异常
            ?: throw UserNotFoundException(id)
        // 回写本地缓存
        local.saveUser(user)
        // 返回用户数据
        return user
    }
}
 
 
// ========== 4. Hilt Module —— 完整绑定配置 ==========
 
@Module
@InstallIn(SingletonComponent::class)
abstract class UserDataModule {
 
    // --- @Binds + @Qualifier：绑定远程数据源 ---
    @RemoteDataSource                    // ← 给这条绑定打上"远程"标签
    @Binds
    abstract fun bindRemoteDataSource(
        impl: RemoteUserDataSource       // ← 具体实现
    ): UserDataSource                    // ← 暴露为接口
 
    // --- @Binds + @Qualifier：绑定本地数据源 ---
    @LocalDataSource                     // ← 给这条绑定打上"本地"标签
    @Binds
    abstract fun bindLocalDataSource(
        impl: LocalUserDataSource        // ← 具体实现
    ): UserDataSource                    // ← 同样暴露为接口
 
    // --- @Binds：绑定 Repository（无需 Qualifier，类型唯一） ---
    @Binds
    abstract fun bindUserRepository(
        impl: OfflineFirstUserRepository
    ): UserRepository
 
    companion object {
        // --- @Provides：Room 需要 Builder 创建 ---
        @Provides
        @Singleton
        fun provideDatabase(
            @ApplicationContext context: Context
        ): AppDatabase {
            return Room.databaseBuilder(
                context,
                AppDatabase::class.java,
                "user_database"
            ).build()
        }
 
        // --- @Provides：DAO 从 Database 获取 ---
        @Provides
        fun provideUserDao(db: AppDatabase): UserDao {
            return db.userDao()
        }
    }
}

// 统一常量定义
object NamedKeys {
    // API 基础地址的 Named Key
    const val BASE_URL = "base_url"
    // API 密钥的 Named Key
    const val API_KEY = "api_key"
}
 
// 使用时引用常量
@Named(NamedKeys.BASE_URL)
@Provides
fun provideBaseUrl(): String = "https://..."

// @HiltAndroidApp 是 Hilt 的"总开关"
// 它会触发代码生成，创建 SingletonComponent 并完成 Application 级别的依赖注入
@HiltAndroidApp
class MyApplication : Application() {
 
    // 字段注入：Hilt 会在 super.onCreate() 过程中为此字段赋值
    // 注意：字段不能是 private 的，否则 Hilt 无法通过生成代码访问它
    @Inject
    lateinit var analyticsService: AnalyticsService
 
    override fun onCreate() {
        // 必须先调用 super.onCreate()
        // 因为 Hilt 的注入逻辑正是在 super.onCreate() 中执行的
        super.onCreate()
 
        // 此处 analyticsService 已经被注入，可以安全使用
        analyticsService.trackAppLaunch()
    }
}

// @AndroidEntryPoint 标注后，Hilt 会为此 Activity 生成注入代码
// 它会创建一个与此 Activity 实例绑定的 ActivityComponent
@AndroidEntryPoint
class HomeActivity : AppCompatActivity() {
 
    // 字段注入：不能是 private，lateinit 表示稍后由 Hilt 赋值
    @Inject
    lateinit var userRepository: UserRepository
 
    // 可以注入多个依赖
    @Inject
    lateinit var navigator: AppNavigator
 
    override fun onCreate(savedInstanceState: Bundle?) {
        // 关键：必须先调用 super.onCreate()
        // Hilt 的注入逻辑在 super.onCreate() 的调用链中执行
        super.onCreate(savedInstanceState)
 
        // 此处所有 @Inject 字段已就绪
        setContentView(R.layout.activity_home)
 
        // 安全使用注入的依赖
        val user = userRepository.getCurrentUser()
        navigator.setupBottomNavigation(this)
    }
}

@AndroidEntryPoint
class DetailActivity : AppCompatActivity() {
 
    // Hilt 自动绑定：当前 Activity 的 Application 实例
    @Inject
    lateinit var application: Application
 
    // Hilt 自动绑定：当前 Activity 实例（类型为 Activity）
    // 注意：这里拿到的是 android.app.Activity 类型
    @Inject
    lateinit var activity: Activity
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        // application 和 activity 都已就绪
        // 等价于 this 和 getApplication()，但通过 DI 获取让代码更可测试
        val appName = application.packageName
    }
}

// Fragment 也使用 @AndroidEntryPoint 注解（与 Activity 相同的注解）
@AndroidEntryPoint
class ProfileFragment : Fragment(R.layout.fragment_profile) {
 
    // 字段注入
    @Inject
    lateinit var profileFormatter: ProfileFormatter
 
    // 注意：ViewModel 不是通过 @Inject 字段注入的
    // 而是通过 by viewModels() 委托（Hilt 会自动参与 ViewModel 的创建）
    private val viewModel: ProfileViewModel by viewModels()
 
    // Fragment 的注入发生在 onAttach() 时
    // 因此在 onCreateView() 及之后的生命周期中，依赖都已就绪
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // profileFormatter 已注入，可安全使用
        val displayName = profileFormatter.format(viewModel.userProfile.value)
        view.findViewById<TextView>(R.id.nameText).text = displayName
    }
}

// 同样使用 @AndroidEntryPoint 注解
@AndroidEntryPoint
class SyncService : Service() {
 
    // 字段注入
    @Inject
    lateinit var syncManager: SyncManager
 
    // 注入应用级别的依赖也没问题，因为 ServiceComponent 是 SingletonComponent 的子组件
    @Inject
    lateinit var database: AppDatabase
 
    override fun onCreate() {
        // 与 Activity 相同，Hilt 注入在 super.onCreate() 中执行
        super.onCreate()
        // syncManager 和 database 已就绪
        syncManager.initialize()
    }
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 安全使用注入的依赖
        syncManager.performSync(database)
        return START_STICKY
    }
 
    override fun onBind(intent: Intent?): IBinder? {
        // 如果是 Bound Service，这里也可以安全使用依赖
        return null
    }
}

// BroadcastReceiver 同样使用 @AndroidEntryPoint 注解
@AndroidEntryPoint
class BootCompletedReceiver : BroadcastReceiver() {
 
    // 字段注入
    @Inject
    lateinit var alarmScheduler: AlarmScheduler
 
    @Inject
    lateinit var logger: AppLogger
 
    // 注入发生在 onReceive() 被调用时（内部在 super.onReceive() 之前完成）
    override fun onReceive(context: Context, intent: Intent) {
        // 此处 alarmScheduler 和 logger 已就绪
        if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
            logger.log("Device booted, rescheduling alarms")
            // 重新设置闹钟
            alarmScheduler.rescheduleAll()
        }
    }
}

<!-- AndroidManifest.xml 中静态注册 -->
<!-- Hilt 的字节码转换会确保注入逻辑被正确织入 -->
<receiver
    android:name=".BootCompletedReceiver"
    android:exported="true">
    <intent-filter>
        <!-- 监听系统启动完成广播 -->
        <action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>
</receiver>

// 动态注册示例
// 在 Activity 或其他有 Context 的地方注册
val receiver = BootCompletedReceiver() // 此时 @Inject 字段尚未赋值
val filter = IntentFilter(Intent.ACTION_BOOT_COMPLETED)
// 注册到系统
registerReceiver(receiver, filter)
// 当广播到达时，onReceive() 内部 Hilt 会先完成注入，再执行业务逻辑

// ❌ 错误：宿主 Activity 缺少 @AndroidEntryPoint
class PlainActivity : AppCompatActivity() {
    // 这个 Activity 没有 Hilt 注入
}
 
// Fragment 使用了 @AndroidEntryPoint
@AndroidEntryPoint
class MyFragment : Fragment() {
    @Inject
    lateinit var repo: SomeRepository
    // 运行时崩溃：IllegalStateException
    // "Hilt Fragments must be attached to an @AndroidEntryPoint Activity"
}

// ✅ 正确：宿主 Activity 也需要标注
@AndroidEntryPoint
class CorrectActivity : AppCompatActivity() {
    // 现在 MyFragment 可以正常使用了
}

@AndroidEntryPoint
class BadActivity : AppCompatActivity() {
    
    @Inject
    lateinit var repo: UserRepository
 
    // ❌ 错误：init 块在构造器中执行，此时 Hilt 尚未注入
    init {
        // 这里 repo 未初始化，会抛出 UninitializedPropertyAccessException
        // repo.doSomething()
    }
 
    // ❌ 错误：属性初始化也是在构造器中执行
    // val userName = repo.getCurrentUser().name // 崩溃！
 
    override fun onCreate(savedInstanceState: Bundle?) {
        // ❌ 错误：在 super.onCreate() 之前访问
        // repo.doSomething() // 崩溃！
 
        super.onCreate(savedInstanceState) // ✅ Hilt 在这里注入
 
        // ✅ 正确：在 super.onCreate() 之后访问
        repo.doSomething()
    }
}

@AndroidEntryPoint
class MyActivity : AppCompatActivity() {
    // ❌ 编译错误：Hilt 无法访问 private 字段
    // @Inject
    // private lateinit var repo: UserRepository
 
    // ✅ 正确：使用默认可见性（或 internal / protected）
    @Inject
    lateinit var repo: UserRepository
}

// ✅ 推荐：业务依赖放在 ViewModel 中（构造器注入，更优雅）
@HiltViewModel
class HomeViewModel @Inject constructor(
    // 构造器注入：干净、可测试、不需要 lateinit
    private val userRepository: UserRepository,
    private val analyticsTracker: AnalyticsTracker,
    // SavedStateHandle 由 Hilt 自动提供
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // ViewModel 中封装业务逻辑
    fun loadUser() = userRepository.getCurrentUser()
}
 
// Activity 只负责 UI 绑定
@AndroidEntryPoint
class HomeActivity : AppCompatActivity() {
 
    // 通过委托获取 ViewModel（Hilt 自动参与创建）
    private val viewModel: HomeViewModel by viewModels()
 
    // 只在 Activity 中注入与 UI 直接相关的依赖
    @Inject
    lateinit var imageLoader: ImageLoader
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_home)
 
        // 通过 ViewModel 访问业务数据
        viewModel.loadUser().observe(this) { user ->
            imageLoader.load(user.avatarUrl)
        }
    }
}

// 使用 @AssistedInject 标注构造器，表示这个类需要辅助注入
class PaymentProcessor @AssistedInject constructor(
    // 由 Hilt 容器自动提供的依赖，无需任何额外标注
    private val gateway: PaymentGateway,
    // 由 Hilt 容器自动提供的依赖
    private val analytics: AnalyticsTracker,
    // @Assisted 标注的参数：运行时由调用方传入
    @Assisted private val orderId: String,
    // @Assisted 标注的参数：运行时由调用方传入
    @Assisted private val amount: Double
) {
    // 使用所有依赖执行业务逻辑
    suspend fun process(): PaymentResult {
        // gateway 和 analytics 来自容器，orderId 和 amount 来自调用方
        analytics.trackPaymentStart(orderId)
        return gateway.charge(orderId, amount)
    }
}

class MessageSender @AssistedInject constructor(
    // 容器提供的依赖
    private val networkClient: NetworkClient,
    // 两个都是 String 类型的辅助参数，必须用标识符区分
    @Assisted("senderId") private val senderId: String,
    // 不同的标识符避免歧义
    @Assisted("receiverId") private val receiverId: String
) {
    // senderId 和 receiverId 在运行时由调用方分别指定
    fun send(content: String) {
        networkClient.post(from = senderId, to = receiverId, body = content)
    }
}

// @AssistedFactory 标注一个接口，Dagger 会自动生成它的实现
@AssistedFactory
interface PaymentProcessorFactory {
    // 方法的返回类型必须是 @AssistedInject 标注的类
    // 方法参数必须与目标类中所有 @Assisted 参数一一对应（类型 + 标识符）
    fun create(orderId: String, amount: Double): PaymentProcessor
}

// MessageSender 的辅助工厂
@AssistedFactory
interface MessageSenderFactory {
    // 参数的 @Assisted 标识符必须与目标类构造器中的标识符匹配
    fun create(
        @Assisted("senderId") senderId: String,
        @Assisted("receiverId") receiverId: String
    ): MessageSender
}

// Dagger 自动生成的工厂实现（简化版，实际生成代码更完整）
public final class PaymentProcessorFactory_Impl implements PaymentProcessorFactory {
 
    // 容器管理的依赖以 Provider 形式持有，支持延迟获取
    private final Provider<PaymentGateway> gatewayProvider;
    private final Provider<AnalyticsTracker> analyticsProvider;
 
    // 构造器接收容器依赖的 Provider
    public PaymentProcessorFactory_Impl(
            Provider<PaymentGateway> gatewayProvider,
            Provider<AnalyticsTracker> analyticsProvider) {
        this.gatewayProvider = gatewayProvider;
        this.analyticsProvider = analyticsProvider;
    }
 
    // create() 方法：合并容器依赖 + 运行时参数，构造目标实例
    @Override
    public PaymentProcessor create(String orderId, double amount) {
        // 从 Provider 中获取容器管理的实例
        // 与调用方传入的 orderId、amount 一起传入构造器
        return new PaymentProcessor(
                gatewayProvider.get(),
                analyticsProvider.get(),
                orderId,
                amount
        );
    }
}

// 在 ViewModel 中使用 Factory 创建辅助注入的对象
@HiltViewModel
class CheckoutViewModel @Inject constructor(
    // Hilt 自动提供 Factory 的生成实现，无需手动绑定
    private val processorFactory: PaymentProcessorFactory
) : ViewModel() {
 
    // 在运行时，用户选择订单后才知道 orderId 和 amount
    fun processPayment(orderId: String, amount: Double) {
        // 通过 Factory 传入运行时参数，创建 PaymentProcessor 实例
        val processor = processorFactory.create(orderId, amount)
        viewModelScope.launch {
            val result = processor.process()
            // 处理支付结果...
        }
    }
}

// build.gradle.kts (Module level)
dependencies {
    // Hilt Worker 扩展库，提供 @HiltWorker 注解和 HiltWorkerFactory
    implementation("androidx.hilt:hilt-work:1.2.0")
    // KSP 注解处理器，用于生成辅助注入代码
    ksp("androidx.hilt:hilt-compiler:1.2.0")
}

// @HiltWorker 是 Hilt 专门为 Worker 提供的注解
// 它本质上是 @AssistedInject 的语法糖，内部会触发辅助注入的代码生成
@HiltWorker
class SyncWorker @AssistedInject constructor(
    // Context 是 Worker 的必需参数，由 WorkManager 在运行时传入
    // 必须标注 @Assisted
    @Assisted appContext: Context,
    // WorkerParameters 也是 Worker 的必需参数，同样由 WorkManager 传入
    @Assisted workerParams: WorkerParameters,
    // 以下是由 Hilt 容器自动提供的业务依赖
    private val syncRepository: SyncRepository,
    private val notificationHelper: NotificationHelper
) : CoroutineWorker(appContext, workerParams) {
 
    override suspend fun doWork(): Result {
        return try {
            // 使用容器注入的 syncRepository 执行同步操作
            syncRepository.performFullSync()
            // 使用容器注入的 notificationHelper 发送通知
            notificationHelper.showSyncComplete()
            // 返回成功结果
            Result.success()
        } catch (e: Exception) {
            // 如果可以重试则返回 retry，否则返回 failure
            if (runAttemptCount < 3) Result.retry() else Result.failure()
        }
    }
}

// 在 Application 类中配置 WorkManager
@HiltAndroidApp
class MyApplication : Application(), Configuration.Provider {
 
    // Hilt 自动注入 HiltWorkerFactory
    // 这个 Factory 内部维护了所有 @HiltWorker 类的 AssistedFactory 映射
    @Inject
    lateinit var workerFactory: HiltWorkerFactory
 
    // 实现 Configuration.Provider 接口，提供自定义的 WorkManager 配置
    override val workManagerConfiguration: Configuration
        get() = Configuration.Builder()
            // 将 HiltWorkerFactory 设置为 WorkManager 的 WorkerFactory
            // 这样 WorkManager 在创建 Worker 时会委托给 Hilt 进行辅助注入
            .setWorkerFactory(workerFactory)
            .build()
}

<!-- 移除 WorkManager 的默认 ContentProvider 初始化器 -->
<!-- 因为我们要手动初始化以注入 HiltWorkerFactory -->
<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data
        android:name="androidx.work.WorkManagerInitializer"
        android:value="androidx.startup"
        tools:node="remove" />
</provider>

@HiltWorker
class UploadWorker @AssistedInject constructor(
    // 固定的两个辅助参数：Context 和 WorkerParameters
    @Assisted appContext: Context,
    @Assisted workerParams: WorkerParameters,
    // 容器提供的依赖
    private val uploadService: UploadService,
    private val fileManager: FileManager
) : CoroutineWorker(appContext, workerParams) {
 
    override suspend fun doWork(): Result {
        // 额外的运行时数据从 inputData 中获取，而非 @Assisted 参数
        val filePath = inputData.getString("file_path")
            ?: return Result.failure()
        val uploadUrl = inputData.getString("upload_url")
            ?: return Result.failure()
 
        // 使用容器注入的依赖 + inputData 中的运行时数据执行上传
        val file = fileManager.getFile(filePath)
        return if (uploadService.upload(uploadUrl, file)) {
            Result.success()
        } else {
            Result.retry()
        }
    }
 
    companion object {
        // 提供便捷方法构建 WorkRequest，封装 inputData 的 key
        fun buildRequest(filePath: String, uploadUrl: String): OneTimeWorkRequest {
            // 将运行时参数打包到 inputData 中
            val data = workDataOf(
                "file_path" to filePath,
                "upload_url" to uploadUrl
            )
            return OneTimeWorkRequestBuilder<UploadWorker>()
                .setInputData(data)
                .build()
        }
    }
}