2. gRPC基础回顾：Protocol Buffers语法、gRPC服务定义、一元与服务器/客户端流模式

在进入消息队列双向流通信实战之前，必须夯实gRPC的核心基础。本章将系统回顾Protocol Buffers（protobuf）的接口定义语法、gRPC服务定义规范，以及四种通信模式中的三种基础模式：一元RPC、服务器端流式RPC、客户端流式RPC。双向流模式将在后续章节深入展开。

2.1 Protocol Buffers 语法速览

Protocol Buffers 是 gRPC 的默认接口定义语言（IDL）和序列化协议。它使用 .proto 文件定义消息结构和服务接口，具有语言中立、平台无关、序列化体积小、解析速度快等优势。

2.1.1 消息类型定义

一个典型的 protobuf 消息定义包含字段编号、字段类型和字段名称。字段编号是二进制编码的关键标识，一旦发布不应修改。

syntax = "proto3";

package messagequeue.v1;

// 任务消息体
message TaskMessage {
  string task_id = 1;
  string queue_name = 2;
  bytes payload = 3;
  int32 priority = 4;
  map<string, string> headers = 5;
}

2.1.2 标量类型与复合类型

2.1.3 枚举与嵌套消息

// 任务状态枚举
enum TaskStatus {
  TASK_STATUS_UNSPECIFIED = 0;
  TASK_STATUS_PENDING = 1;
  TASK_STATUS_PROCESSING = 2;
  TASK_STATUS_COMPLETED = 3;
  TASK_STATUS_FAILED = 4;
}

// 嵌套消息示例
message TaskResult {
  string task_id = 1;
  TaskStatus status = 2;
  string error_message = 3;
  int64 completed_at = 4;
}

2.2 gRPC 服务定义

gRPC 服务定义在 .proto 文件中使用 service 关键字声明。每个服务包含若干 RPC 方法，每个方法指定输入消息类型和输出消息类型。

2.2.1 服务定义语法

service TaskQueue {
  // 一元 RPC：提交任务，返回确认
  rpc SubmitTask(TaskMessage) returns (TaskAck);

  // 服务器端流式 RPC：订阅任务结果流
  rpc SubscribeResult(TaskFilter) returns (stream TaskResult);

  // 客户端流式 RPC：批量上报任务进度
  rpc ReportProgress(stream ProgressReport) returns (SummaryResponse);

  // 双向流式 RPC：任务分发与结果回收
  rpc ProcessTask(stream TaskMessage) returns (stream TaskResult);
}

2.2.2 四种通信模式对比

2.3 一元 RPC 模式详解

一元 RPC 是最基础的请求-响应模式。客户端发送一个请求消息，服务器处理后返回一个响应消息。其行为类似于传统的 HTTP API 调用，但底层使用 HTTP/2 和 protobuf 序列化，性能更高。

// 一元 RPC 服务端实现示例（Go）
func (s *taskQueueServer) SubmitTask(ctx context.Context, req *pb.TaskMessage) (*pb.TaskAck, error) {
    // 验证请求
    if req.TaskId == "" {
        return nil, status.Errorf(codes.InvalidArgument, "task_id is required")
    }
    // 处理业务逻辑
    err := s.store.SaveTask(ctx, req)
    if err != nil {
        return nil, status.Errorf(codes.Internal, "failed to save task: %v", err)
    }
    // 返回响应
    return &pb.TaskAck{
        TaskId:   req.TaskId,
        Accepted: true,
        Timestamp: time.Now().Unix(),
    }, nil
}

2.4 服务器端流式 RPC 模式

服务器端流式 RPC 允许服务器在收到客户端的一个请求后，通过流式响应返回多条消息。客户端通过迭代读取流来逐个处理响应。这种模式非常适合事件订阅、日志推送、数据导出等场景。

// 服务器端流式 RPC 服务端实现示例（Go）
func (s *taskQueueServer) SubscribeResult(req *pb.TaskFilter, stream pb.TaskQueue_SubscribeResultServer) error {
    // 创建结果通道
    resultCh := make(chan *pb.TaskResult, 100)
    // 启动后台协程推送结果
    go s.resultDispatcher.Dispatch(req, resultCh)
    // 持续读取并发送
    for result := range resultCh {
        if err := stream.Send(result); err != nil {
            return err
        }
    }
    return nil
}

2.5 客户端端流式 RPC 模式

客户端端流式 RPC 允许客户端通过流式请求发送多条消息，服务器在所有消息接收完毕后返回一个单条响应。这种模式适用于批量数据上传、日志聚合、传感器数据采集等场景。

// 客户端端流式 RPC 客户端调用示例（Go）
func reportProgress(client pb.TaskQueueClient, reports []*pb.ProgressReport) (*pb.SummaryResponse, error) {
    stream, err := client.ReportProgress(ctx)
    if err != nil {
        return nil, err
    }
    // 逐个发送进度报告
    for _, report := range reports {
        if err := stream.Send(report); err != nil {
            return nil, err
        }
    }
    // 关闭发送端，等待服务器响应
    return stream.CloseAndRecv()
}

2.6 三种基础模式对比总结

2.7 三种基础模式通信流程图示

下图展示了三种基础 gRPC 通信模式的交互流程，帮助理解客户端与服务器之间的消息传递方向与生命周期。

2.8 消息队列场景中的模式选择

在消息队列系统中，不同通信模式对应不同的交互场景。下表给出了典型的选择建议：

2.9 本章小结

本章系统回顾了 gRPC 的核心基础：

• Protocol Buffers 语法：消息类型定义、标量与复合类型、枚举与嵌套消息、字段编号规则。
• gRPC 服务定义：service 关键字、RPC 方法声明、四种通信模式的语法差异。
• 一元 RPC：单请求-单响应，适用于提交/确认类操作。
• 服务器端流式 RPC：单请求-多响应，适用于事件订阅和数据推送。
• 客户端端流式 RPC：多请求-单响应，适用于批量上传和聚合报告。