3. gRPC 服务定义与生成：编写.proto文件、使用protoc生成客户端/服务端代码、gRPC拦截器机制

3.1 核心流程概述

在分布式事务压测场景中，gRPC 服务的定义与代码生成是测试验证的起点。本章聚焦于从 .proto 文件编写到拦截器注入的完整链路，确保压测工具能够高效、准确地模拟分布式事务的调用行为。

3.2 编写 .proto 文件：分布式事务压测的契约设计

.proto 文件是 gRPC 服务的核心契约。在压测场景中，除了定义业务接口，还需显式声明分布式事务所需的元数据字段。

3.2.1 基础服务定义示例

syntax = "proto3";

package transaction.benchmark;

option go_package = "proto/transaction;transactionpb";

// 分布式事务上下文
message TransactionContext {
  string transaction_id = 1;   // 全局事务 ID
  string span_id = 2;          // 调用链 Span ID
  int64  timestamp = 3;        // 发起时间戳（毫秒）
  map<string, string> baggage = 4; // 透传的上下文标签
}

// 转账请求
message TransferRequest {
  TransactionContext ctx = 1;
  string from_account = 2;
  string to_account = 3;
  double amount = 4;
  int32  timeout_ms = 5;       // 单次调用超时
}

// 转账响应
message TransferResponse {
  bool   success = 1;
  string message = 2;
  string tcc_status = 3;       // TCC 阶段状态：TRY/CONFIRM/CANCEL
}

// 分布式事务压测服务
service TransactionBenchmark {
  // 一元 RPC：TCC-Try 阶段
  rpc TryTransfer(TransferRequest) returns (TransferResponse);

  // 服务端流式 RPC：批量查询事务状态
  rpc QueryTransactionStatus(TransactionContext) returns (stream TransferResponse);

  // 双向流式 RPC：压测控制指令下发
  rpc BenchmarkControl(stream ControlCommand) returns (stream BenchmarkReport);
}

message ControlCommand {
  string action = 1;           // start / stop / reset
  int32  concurrency = 2;
  int32  total_requests = 3;
}

message BenchmarkReport {
  int64  request_id = 1;
  double latency_ms = 2;
  int32  status_code = 3;
}

3.2.2 字段类型选择与压测性能关系

3.3 使用 protoc 生成客户端/服务端代码

protoc 是 Protocol Buffers 的官方编译器。在分布式事务压测项目中，通常需要生成 Go 语言的桩代码，并集成 gRPC 扩展插件。

3.3.1 标准生成命令

# 安装 protoc 及 Go 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# 生成消息代码 + gRPC 服务代码
protoc --proto_path=. \
  --go_out=paths=source_relative:./proto \
  --go-grpc_out=paths=source_relative:./proto \
  transaction_benchmark.proto

3.3.2 生成产物结构

3.4 gRPC 拦截器机制：压测数据采集的核心扩展点

拦截器（Interceptor）是 gRPC 提供的中间件机制，允许在 RPC 调用前后注入自定义逻辑。在分布式事务压测中，拦截器承担着全链路追踪、指标采集、故障注入等关键职责。

3.4.1 拦截器类型对比

3.4.2 压测场景中的拦截器链实现

// 客户端拦截器：注入分布式事务上下文
func TransactionContextInjector(ctx context.Context, method string,
  req, reply interface{}, cc *grpc.ClientConn,
  invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {

  // 从 context 中提取全局事务 ID
  txID := metadata.ValueFromIncoming(ctx, "x-transaction-id")
  if txID == "" {
    txID = uuid.New().String() // 压测时自动生成
  }

  // 将事务 ID 注入到出站 metadata
  md := metadata.Pairs("x-transaction-id", txID)
  ctx = metadata.NewOutgoingContext(ctx, md)

  // 记录调用开始时间
  start := time.Now()
  err := invoker(ctx, method, req, reply, cc, opts...)
  latency := time.Since(start)

  // 上报延迟到压测指标收集器
  metrics.RecordLatency(method, latency)
  return err
}

// 服务端拦截器：提取并验证事务上下文
func TransactionContextExtractor(ctx context.Context, req interface{},
  info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {

  md, ok := metadata.FromIncomingContext(ctx)
  if !ok {
    return nil, status.Errorf(codes.InvalidArgument, "missing metadata")
  }

  txIDs := md.Get("x-transaction-id")
  if len(txIDs) == 0 {
    return nil, status.Errorf(codes.InvalidArgument, "missing transaction id")
  }

  // 将事务 ID 存入 context，供业务逻辑使用
  ctx = context.WithValue(ctx, "transaction_id", txIDs[0])
  return handler(ctx, req)
}

3.4.3 拦截器装配与压测集成

// 客户端装配（压测 worker 初始化）
func NewBenchmarkClient(target string) (TransactionBenchmarkClient, error) {
  conn, err := grpc.Dial(
    target,
    grpc.WithInsecure(),
    grpc.WithUnaryInterceptor(TransactionContextInjector),
    grpc.WithStreamInterceptor(StreamMetricsInterceptor),
    grpc.WithDefaultCallOptions(
      grpc.MaxCallRecvMsgSize(4*1024*1024), // 4MB 限制
      grpc.WaitForReady(true),
    ),
  )
  if err != nil {
    return nil, err
  }
  return NewTransactionBenchmarkClient(conn), nil
}

// 服务端装配（压测目标服务）
func StartBenchmarkServer(port int) {
  s := grpc.NewServer(
    grpc.UnaryInterceptor(TransactionContextExtractor),
    grpc.StreamInterceptor(RateLimitStreamInterceptor),
    grpc.MaxRecvMsgSize(4*1024*1024),
  )
  RegisterTransactionBenchmarkServer(s, &BenchmarkServiceImpl{})
  lis, _ := net.Listen("tcp", fmt.Sprintf(":%d", port))
  s.Serve(lis)
}

3.5 压测场景中的拦截器最佳实践

• 轻量原则： 拦截器内避免执行阻塞操作（如数据库查询、远程调用），压测时每个微秒都影响 QPS。
• 无状态设计： 拦截器不应持有可变状态，防止并发压测时的竞态条件。
• 错误传播： 拦截器返回的错误会终止 RPC 调用链，压测时需区分“业务错误”与“系统错误”。
• 元数据大小控制： 注入到 metadata 的 key-value 对总数建议 ≤ 10 对，避免 protobuf 编码膨胀。
• 采样率支持： 在拦截器中实现可配置的采样逻辑，压测初期 100% 采样，稳定后降至 1%~5%。