4. gRPC 契约测试：gRPC 服务模拟、protobuf 契约定义、客户端/服务端测试桩、流式调用测试

在微服务架构中，gRPC 已成为跨语言服务调用的主流协议。本章聚焦于 gRPC 契约测试的核心实践：从 protobuf 契约定义出发，构建 服务端测试桩与客户端测试桩，并覆盖流式调用的测试场景。通过契约驱动的方式，确保服务提供者与消费者之间的接口行为始终与 .proto 文件保持一致，避免因接口变更导致的集成故障。

4.1 protobuf 契约定义与代码生成

protobuf 契约定义了服务的方法签名、请求/响应消息结构以及字段约束。在 Go 项目中，通常使用 protoc 编译器配合 protoc-gen-go-grpc 插件生成服务端和客户端代码。

// 示例：order.proto 核心片段
syntax = "proto3";
package order;

service OrderService {
  rpc CreateOrder (CreateOrderRequest) returns (CreateOrderResponse);
  rpc GetOrder (GetOrderRequest) returns (GetOrderResponse);
  rpc SubscribeOrderStatus (SubscribeRequest) returns (stream OrderStatusEvent);
}

message CreateOrderRequest {
  string user_id = 1;
  repeated string product_ids = 2;
  double total_amount = 3;
}

message CreateOrderResponse {
  string order_id = 1;
  int32 status_code = 2;
  string message = 3;
}

message SubscribeRequest {
  string order_id = 1;
}

message OrderStatusEvent {
  string order_id = 1;
  string new_status = 2;
  int64 timestamp = 3;
}

4.2 gRPC 服务模拟与测试桩

在集成测试中，我们无法依赖真实的下游 gRPC 服务。通过 服务端测试桩（Server Stub）和 客户端测试桩（Client Stub），可以模拟 gRPC 调用的完整生命周期。

4.2.1 服务端测试桩（Mock Server）

服务端测试桩模拟 gRPC 服务端的行为，接收客户端请求并返回预设响应。Go 中常用 bufconn 包创建内存中的 gRPC 连接，避免真实端口占用。

// 服务端测试桩示例
func TestCreateOrder_ServerStub(t *testing.T) {
    // 1. 创建内存监听器
    lis := bufconn.Listen(1024 * 1024)
    s := grpc.NewServer()

    // 2. 注册模拟服务实现
    mockSvc := &mockOrderService{}
    order.RegisterOrderServiceServer(s, mockSvc)

    // 3. 启动服务
    go func() {
        if err := s.Serve(lis); err != nil {
            t.Fatalf("failed to serve: %v", err)
        }
    }()
    defer s.Stop()

    // 4. 创建客户端连接
    conn, err := grpc.DialContext(context.Background(), "bufnet",
        grpc.WithContextDialer(func(ctx context.Context, s string) (net.Conn, error) {
            return lis.Dial()
        }), grpc.WithInsecure())
    if err != nil {
        t.Fatalf("failed to dial: %v", err)
    }
    defer conn.Close()

    // 5. 发起测试调用
    client := order.NewOrderServiceClient(conn)
    resp, err := client.CreateOrder(context.Background(), &order.CreateOrderRequest{
        UserId:    "user-001",
        ProductIds: []string{"prod-1", "prod-2"},
        TotalAmount: 99.99,
    })
    // 断言...
}

// 模拟服务实现
type mockOrderService struct {
    order.UnimplementedOrderServiceServer
}

func (m *mockOrderService) CreateOrder(ctx context.Context, req *order.CreateOrderRequest) (*order.CreateOrderResponse, error) {
    // 固定返回成功响应
    return &order.CreateOrderResponse{
        OrderId:   "order-mock-001",
        StatusCode: 200,
        Message:   "mock success",
    }, nil
}

4.2.2 客户端测试桩（Client Stub）

客户端测试桩用于测试服务端逻辑，模拟下游 gRPC 客户端的调用行为。通过接口抽象，可以在测试中注入返回错误、超时、特定状态码等异常场景。

// 客户端测试桩接口定义
type OrderServiceClient interface {
    CreateOrder(ctx context.Context, req *order.CreateOrderRequest) (*order.CreateOrderResponse, error)
    GetOrder(ctx context.Context, req *order.GetOrderRequest) (*order.GetOrderResponse, error)
}

// 测试桩实现：固定返回错误
type errorClientStub struct{}

func (e *errorClientStub) CreateOrder(ctx context.Context, req *order.CreateOrderRequest) (*order.CreateOrderResponse, error) {
    return nil, status.Error(codes.Unavailable, "service temporarily unavailable")
}

func (e *errorClientStub) GetOrder(ctx context.Context, req *order.GetOrderRequest) (*order.GetOrderResponse, error) {
    return nil, status.Error(codes.NotFound, "order not found")
}

4.3 流式调用测试

gRPC 支持四种流式模式：一元（Unary）、服务端流（Server Streaming）、客户端流（Client Streaming）和双向流（Bidirectional Streaming）。流式调用的测试重点在于：流的建立、消息的持续发送/接收、流的关闭以及错误传播。

// 服务端流测试示例：订阅订单状态变更
func TestSubscribeOrderStatus_ServerStream(t *testing.T) {
    // 设置服务端测试桩（返回流式响应）
    mockSvc := &mockStreamService{}
    order.RegisterOrderServiceServer(s, mockSvc)

    // ...（服务启动代码同前）

    client := order.NewOrderServiceClient(conn)
    stream, err := client.SubscribeOrderStatus(context.Background(), &order.SubscribeRequest{
        OrderId: "order-001",
    })
    if err != nil {
        t.Fatalf("failed to subscribe: %v", err)
    }

    // 接收流式消息
    var receivedEvents []*order.OrderStatusEvent
    for {
        event, err := stream.Recv()
        if err == io.EOF {
            break // 流正常结束
        }
        if err != nil {
            t.Fatalf("failed to receive event: %v", err)
        }
        receivedEvents = append(receivedEvents, event)
    }

    // 断言：至少收到 3 个状态变更事件
    if len(receivedEvents) < 3 {
        t.Errorf("expected at least 3 events, got %d", len(receivedEvents))
    }
}

// 模拟流式服务端实现
type mockStreamService struct {
    order.UnimplementedOrderServiceServer
}

func (m *mockStreamService) SubscribeOrderStatus(req *order.SubscribeRequest, stream order.OrderService_SubscribeOrderStatusServer) error {
    events := []*order.OrderStatusEvent{
        {OrderId: "order-001", NewStatus: "CREATED", Timestamp: 1000},
        {OrderId: "order-001", NewStatus: "PAID", Timestamp: 2000},
        {OrderId: "order-001", NewStatus: "SHIPPED", Timestamp: 3000},
    }
    for _, event := range events {
        if err := stream.Send(event); err != nil {
            return err
        }
    }
    return nil // 发送完毕，关闭流
}

4.4 契约测试的故障排查清单

在集成测试中，gRPC 契约不匹配是导致故障的主要原因。以下清单帮助快速定位问题根因：