第4章 定义Protobuf消息结构：字段类型选择、嵌套消息、枚举与默认值、向后兼容规则

DataStore 借助 Protocol Buffers（Protobuf）实现强类型存储。消息结构的定义质量直接决定存储的扩展性、磁盘占用与跨版本兼容能力。本章围绕 .proto 文件的字段类型选择、嵌套消息、枚举声明、默认值机制以及向后兼容规则展开，给出可直接用于生产项目的具体方案。

4.1 字段类型选择：标量类型与 DataStore 映射

Protobuf 提供一组标量类型，每种类型对应固定的 wire type 和编码字节数。选择合适的类型能大幅降低磁盘 I/O 与反序列化开销。

4.2 嵌套消息：结构化与扁平化的权衡

嵌套消息允许在一条顶层消息内部定义子消息类型，适合表达“拥有-包含”关系。但过度嵌套会增加序列化层次和解析深度。

// 推荐：两层嵌套，清晰且易于扩展
message UserPreferences {
  message ThemeConfig {
    string primary_color = 1;       // 主题色 hex
    bool use_dark_mode = 2;         // 暗黑模式开关
    float font_scale = 3;          // 字体缩放比 0.8~1.2
  }

  message NotificationSettings {
    bool push_enabled = 1;
    bool email_digest = 2;
    uint32 quiet_hours_start = 3;   // 免打扰开始小时 (0-23)
    uint32 quiet_hours_end = 4;     // 免打扰结束小时 (0-23)
  }

  string user_id = 1;
  ThemeConfig theme = 2;
  NotificationSettings notifications = 3;
  uint64 last_updated_epoch_ms = 4;
}

嵌套消息在 DataStore 中的序列化结果为连续的 length-delimited 字段，父消息与子消息共享同一个字节流。反序列化时，框架会递归解析嵌套结构。

4.3 枚举与默认值：零值语义与显式声明

Protobuf 枚举的第一个值必须为 0，该值同时也是字段的默认值。这一设计对 DataStore 的“缺失字段”行为有直接影响。

// 第 0 值必须保留给 "未指定/未知" 状态
enum ConnectionStatus {
  CONNECTION_UNSPECIFIED = 0;   // 默认值，DataStore 未写入时返回此值
  CONNECTION_WIFI = 1;
  CONNECTION_CELLULAR = 2;
  CONNECTION_ETHERNET = 3;
  CONNECTION_OFFLINE = 4;
}

message NetworkState {
  ConnectionStatus status = 1;          // 默认值为 CONNECTION_UNSPECIFIED
  string ssid = 2;                      // 默认值为 ""
  int32 signal_strength = 3;            // 默认值为 0
  // 注意：int32 的默认值 0 可能与有效值冲突，请自行区分
}

对于枚举字段，始终将 0 值定义为 XXX_UNSPECIFIED 或 XXX_UNKNOWN，避免将业务有效状态放在 0 位。例如：

// 反模式：0 值被业务占用
enum ThemeMode {
  THEME_LIGHT = 0;    // 既是默认值也是有效值 → 无法区分未设置
  THEME_DARK = 1;
  THEME_SYSTEM = 2;
}

// 正模式：0 值留作占位
enum ThemeMode {
  THEME_MODE_UNSPECIFIED = 0;
  THEME_MODE_LIGHT = 1;
  THEME_MODE_DARK = 2;
  THEME_MODE_SYSTEM = 3;
}

4.4 向后兼容规则：字段编号与 wire type 不变性

DataStore 持久化的 Protobuf 字节流可能会跨越多个 App 版本。向后兼容的核心原则是：已发布的字段编号和 wire type 永远不可更改或删除。

message UserSession {
  reserved 2, 5, 8;             // 已删除的字段编号，不可复用
  reserved "legacy_", "old_device_id";  // 已删除的字段名，不可复用

  string session_id = 1;
  // 字段 2 已删除 — 编译器会阻止使用
  string device_id = 3;
  uint64 created_at = 4;
  // 字段 5 已删除
  string refresh_ = 6;
  uint32 expires_in_seconds = 7;
  // 字段 8 已删除
}

