📚 课程目录第2章环境搭建

2. Proto DataStore 基础配置：protobuf 依赖、Gradle 插件与 Schema 文件路径

2.1 核心原理：为什么 Proto DataStore 需要 protobuf

Proto DataStore 以 Protocol Buffers（protobuf）作为序列化方案。与 Preferences DataStore 不同，它要求开发者预先定义 .proto 文件来描述数据结构，然后通过 protobuf 编译器生成类型安全的 Java/Kotlin 类。运行时 DataStore 直接读写这些生成的类，无需手动进行键值映射或类型转换。

  关键优势：编译时类型校验、自动序列化/反序列化、支持嵌套消息与枚举、向后兼容的字段编号。

整个配置链路包括三个环节：

Gradle 插件（protobuf 插件）—— 注册 proto 编译任务。
protobuf 依赖（Java lite 版本）—— 提供运行时序列化库。
Schema 定义文件（.proto）—— 放置在指定目录，插件自动扫描。

2.2 实现流程：三步完成基础配置

应用 protobuf 插件 —— 在项目级 build.gradle（或 build.gradle.kts）添加插件 classpath。
配置模块级 build.gradle —— 声明 protobuf 插件、protobuf lite 依赖、自定义 schema 目录路径。
创建 .proto schema 文件 —— 在指定目录（默认 src/main/proto/）编写消息定义。

建议：若需要复用 proto 定义，可将 .proto 文件抽取为独立库模块，通过 protoPath 引入。

2.3 具体配置：Gradle 插件与依赖

2.3.1 项目级 build.gradle（引入插件）

// 项目根目录 build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.google.protobuf:protobuf-gradle-plugin:0.9.4"
    }
}

若使用 Kotlin DSL（.kts）：

// build.gradle.kts
plugins {
    id("com.google.protobuf") version "0.9.4" apply false
}

2.3.2 模块级 build.gradle（应用插件 + 配置）

plugins {
    id 'com.android.application'
    id 'com.google.protobuf'                // 应用 protobuf 插件
}

android {
    // ... 常规配置
}

dependencies {
    implementation "androidx.datastore:datastore:1.1.1"
    implementation "com.google.protobuf:protobuf-javalite:3.25.3"
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.25.3"
    }
    generateProtoTasks {
        all().each { task ->
            task.builtins {
                java {
                    option 'lite'
                }
            }
        }
    }
}

关键配置说明：

配置项	含义	常见值
`protoc.artifact`	proto 编译器（protoc）的 Maven 坐标，用于生成 Java 代码	`com.google.protobuf:protoc:3.25.3`
`option 'lite'`	生成轻量版 Java 类（减小 APK 体积）	必须设置 `'lite'` 以匹配 `protobuf-javalite`
`protobuf-javalite`	运行时库，与 lite 模式生成的类兼容	`3.25.3`（与 `protoc` 版本一致）

2.4 Schema 定义文件路径与命名约定

protobuf 插件默认扫描 src/main/proto/ 目录下的所有 .proto 文件。生成的文件位于 build/generated/source/proto/main/java/。若要自定义 proto 目录，可在 protobuf 块中配置：

protobuf {
    // 自定义 proto 源目录
    generateProtoTasks {
        all().each { task ->
            task.builtins {
                java { option 'lite' }
            }
        }
    }
}
// 通过 sourceSets 指定
android {
    sourceSets {
        main {
            proto {
                srcDir 'src/main/proto'         // 默认路径，可改为自定义
            }
        }
    }
}

推荐的文件组织结构（以 “Settings” 主题为例）：

app/
└── src/
    └── main/
        ├── proto/
        │   └── settings.proto
        └── java/...

2.5 proto 文件基本编写示例

syntax = "proto3";                         // 必须使用 proto3

option java_package = "com.example.app.datastore";
option java_multiple_files = true;        // 生成多个顶级类

message UserPreferences {
    string display_name = 1;               // 字段编号不能重复
    int32 theme = 2;                       // 0=light, 1=dark
    bool notifications_enabled = 3;
}

2.6 常见错误与调试

错误现象	根本原因	解决方法
`Could not find method google()`	缺少 Google Maven 仓库	在 `buildscript.repositories` 中添加 `google()`
`protoc version mismatch`	`protoc` 版本与 `protobuf-javalite` 版本不一致	统一为相同版本（如 `3.25.3`）
`No matching variant of protobuf-javalite`	缺少 `option 'lite'` 导致生成的类是完整版	确保 `generateProtoTasks` 中设置 `option 'lite'`
`Proto file not found`	`.proto` 未放在 `src/main/proto/` 或 sourceSets 指定错误	检查目录是否正确，或重新配置 `srcDir`

版本兼容警示：DataStore 1.0+ 要求 protobuf 版本 ≥ 3.14.0，建议使用 3.18+ 以获取最新性能优化。同时避免混用 protobuf-java（非 lite）与 protobuf-javalite，否则会出现 NoClassDefFoundError。

2.7 性能与稳定性优化建议

统一版本号：使用 Gradle 属性或版本目录（libs.versions.toml）管理 protoc 与 protobuf-javalite 版本，避免人工维护遗漏。
精简生成类：仅定义必要的字段，避免过大的消息（建议单条消息 < 100 个字段），否则编译器生成的代码量膨胀。
缓存配置：开启 Gradle 构建缓存（--build-cache），proto 编译任务仅在 .proto 变更时重新执行。
索引文件系统：.proto 文件数量较多时，将 proto 独立为模块，避免 Android Studio 索引卡顿。

2.8 验证配置是否成功

执行 ./gradlew generateDebugProto 查看生成产物：

build/generated/source/proto/main/java/com/example/app/datastore/
└── UserPreferences.java
└── UserPreferencesOrBuilder.java

若文件生成且无编译错误，则基础配置完成。