ProtoBuf 与 gRPC

本文介绍如何使用 ProtoBuf 定义数据结构和服务接口，并在 Go 语言中实现 gRPC 服务端逻辑。请事先配置好 protoc 和 Go 的 gRPC 插件环境。

为什么我们需要 ProtoBuf？#

在微服务和网络通信中，我们需要一种方式来“打包”数据。你可能熟悉 JSON，它易读但体积大、解析慢。

Protocol Buffers (ProtoBuf) 是 Google 开发的一种机制。你可以把它想象成一种强类型的、经过极致压缩的 JSON。

强类型：必须定义字段是 int 还是 string。
契约优先：先写 .proto 文件定义数据结构和接口，再生成代码。

2. 编写你的第一个 ProtoBuf 文件#

ProtoBuf 使用 .proto 文件来描述数据。我们以一个“用户服务”为例。

2.1 头部声明#

每个 .proto 文件的开头都应该包含以下关键信息：

1
// 声明使用 proto3 语法（目前的主流版本，必写）
2
syntax = "proto3";
3

4
// 定义包名，类似于 C++ 的 namespace 或 Java 的 package
5
// 这防止了不同项目之间的命名冲突
6
package user.v1;
7

8
// 【关键】指定 Go 语言生成代码的路径
9
// 格式通常是： "模块名/路径;包名"
10
// - go_package 定义了生成的 .pb.go 文件属于哪个 Go包
11
option go_package = "[example.com/project/api/user;userpb](https://example.com/project/api/user;userpb)";

2.2 定义消息 (Message)#

message 类似于 Go 中的 struct。它是数据传输的基本单元。

1
// 定义一个用户实体
2
message User {
3
  // 字段格式：类型 字段名 = 唯一编号;
4

5
  // 唯一编号（Tag）：1, 2, 3...
6
  // 注意：这个数字非常重要，它是二进制编码时的字段标识，一旦定下来不要轻易修改！
7

8
  int64 id = 1;             // 用户ID
9
  string username = 2;      // 用户名
10
  bool is_active = 3;       // 是否激活
11
  float balance = 4;        // 余额
12
  bytes avatar = 5;         // 头像（二进制数据）
13
}

注意：ProtoBuf 中字段名推荐使用 下划线命名法 (snake_case)，例如 is_active。生成的 Go 代码会自动转为 大驼峰 (PascalCase)，即 IsActive。

2.3 复杂类型：数组与映射#

在实际业务中，我们经常需要列表或字典结构。

1
message UserProfile {
2
  int64 user_id = 1;
3

4
  // repeated 关键字表示数组（切片/List）
5
  // 对应 Go 中的 []string
6
  repeated string hobbies = 2;
7

8
  // map 关键字表示映射
9
  // 对应 Go 中的 map[string]string
10
  map<string, string> metadata = 3;
11
}

2.4 枚举 (Enum)#

当字段只有固定的几个值时，使用枚举。

1
// 枚举通常建议包含一个 0 值作为默认值
2
enum UserStatus {
3
  STATUS_UNKNOWN = 0; // 默认值，必须是0
4
  STATUS_NORMAL = 1;
5
  STATUS_BANNED = 2;
6
}
7

8
message UserStatusRequest {
9
  int64 user_id = 1;
10
  UserStatus status = 2; // 使用上面定义的枚举
11
}

3. 定义服务 (Service) —— gRPC 的核心#

仅仅定义数据结构（Message）是不够的，我们需要定义方法。在 ProtoBuf 中，这叫做 service。

这相当于定义 Go 中的 interface。

1
// 定义 User 服务
2
service UserService {
3
  // 定义一个 RPC 方法：GetUser
4
  // 接收 GetUserRequest，返回 GetUserResponse
5
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
6

7
  // 定义另一个方法：CreateUser
8
  rpc CreateUser (CreateUserRequest) returns (CreateUserResponse);
9
}
10

11
// ------------------------------------
12
// 配套的 Request 和 Response 消息定义
13
// ------------------------------------
14

15
message GetUserRequest {
16
  int64 id = 1;
17
}
18

19
message GetUserResponse {
20
  User user = 1; // 引用上面定义的 User 消息
21
}
22