4.5 向后兼容的字段类型迁移表

当业务需求变化需要调整字段类型时，并非所有类型变更都破坏兼容。下表列出可安全转换的类型对：

4.6 本章内联 SVG：Protobuf 消息定义决策流程

下图展示从业务需求到 .proto 消息定义的关键决策路径，涵盖字段类型选择、嵌套层次、枚举默认值设计及兼容性检查点。

4.7 向后兼容实战：字段废弃与 reserved 管理

在 DataStore 长期存储场景中，字段废弃是高频操作。以下展示正确的废弃流程：

// ===== 版本 1 (v1) =====
message AppSettings {
  string locale = 1;
  float brightness = 2;
  bool auto_sync = 3;
}

// ===== 版本 2 (v2)：废弃 brightness，新增 theme_mode =====
message AppSettings {
  reserved 2;                    // brightness 字段编号不再使用
  reserved "brightness";         // 字段名同样 reserved

  string locale = 1;
  bool auto_sync = 3;
  string theme_mode = 4;         // 新增字段，使用编号 4
}

// ===== 版本 3 (v3)：用枚举替代 theme_mode string =====
message AppSettings {
  reserved 2;
  reserved "brightness";

  enum ThemeMode {
    THEME_MODE_UNSPECIFIED = 0;
    THEME_MODE_LIGHT = 1;
    THEME_MODE_DARK = 2;
    THEME_MODE_SYSTEM = 3;
  }

  string locale = 1;
  bool auto_sync = 3;
  ThemeMode theme_mode = 4;      // 类型从 string 改为枚举，wire type 仍为 VARINT，兼容
}

4.8 DataStore 中 Proto 消息的默认值处理策略

DataStore 基于 Protobuf 序列化，读取时所有未设置的字段都会返回默认值。在应用层需要设计明确的默认值处理策略：

• 字段级默认值常量：在 Kotlin 代码中定义常量类，集中管理业务默认值。
• 使用 optional 关键字（Protobuf 3.15+）：显式标记可选字段，配合 hasField() 判断是否被设置。
• 包装类型：使用 google.protobuf.wrappers 中的 StringValue、Int32Value 等，使默认值为 null 而非零值。

// 使用 optional 关键字区分未设置与零值
message UserConfig {
  optional string display_name = 1;       // 未设置时返回 null（在 Kotlin 中为 null）
  optional int32 age = 2;                 // 未设置时返回 null
  string email = 3;                       // 未设置时返回 ""
}

// Kotlin 读取时判断
val config: UserConfig = dataStore.first()
val name: String? = if (config.hasDisplayName()) config.displayName else null
val age: Int? = if (config.hasAge()) config.age else null

4.9 性能与稳定性优化：字段编号分配策略

字段编号不仅影响兼容性，还影响序列化性能。Protobuf 编码时，编号越小，tag 字节开销越少。

// 高效编号分配示例
message HighFrequencyConfig {
  // 1 字节 tag 区域 — 每次读取都会访问的字段
  bool is_first_launch = 1;
  uint32 app_version_code = 2;
  string device_locale = 3;
  float screen_brightness = 4;

  // 2 字节 tag 区域 — 偶尔访问的字段
  uint64 last_sync_timestamp = 16;
  string last_sync_error = 17;
  uint32 background_fetch_interval = 18;

  // 预留扩展区
  reserved 32 to 64;
}

4.10 常见错误与调试

以下为定义 Protobuf 消息结构时的高频问题及其排查方法：

# 使用 protoscope 分析 DataStore 的 .pb 文件
protoscope user_preferences.pb

# 输出示例：
# 1: STRING "user_abc"
# 2: MESSAGE {
#   1: STRING "#1A2B3C"
#   2: VARINT 1
# }
# 3: MESSAGE {
#   1: VARINT 1
#   2: VARINT 0
# }

通过本章的学习，你已经能够设计出兼容性强、序列化高效的 Protobuf 消息结构，为后续 DataStore 的读写操作奠定坚实的类型安全基础。