4. 编写第一个 Initializer：创建自定义 Initializer 类、实现 create() 和 dependencies() 方法

4.1 为什么需要自定义 Initializer

Jetpack App Startup 通过 Initializer 接口将组件初始化逻辑抽象成可组合、可排序的单元。当我们需要在应用启动时自动完成某个库（如日志、数据库、分析 SDK）的初始化，并且依赖其他初始化结果时，就必须编写自己的 Initializer。这一章节将带你从头实现第一个自定义 Initializer，掌握 create() 和 dependencies() 这两个核心方法。

4.2 Initializer 接口原理

Initializer 是泛型接口：

interface Initializer<T> {
    fun create(context: Context): T
    fun dependencies(): List<Class<out Initializer<*>>>
}
  • create(context: Context)：初始化逻辑的入口，返回一个 T 类型的实例。通常在该方法内完成库的配置、线程池创建、数据库打开等耗时操作。App Startup 会在合适的线程（默认主线程，可配置）调用该方法。
  • dependencies()：声明当前 Initializer 依赖的其他 Initializer 的 Class 列表。App Startup 会保证按拓扑顺序执行依赖链，即先执行所有依赖，再执行当前 Initializer。

4.3 实现流程

  1. 创建类：新建一个 Kotlin/Java 类，实现 Initializer<T> 接口，其中 T 是初始化后返回的对象类型（通常为对应库的单例或 Builder）。
  2. 实现 create()：在方法体内写入需要执行的初始化代码，并返回初始化后的对象。注意捕获异常，避免应用崩溃。
  3. 实现 dependencies()：返回依赖的 Initializer 列表。若没有依赖，返回 emptyList() 或 Collections.emptyList()。
  4. 在 AndroidManifest.xml 中注册：为了让 App Startup 自动发现 Initializer，必须在 AndroidManifest.xml 的 <provider> 中声明。
提示：如果使用 App Startup 的自动发现机制，你不需要手动调用 AppInitializer.getInstance(context).initializeComponent()，App Startup 会在 ContentProvider 的 onCreate 中自动完成依赖解析和初始化。

4.4 代码示例：自定义日志初始化器

假设我们有一个 SimpleLogger 库，需要传入日志级别和缓存目录。下面的 Initializer 完成其初始化：

// SimpleLoggerInitializer.kt
class SimpleLoggerInitializer : Initializer<SimpleLogger> {
    override fun create(context: Context): SimpleLogger {
        // 从 SharedPreferences 或 BuildConfig 读取配置
        val logLevel = BuildConfig.DEBUG_LEVEL
        val cacheDir = File(context.cacheDir, "logs")
        return SimpleLogger.Builder()
            .setLevel(logLevel)
            .setLogDir(cacheDir)
            .build()
    }

    override fun dependencies(): List<Class<out Initializer<*>>> {
        // 假设 SimpleLogger 依赖一个磁盘缓存初始化器
        return listOf(DiskCacheInitializer::class.java)
    }
}
<!-- AndroidManifest.xml -->
<application>
    <provider
        android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        android:multiprocess="true"
        tools:node="merge">
        <meta-data
            android:name="com.example.app.SimpleLoggerInitializer"
            android:value="androidx.startup" />
    </provider>
</application>
关键点：android:value 必须设为 "androidx.startup"，这是 App Startup 的默认发现标记。如果使用 tools:node="merge"，可以合并库中的多个 Initializer。

4.5 调试验证

初始化完成后，可以通过以下方式验证 Initializer 是否被执行：

  • 在 create() 中添加日志（如 Log.d("AppStartup", "SimpleLogger initialized")），观察 Logcat。
  • 检查 SimpleLogger.getInstance() 是否返回非 null 实例。
  • 使用 AppInitializer.getInstance(context).isEagerlyInitialized(SimpleLoggerInitializer::class.java) 查询是否已初始化。
注意：create() 默认运行在主线程，如果初始化包含耗时操作（超过 10ms），应放入后台线程或使用 Dispatchers.IO。App Startup 本身不强制异步，开发者需自行处理线程模型。

4.6 常见错误与解决方案

错误场景原因解决方案
Initializer 未执行AndroidManifest 中未正确声明 meta-data，或使用了 tools:node="remove"检查 manifest 合并结果，确保 InitializationProvider 包含相应 meta-data
依赖死循环Initializer A 依赖 B，B 又依赖 A（直接或间接）App Startup 会抛出 StartupException；重新设计初始化顺序或移除循环依赖
Context 为空在 create() 中使用了错误的 context（如 application 与 activity 混淆）始终使用传入的 context，需要 application 时调用 context.applicationContext
多次初始化在代码中手动调用了 initializeComponent()，同时 Manifest 又自动触发避免重复调用；App Startup 内部有防重入机制，但多次调用仍可能产生副作用

4.7 性能与稳定性优化

  • 延迟非关键初始化：将非必须组件的初始化放到 dependencies() 返回空列表，并在 create() 中使用 Dispatchers.Default 异步执行。
  • 避免在 create() 中持有 Activity 引用：应用启动阶段可能尚未与 Activity 绑定。
  • 使用 Provider 初始化时注意线程安全：如果多个 Initializer 并行执行（未来版本可能支持并行），需确保共享资源加锁。
  • 测量初始化耗时：在 create() 前后添加 System.currentTimeMillis() 或使用 TraceCompat，分析启动性能。

4.8 初始化流程与依赖关系示意图

下图展示了自定义 Initializer 的生命周期及其与 App Startup 引擎的交互：

自定义 Initializer 生命周期与依赖解析 应用启动 InitializationProvider.onCreate() 解析依赖图（DAG） create(依赖A) create(依赖B) create(当前Initializer) 初始化完成 dependencies() 定义依赖 create() 返回实例

4.9 小结

本章从接口原理到完整实现，手把手编写了第一个自定义 Initializer。关键在于理解 create() 负责初始化逻辑，dependencies() 声明执行顺序。通过 AndroidManifest 注册后，App Startup 自动完成依赖解析和调用。接下来，你可以在实际项目中为第三方 SDK 编写 Initializer，实现统一、有序的启动初始化。

← 上一章 📖 返回目录 下一章 →