2. Protocol Buffers 基础：.proto 文件结构、消息类型定义、字段规则与标量类型

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化引擎。在 gRPC 流式通信中，所有请求与响应数据都必须以 Protobuf 消息的形式在传输层进行编码和解码。掌握 .proto 文件的结构、消息类型定义、字段规则以及标量类型，是构建可靠发布拓扑数据通道的前提。

2.1 .proto 文件结构

一个标准的 .proto 文件由 包声明、导入声明、选项设置 和 消息定义 四个核心部分组成。以下是一个用于后端发布拓扑的示例文件结构：

syntax = "proto3";                          // 指定语法版本

package publish.topology.v1;                // 包声明，避免命名冲突

import "google/protobuf/timestamp.proto";   // 导入常用类型

option go_package = "publish/topology/v1;topologyv1";  // 代码生成选项

// 节点状态枚举
enum NodeStatus {
  NODE_STATUS_UNSPECIFIED = 0;
  NODE_STATUS_ONLINE = 1;
  NODE_STATUS_OFFLINE = 2;
  NODE_STATUS_DEGRADED = 3;
}

// 拓扑节点消息
message TopologyNode {
  string node_id = 1;
  string node_name = 2;
  NodeStatus status = 3;
  repeated string upstream_ids = 4;
  map<string, string> metadata = 5;
}

2.2 消息类型定义

消息（Message）是 Protobuf 中最核心的数据结构，相当于编程语言中的结构体或类。每条消息由若干个字段组成，每个字段包含 字段规则、数据类型、字段名称 和 唯一编号。

2.3 字段规则：required / optional / repeated

在 proto3 语法中，字段规则相比 proto2 做了简化。下表对比了三种规则在 proto3 中的行为：

2.4 标量类型与默认值

Protobuf 提供了一套跨语言的标量类型映射。在 gRPC 流式通信中，选择合适的标量类型直接影响传输效率和内存占用。以下是常用标量类型及其默认值：

2.5 消息嵌套与复用

在实际的发布拓扑中，消息往往需要嵌套组合。Protobuf 支持在一个 .proto 文件中定义多个消息，也支持消息嵌套：

message PublishTopology {
  string topology_id = 1;
  string version = 2;
  repeated TopologyNode nodes = 3;       // 复用 TopologyNode 消息
  google.protobuf.Timestamp created_at = 4;

  // 嵌套消息：仅在此消息内部使用
  message Edge {
    string source_node_id = 1;
    string target_node_id = 2;
    int32 weight = 3;
  }
  repeated Edge edges = 5;
}

这种嵌套结构非常适合描述发布拓扑中的节点与边关系。在 gRPC 流式通信中，服务端可以持续推送 PublishTopology 消息流，客户端按需解析其中的 nodes 和 edges 列表。

2.6 字段编号与兼容性

字段编号是 Protobuf 二进制格式中识别字段的唯一标识，直接影响向后兼容性。以下是字段编号的分配策略：

• 1 ~ 15 号：使用 1 字节编码，应留给最频繁出现的字段（如 node_id、status）。
• 16 ~ 2047 号：使用 2 字节编码，分配给次频繁字段。
• 2048 ~ 2^29-1：使用 5 字节编码，用于很少出现的扩展字段。
• 19000 ~ 19999：保留编号，不可使用。

2.7 消息定义与字段规则总览

下图展示了 .proto 文件中消息定义、字段规则、标量类型与默认值之间的整体关系，以及它们在 gRPC 流式通信中的位置：

2.8 实战：定义发布拓扑节点消息

综合以上知识点，以下是一个用于后端发布拓扑的完整消息定义示例，包含节点信息、健康状态、依赖关系和元数据：

syntax = "proto3";

package publish.topology.v1;

import "google/protobuf/timestamp.proto";

option go_package = "publish/topology/v1;topologyv1";

// 节点角色枚举
enum NodeRole {
  NODE_ROLE_UNSPECIFIED = 0;
  NODE_ROLE_PRODUCER = 1;
  NODE_ROLE_CONSUMER = 2;
  NODE_ROLE_BROKER = 3;
}

// 拓扑节点消息
message TopologyNode {
  // 频繁访问字段使用小编号
  string node_id = 1;                    // 节点唯一标识
  string node_name = 2;                  // 节点名称
  NodeRole role = 3;                     // 节点角色

  // 健康状态
  bool is_healthy = 4;                   // 是否健康
  int32 active_connections = 5;          // 当前活跃连接数

  // 拓扑关系
  repeated string upstream_ids = 6;      // 上游节点 ID 列表
  repeated string downstream_ids = 7;    // 下游节点 ID 列表

  // 元数据
  map<string, string> labels = 8;       // 标签键值对
  string region = 9;                     // 部署区域
  google.protobuf.Timestamp last_heartbeat = 10;  // 最后心跳时间
}

// 拓扑快照消息（用于流式推送）
message TopologySnapshot {
  string snapshot_id = 1;
  int64 version = 2;
  repeated TopologyNode nodes = 3;
  google.protobuf.Timestamp created_at = 4;
}