3. gRPC 服务定义：service 关键字、RPC 方法类型与方法签名

在 gRPC 的通信模型中，服务定义是一切数据传输的起点。开发者通过 Protocol Buffers（protobuf）的 IDL 语言，使用 service 关键字声明一个 RPC 服务，并在其中定义具体的 RPC 方法。每种方法类型对应不同的流式语义，直接影响后端发布拓扑中数据推送、批量同步、实时转发的实现方式。

3.1 service 关键字与服务定义结构

gRPC 服务定义在 .proto 文件中，使用 service 关键字将一组 RPC 方法聚合为一个逻辑单元。一个典型的服务定义包含：服务名称、方法列表、请求消息类型与响应消息类型。

syntax = "proto3";

package publish.topology;

// 定义发布拓扑数据传输服务
service TopologyDataService {
  // 单次查询节点状态
  rpc GetNodeStatus (NodeStatusRequest) returns (NodeStatusResponse);

  // 服务端流式推送拓扑变更事件
  rpc SubscribeTopologyChange (SubscribeRequest) returns (stream TopologyEvent);

  // 客户端流式批量上报节点指标
  rpc ReportNodeMetrics (stream NodeMetric) returns (ReportAck);

  // 双向流式实时同步发布链路状态
  rpc SyncPublishLink (stream LinkState) returns (stream LinkState);
}

3.2 四种 RPC 方法类型

gRPC 定义了四种 RPC 方法类型，分别对应不同的数据流模式。在后端发布拓扑场景中，这四种类型覆盖了从查询、订阅、批量上报到实时同步的全部通信需求。

3.3 方法签名与消息类型设计

每个 RPC 方法的签名由方法名、请求消息类型和响应消息类型三部分组成。方法签名直接决定了 gRPC 生成的客户端桩（Stub）和服务端抽象接口的形态。

// 方法签名格式
rpc 方法名 (请求消息类型) returns (响应消息类型);

// 示例：一元方法
rpc GetNodeStatus (NodeStatusRequest) returns (NodeStatusResponse);

// 示例：服务端流方法
rpc SubscribeTopologyChange (SubscribeRequest) returns (stream TopologyEvent);

// 示例：客户端流方法
rpc ReportNodeMetrics (stream NodeMetric) returns (ReportAck);

// 示例：双向流方法
rpc SyncPublishLink (stream LinkState) returns (stream LinkState);

消息类型的设计直接影响流式通信的粒度和性能。以下是发布拓扑中常见的消息设计原则：

• 请求消息：包含标识符、过滤条件、控制参数，尽量保持轻量。
• 响应消息：对于流式方法，每条消息应包含完整的业务数据单元，避免跨消息拼接。
• 流式消息：建议在消息内加入序列号或时间戳，便于接收方处理乱序和重传。

3.4 四种方法类型的流式语义对比

理解流式语义的差异，是正确设计发布拓扑数据传输协议的前提。下表从连接生命周期、背压处理、错误恢复三个维度进行对比：

3.5 服务定义与发布拓扑的映射关系

下图展示了四种 RPC 方法类型在后端发布拓扑中的典型数据流映射：

3.6 方法签名中的流式关键字使用规范

在 .proto 文件中，stream 关键字的位置决定了流的方向。以下是使用规范：

• 无 stream：请求和响应均为单条消息，对应 Unary 方法。
• 响应侧 stream：returns (stream ResponseType)，服务端可发送多条响应消息。
• 请求侧 stream：rpc Method (stream RequestType) returns (ResponseType)，客户端可发送多条请求消息。
• 双侧 stream：rpc Method (stream RequestType) returns (stream ResponseType)，双方均可独立发送多条消息。

3.7 服务定义的最佳实践

结合后端发布拓扑的实际需求，以下是服务定义阶段的关键建议：

1. 按业务域拆分服务：将拓扑查询、事件订阅、指标上报、链路同步分别定义为独立服务，避免单个服务过于臃肿。
2. 流式方法优先使用 Server Streaming：在发布拓扑中，服务端是数据生产方，Server Streaming 天然适合推送场景，实现简单且易于控制背压。
3. 为流式消息添加元数据：在消息体内包含 sequence_id、timestamp、batch_id 等字段，便于接收方处理乱序、去重和断点续传。
4. 避免在流式方法中传输大消息：单条消息建议控制在 1MB 以内，超过时应考虑分片或使用独立的文件传输通道。