3. Protocol Buffers详解

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。在实时通信微服务中，消息的紧凑性、解析速度与跨语言兼容性直接决定了系统的吞吐与延迟。本章深入剖析 proto3 的核心语法要素，为后续定义双向流服务奠定基础。

3.1 proto3 语法概览与文件结构

每个 .proto 文件以 syntax = "proto3"; 声明版本，随后定义包名、导入依赖与消息类型。proto3 移除了 proto2 中的 required 和 optional 关键字，所有字段默认为可选，且不再支持 default 自定义默认值。

syntax = "proto3";

package im.realtime.v1;

import "google/protobuf/timestamp.proto";

message ChatMessage {
  string message_id = 1;
  string sender_id = 2;
  string content = 3;
  google.protobuf.Timestamp sent_at = 4;
}

3.2 消息类型定义与嵌套结构

消息（Message）是 Protobuf 的基本数据单元。每个字段由 类型、字段名 和 唯一编号 组成。编号 1–15 使用 1 字节编码，适合高频字段；16–2047 使用 2 字节编码，适合低频或扩展字段。

消息支持嵌套定义，适合表达层次化数据结构，如实时通信中的消息体包含多个附件对象。

message ChatMessage {
  string message_id = 1;
  string sender_id = 2;
  string content = 3;

  message Attachment {
    string file_name = 1;
    string file_url = 2;
    int32 file_size = 3;
  }

  repeated Attachment attachments = 4;
}

3.3 字段规则与数据类型

proto3 支持三种字段规则：singular（默认）、repeated（重复）和 map（映射）。singular 表示零个或一个实例；repeated 表示零个或多个有序列表；map 表示键值对集合。

3.4 默认值与零值语义

proto3 中每个字段在未设置值时使用其类型的零值。这一设计消除了显式默认值声明，但要求开发者理解零值语义以避免逻辑歧义。

3.5 枚举类型定义与使用

枚举（enum）用于定义一组预置常量。proto3 要求枚举的第一个值编号必须为 0，且该值作为默认值。枚举支持别名（allow_alias），允许不同名称映射到同一编号。

enum MessageType {
  MESSAGE_TYPE_UNSPECIFIED = 0;  // 必须存在，零值
  MESSAGE_TYPE_TEXT = 1;
  MESSAGE_TYPE_IMAGE = 2;
  MESSAGE_TYPE_AUDIO = 3;
  MESSAGE_TYPE_VIDEO = 4;
  MESSAGE_TYPE_FILE = 5;
  MESSAGE_TYPE_SYSTEM = 6;
}

message ChatMessage {
  string message_id = 1;
  MessageType type = 2;
  string content = 3;
}

枚举值在跨版本兼容时需注意：新增枚举值不应破坏已有客户端逻辑。建议在枚举末尾追加新值，并避免删除已有值。

3.6 综合示例：实时通信消息定义

以下示例整合了本章所有核心概念，定义了一个适用于双向流实时通信的完整消息结构。

syntax = "proto3";

package im.realtime.v1;

import "google/protobuf/timestamp.proto";

// 消息发送状态枚举
enum SendStatus {
  SEND_STATUS_UNSPECIFIED = 0;
  SEND_STATUS_SENDING = 1;
  SEND_STATUS_SENT = 2;
  SEND_STATUS_DELIVERED = 3;
  SEND_STATUS_FAILED = 4;
}

// 消息体
message ChatMessage {
  string message_id = 1;
  string conversation_id = 2;
  string sender_id = 3;
  string receiver_id = 4;
  MessageType type = 5;
  string content = 6;
  repeated Attachment attachments = 7;
  map<string, string> extensions = 8;
  google.protobuf.Timestamp sent_at = 9;
  SendStatus status = 10;

  enum MessageType {
    MESSAGE_TYPE_UNSPECIFIED = 0;
    MESSAGE_TYPE_TEXT = 1;
    MESSAGE_TYPE_IMAGE = 2;
    MESSAGE_TYPE_AUDIO = 3;
    MESSAGE_TYPE_VIDEO = 4;
  }

  message Attachment {
    string file_name = 1;
    string file_url = 2;
    int32 file_size = 3;
    string mime_type = 4;
  }
}

// 双向流请求与响应
message StreamRequest {
  oneof payload {
    ChatMessage message = 1;
    Heartbeat heartbeat = 2;
    Ack ack = 3;
  }
}

message StreamResponse {
  oneof payload {
    ChatMessage message = 1;
    HeartbeatAck heartbeat_ack = 2;
    Error error = 3;
  }
}

message Heartbeat {
  int64 sequence = 1;
}

message HeartbeatAck {
  int64 sequence = 1;
}

message Ack {
  string message_id = 1;
  SendStatus status = 2;
}

message Error {
  int32 code = 1;
  string message = 2;
}