23
message CreateUserRequest {
24
  string username = 1;
25
  string password = 2;
26
}
27

28
message CreateUserResponse {
29
  int64 id = 1;
30
  bool success = 2;
31
}

4. 从 Proto 到 Go 的映射原理#

假设你已经运行了生成命令（protoc），生成了 user.pb.go (数据结构) 和 user_grpc.pb.go (服务接口)。

你需要理解生成的代码是什么样子的，才能知道怎么去写业务逻辑。

4.1 Message Struct#

ProtoBuf 定义的 message 会被转化为 Go 的 struct。

Proto:

1
message User {
2
  int64 id = 1;
3
  string username = 2;
4
}

生成的 Go 代码 (近似):

1
type User struct {
2
    Id       int64  `protobuf:"varint,1,..." json:"id,omitempty"`
3
    Username string `protobuf:"bytes,2,..." json:"username,omitempty"`
4
    // 还有一些内部使用的字段...
5
}

你可以直接像操作普通结构体一样操作它：user.Id = 100。

4.2 Service Interface#

ProtoBuf 定义的 service 会生成两个关键部分：客户端接口（Client）和 服务端接口（Server）。我们主要关注服务端。

Proto:

1
service UserService {
2
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
3
}

生成的 Go 接口 (在 _grpc.pb.go 中)，统一在名为 _ServiceServer 的接口中，直接在此文件中查找:

1
// 这是你需要实现的接口！
2
type UserServiceServer interface {
3
    // 上下文 Context 永远是第一个参数，用于处理超时和取消
4
    GetUser(context.Context, *GetUserRequest) (*GetUserResponse, error)
5

6
    // 这是一个为了向前兼容的安全方法，必须嵌入
7
    mustEmbedUnimplementedUserServiceServer()
8
}

5. 核心实战：如何在 Go 中实现接口#

步骤 1: 创建结构体#

你需要定义一个结构体，作为服务的承载者。

1
package main
2

3
import (
4
    "context"
5
    "errors"
6
    // 引入生成的 proto 包，假设别名为 pb
7
    pb "[example.com/project/api/user](https://example.com/project/api/user)"
8
)
9

10
// 1. 定义结构体
11
type server struct {
12
    // 2. 【必须】嵌入“未实现的服务端”结构体
13
    // 这样做的好处是，如果你在 .proto 增加了新方法但还没写 Go 代码，
14
    // 程序依然能编译通过（只不过调用新方法会报错“未实现”）。
15
    pb.UnimplementedUserServiceServer
16
}

步骤 2: 实现方法#

完全照搬生成的接口签名来写方法，直接从 type _Server interface 粘贴复制来，并进行相应补全。

例如将 GetUser(context.Context, *GetUserRequest) (*GetUserResponse, error) 补全为 func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) 并实现业务逻辑。

1
// 实现 GetUser 方法
2
// 参数：ctx (上下文), req (请求体指针)
3
// 返回：resp (响应体指针), err (错误信息)
4
func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
5
    // 1. 获取请求参数
6
    userID := req.GetId() // 建议使用 GetId() 方法而不是 .Id，防空指针
7

8
    // 2. 执行业务逻辑 (模拟查库)
9
    if userID == 0 {
10
        return nil, errors.New("用户ID不能为空")
11
    }
12

13
    // 模拟数据
14
    foundUser := &pb.User{
15
        Id:       userID,
16
        Username: "DeepLearningUser",
17
        IsActive: true,
18
        Hobbies:  []string{"coding", "reading"},
19
    }
20

21
    // 3. 构造响应并返回
22
    return &pb.GetUserResponse{
23
        User: foundUser,
24
    }, nil
25
}

步骤 3: 启动 gRPC Server#

最后，你需要编写 main 函数来监听端口并注册你的服务。

1
package main
2

3
import (
4
    "log"
5
    "net"
6

7
    "google.golang.org/grpc"
8
    pb "[example.com/project/api/user](https://example.com/project/api/user)"
9
)
10

