4. 第一个 gRPC 服务：编写 .proto 文件、生成 Go 代码、实现 Server 端、实现 Client 端、运行与测试

本章将带领你从零搭建一个完整的 gRPC 服务，涵盖契约定义、代码生成、服务端与客户端实现，以及最终的运行验证。这是后续所有契约校验实践的基础骨架。

4.1 整体流程概览

一个 gRPC 服务的开发遵循“契约优先”原则，核心流程如下：

1. 编写 .proto 文件：定义服务接口、请求与响应消息结构。
2. 生成 Go 代码：使用 protoc 编译器及对应插件生成服务端与客户端桩代码。
3. 实现 Server 端：编写业务逻辑，实现生成的接口。
4. 实现 Client 端：编写客户端代码，调用远程服务。
5. 运行与测试：启动服务端，运行客户端，验证通信是否正常。

4.2 编写 .proto 文件

在项目根目录创建 proto/user/v1/user.proto 文件，定义服务与消息结构。

syntax = "proto3";

package user.v1;

option go_package = "github.com/your-username/grpc-demo/gen/user/v1;userv1";

// 用户服务定义
service UserService {
  // 获取用户信息
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

// 请求消息：用户 ID
message GetUserRequest {
  string user_id = 1;
}

// 响应消息：用户信息
message GetUserResponse {
  string user_id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
}

4.3 生成 Go 代码

确保已安装 protoc 编译器及 Go 插件：

# 安装 protoc（macOS）
brew install protobuf

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

在项目根目录执行以下命令生成代码：

protoc --proto_path=proto \
  --go_out=gen \
  --go_opt=paths=source_relative \
  --go-grpc_out=gen \
  --go-grpc_opt=paths=source_relative \
  proto/user/v1/user.proto

生成后的目录结构：

gen/
└── user/
    └── v1/
        ├── user.pb.go          # 消息序列化代码
        └── user_grpc.pb.go     # 服务端/客户端桩代码

4.4 实现 Server 端

创建 server/main.go，实现 UserServiceServer 接口：

package main

import (
    "context"
    "log"
    "net"

    "google.golang.org/grpc"
    pb "github.com/your-username/grpc-demo/gen/user/v1"
)

// 服务端结构体
type userServer struct {
    pb.UnimplementedUserServiceServer
}

// 实现 GetUser 方法
func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    // 模拟数据库查询
    return &pb.GetUserResponse{
        UserId: req.UserId,
        Name:   "Alice",
        Email:  "alice@example.com",
        Age:    30,
    }, nil
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    s := grpc.NewServer()
    pb.RegisterUserServiceServer(s, &userServer{})

    log.Println("Server listening on :50051")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

4.5 实现 Client 端

创建 client/main.go，连接服务端并调用 GetUser 方法：

package main

import (
    "context"
    "log"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "github.com/your-username/grpc-demo/gen/user/v1"
)

func main() {
    // 建立连接（本示例使用不安全连接）
    conn, err := grpc.Dial("localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("did not connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewUserServiceClient(conn)

    // 设置超时上下文
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()

    // 调用 RPC
    resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "123"})
    if err != nil {
        log.Fatalf("could not get user: %v", err)
    }

    log.Printf("User Info: ID=%s, Name=%s, Email=%s, Age=%d",
        resp.UserId, resp.Name, resp.Email, resp.Age)
}

4.6 运行与测试

启动服务端和客户端，验证通信是否正常。

1. 启动服务端：在项目根目录执行 go run server/main.go，看到输出 Server listening on :50051 表示启动成功。
2. 启动客户端：另开终端，执行 go run client/main.go，看到类似以下输出表示调用成功：

2025/01/15 10:30:00 User Info: ID=123, Name=Alice, Email=alice@example.com, Age=30

4.7 常见问题与排查