3. Protocol Buffers 详解：定义 proto 文件、消息类型、字段规则、枚举、服务定义

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。在 gRPC 缓存一致性场景中，proto 文件不仅定义了服务契约，还直接决定了缓存键的生成粒度、序列化性能以及版本兼容策略。本章将系统讲解 proto 文件的核心语法要素。

3.1 proto 文件结构与包声明

一个标准的 proto 文件以 syntax 声明开头，随后定义包名、导入依赖、消息类型和服务接口。包名用于避免命名冲突，在 gRPC 中通常映射为 Go 的包路径。

syntax = "proto3";

package cache.v1;

option go_package = "github.com/example/cache/api/v1;cachev1";

// 导入其他 proto 文件
import "google/protobuf/timestamp.proto";
import "common/status.proto";

3.2 消息类型（Message）与字段规则

消息类型是 Protobuf 的核心数据结构，每个字段由 字段规则 + 类型 + 字段名 + 编号 组成。字段编号在二进制编码中起关键作用，一旦发布不应修改。

字段规则对比

message CacheEntry {
  string key = 1;                          // singular（默认）
  optional google.protobuf.Timestamp expire_at = 2; // optional
  bytes value = 3;                         // 二进制负载
  repeated string tags = 4;                // repeated
  map<string, string> metadata = 5;        // map
}

3.3 标量类型与默认值

proto3 中每个标量类型都有明确的默认值。反序列化时，如果字段未设置，则取默认值。这一特性对缓存命中与未命中的判断有直接影响。

3.4 枚举（Enum）

枚举用于定义一组预定义的常量值。在缓存一致性中，枚举常用于表示缓存状态、操作类型或错误码。

enum CacheStatus {
  CACHE_STATUS_UNSPECIFIED = 0;  // 必须存在零值
  CACHE_STATUS_HIT = 1;          // 缓存命中
  CACHE_STATUS_MISS = 2;         // 缓存未命中
  CACHE_STATUS_STALE = 3;        // 缓存过期但可用
  CACHE_STATUS_INVALIDATED = 4;  // 缓存已失效
}

message CacheResponse {
  CacheStatus status = 1;
  bytes data = 2;
}

3.5 服务定义（Service）

服务定义将消息类型组合成 RPC 方法接口。在 gRPC 缓存一致性架构中，服务定义决定了客户端与缓存代理之间的通信模式。

service CacheService {
  // 一元 RPC：获取缓存
  rpc Get(GetRequest) returns (GetResponse);

  // 服务端流式 RPC：批量获取缓存
  rpc BatchGet(BatchGetRequest) returns (stream CacheEntry);

  // 客户端流式 RPC：批量写入缓存
  rpc BatchSet(stream SetRequest) returns (BatchSetResponse);

  // 双向流式 RPC：缓存订阅与失效通知
  rpc Subscribe(stream SubscribeRequest) returns (stream InvalidateEvent);
}

3.6 完整 proto 文件示例：缓存一致性契约

以下是一个面向缓存一致性场景的完整 proto 文件，整合了消息类型、枚举、字段规则和服务定义。

syntax = "proto3";

package cache.v1;

option go_package = "github.com/example/cache/api/v1;cachev1";

import "google/protobuf/timestamp.proto";

// 缓存状态枚举
enum CacheStatus {
  CACHE_STATUS_UNSPECIFIED = 0;
  CACHE_STATUS_HIT = 1;
  CACHE_STATUS_MISS = 2;
  CACHE_STATUS_STALE = 3;
  CACHE_STATUS_INVALIDATED = 4;
}

// 缓存条目
message CacheEntry {
  string key = 1;
  optional google.protobuf.Timestamp expire_at = 2;
  bytes value = 3;
  repeated string tags = 4;
  map<string, string> metadata = 5;
  int64 version = 6;  // 用于乐观锁一致性
}

// 获取请求
message GetRequest {
  string key = 1;
  bool allow_stale = 2;  // 是否允许返回过期数据
}

// 获取响应
message GetResponse {
  CacheStatus status = 1;
  CacheEntry entry = 2;
}

// 失效事件
message InvalidateEvent {
  string key = 1;
  repeated string tags = 2;
  google.protobuf.Timestamp invalidated_at = 3;
}

// 缓存服务定义
service CacheService {
  rpc Get(GetRequest) returns (GetResponse);
  rpc Set(CacheEntry) returns (CacheStatus);
  rpc Delete(GetRequest) returns (CacheStatus);
  rpc Subscribe(stream SubscribeRequest) returns (stream InvalidateEvent);
}

3.7 字段编号与向后兼容

字段编号是 Protobuf 二进制格式的核心标识符。在缓存一致性场景中，proto 文件的演进必须遵循向后兼容规则，否则可能导致缓存反序列化失败。

message CacheEntry {
  reserved 7, 8, 10 to 15;       // 保留已删除的字段编号
  reserved "deprecated_field";    // 保留已删除的字段名

  string key = 1;
  int64 version = 2;              // 高频字段使用小编号
  optional google.protobuf.Timestamp expire_at = 3;
  bytes value = 4;
  repeated string tags = 16;      // 低频字段使用大编号
  map<string, string> metadata = 17;
}

3.8 oneof 字段：缓存条件分支

oneof 允许一组字段中同时最多只有一个被设置。在缓存一致性中，oneof 常用于表示互斥的缓存状态或负载类型。

message CacheValue {
  oneof value_type {
    string string_value = 1;
    int64 int_value = 2;
    double double_value = 3;
    bytes binary_value = 4;
  }
}

message CacheResponse {
  CacheStatus status = 1;
  oneof result {
    CacheValue data = 2;       // 缓存命中时
    string redirect_key = 3;   // 缓存重定向时
    string error_message = 4;  // 缓存错误时
  }
}

使用 oneof 可以显著减少缓存消息中的冗余字段，同时保证反序列化时只有一个分支被激活，避免歧义。

3.9 小结