11
func main() {
12
    // 1. 监听 TCP 端口
13
    lis, err := net.Listen("tcp", ":50051")
14
    if err != nil {
15
        log.Fatalf("无法监听端口: %v", err)
16
    }
17

18
    // 2. 创建 gRPC 服务器实例
19
    grpcServer := grpc.NewServer()
20

21
    // 3. 注册服务
22
    // 将我们实现的 server{} 结构体注册到 gRPC 服务器上
23
    // 这个 Register 函数是自动生成的代码提供的
24
    pb.RegisterUserServiceServer(grpcServer, &server{})
25

26
    log.Printf("gRPC 服务启动在 :50051 端口...")
27

28
    // 4. 开始服务 (阻塞操作)
29
    if err := grpcServer.Serve(lis); err != nil {
30
        log.Fatalf("服务启动失败: %v", err)
31
    }
32
}

6. 一个 `.bat` 脚本快速生成代码#

这个脚本可以帮助你快速生成 .pb.go _grpc.pb.go 和 _validate.pb.go 文件。

1
@echo off
2
setlocal
3

4
if "%~1"=="" (
5
    echo [USAGE] Please provide a proto file.
6
    exit /b 1
7
)
8

9
set "TARGET_PATH=%~dp1"
10
set "FILE_NAME=%~nx1"
11

12
pushd "%TARGET_PATH%"
13
echo [INFO] Working Directory: %CD%
14

15
protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative --validate_out="lang=go:." "%FILE_NAME%"
16

17
if %errorlevel% neq 0 (
18
    echo [FAIL] Compilation failed!
19
    popd
20
    exit /b 1
21
)
22

23
echo [SUCCESS] Done.
24
popd

cd 到你的 proto 文件目录，运行对应的 .proto 文件：

1
makeproto user.proto

7. 提示#

零值处理：ProtoBuf (proto3) 不会在网络中传输默认值（如 0, false, ""）。

如果你在 Go 中收到 0，你无法区分它是“未设置”还是“故意设置为 0”。
如果必须区分，需要使用 Wrapper 类型（如 google.protobuf.Int32Value）或指针。

字段编号：一旦上线，不要更改字段的编号（Tag）。如果你要把 id = 1 改成 id = 2，旧版本的客户端将无法正确解析数据。
Getter 方法：在 Go 中读取 proto 结构体字段时，尽量使用生成的 GetFieldName() 方法（例如 req.GetUsername()）。如果 req 本身是 nil，直接访问 req.Username 会 Panic，而 req.GetUsername() 会安全返回空字符串。

8. 总结#

写契约：编写 xxx.proto 文件，定义 Message 和 Service。
生成代码：运行 protoc 生成 Go 代码。
定义 Struct：在 Go 中定义 type server struct {} 并嵌入 Unimplemented...。
实现逻辑：为 server 实现接口定义的方法 (ctx, req) -> (resp, err)。
启动注册：在 main 中 net.Listen -> grpc.NewServer -> Register... -> Serve。

为什么我们需要 ProtoBuf？#

2. 编写你的第一个 ProtoBuf 文件#

2.1 头部声明#

2.2 定义消息 (Message)#

2.3 复杂类型：数组与映射#

2.4 枚举 (Enum)#

3. 定义服务 (Service) —— gRPC 的核心#

4. 从 Proto 到 Go 的映射原理#

4.1 Message Struct#

4.2 Service Interface#

5. 核心实战：如何在 Go 中实现接口#

步骤 1: 创建结构体#

步骤 2: 实现方法#

步骤 3: 启动 gRPC Server#

6. 一个 `.bat` 脚本快速生成代码#

7. 提示#

8. 总结#

文章分享

评论区

ProtoBuf 与 gRPC

为什么我们需要 ProtoBuf？#

2. 编写你的第一个 ProtoBuf 文件#

2.1 头部声明#

2.2 定义消息 (Message)#

2.3 复杂类型：数组与映射#

2.4 枚举 (Enum)#

3. 定义服务 (Service) —— gRPC 的核心#

4. 从 Proto 到 Go 的映射原理#

4.1 Message Struct#

4.2 Service Interface#

5. 核心实战：如何在 Go 中实现接口#

步骤 1: 创建结构体#

步骤 2: 实现方法#

步骤 3: 启动 gRPC Server#

6. 一个 .bat 脚本快速生成代码#

7. 提示#

8. 总结#

文章分享

评论区

6. 一个 `.bat` 脚本快速生成代码#