Snow.
中
All writing Notes & observations

Go gRPC Tutorial

6 min read
阅读中文版

前言

gRPC 是一个高性能、开源的远程过程调用（RPC）框架，由 Google 开发。它基于 HTTP/2 协议设计，默认使用 Protocol Buffers 作为序列化工具，支持跨语言、跨平台的服务调用。对于 Go 语言开发者来说，gRPC 是构建微服务架构的首选工具之一，它能够极大地简化服务间的通信开发，同时提供极高的性能。

本文章将从最基础的概念开始，带你一步步完成从环境搭建到实战开发，再到容器化部署的全流程，覆盖 Windows、Linux、Mac 三大主流系统，以及 Docker 容器化部署方案，让你从零开始，快速掌握 Go 语言下的 gRPC 开发。

一、核心概念入门

1.1 什么是 gRPC？

gRPC 是一个现代化的 RPC 框架，它允许客户端应用直接调用不同机器上的服务端方法，就像调用本地方法一样。它基于 HTTP/2 协议，带来了以下优势：

  • 多路复用：在同一个 TCP 连接上并行处理多个请求，减少连接开销

  • 流处理：支持客户端、服务端的双向流处理

  • 强类型接口：基于 Protobuf 定义服务接口，天然支持跨语言

  • 高性能：二进制序列化，比 JSON 等文本格式更快、更小

1.2 什么是 Protocol Buffers？

Protocol Buffers（简称 Protobuf）是 Google 推出的一种轻量级、高效的结构化数据序列化格式，它比 XML、JSON 更小、更快、更简单。在 gRPC 中，我们使用 Protobuf 来定义服务的接口和消息结构，然后通过编译器生成不同语言的代码。

1.3 gRPC 的四种服务类型

gRPC 支持四种不同类型的服务调用模式，以满足不同的业务场景：

  1. 简单 RPC（Unary RPC）：最基础的调用模式，客户端发送一个请求，服务端返回一个响应，就像普通的函数调用一样。

  2. 客户端流 RPC（Client-side Streaming RPC）：客户端发送多个请求给服务端，服务端处理完后返回一个响应。

  3. 服务端流 RPC（Server-side Streaming RPC）：客户端发送一个请求，服务端返回多个响应流。

  4. 双向流 RPC（Bidirectional Streaming RPC）：客户端和服务端都可以通过读写流来发送多个消息，双方可以独立地读写。

1.4 gRPC 工作架构

下图展示了 gRPC 客户端与服务端的基础交互架构：

  • 客户端侧：业务代码调用本地的 gRPC Stub（客户端桩），Stub 会把调用参数通过 Protobuf 序列化为二进制数据，再通过 HTTP/2 客户端把请求发送出去。
  • 网络传输：基于 TCP 连接的 HTTP/2 协议，支持多路复用，同一个连接可以并行处理多个请求。
  • 服务端侧：HTTP/2 服务端收到请求后，先通过 Protobuf 反序列化出请求参数，交给 gRPC 服务端，再转发到你的业务服务实现，处理完成后把结果原路返回给客户端。

二、Protobuf 基础语法

在开始开发之前，我们需要先掌握 Protobuf 的基础语法，因为我们所有的服务定义都需要写在 .proto 文件中。我们这里使用最新的 proto3 语法，这也是目前 gRPC 推荐的版本。

2.1 基础文件结构

一个标准的 .proto 文件的基础结构如下：

1
2
3
4
5
6
7
8
9

// 1. 声明语法版本，必须放在文件第一行（注释除外）
syntax = "proto3";

// 2. 包声明，用于防止命名冲突，相当于命名空间
package helloworld;

// 3. Go语言专属选项，指定生成代码的包路径和包名
// 格式为: 生成文件的输出路径; 包名
option go_package = "./;pb";

2.2 消息（Message）定义

消息是 Protobuf 中数据的载体，你可以把它理解为 Go 语言中的结构体，用来定义传输的数据结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 定义请求消息
message HelloRequest {
  // 字段格式: 类型 字段名 = 字段编号;
  string name = 1;
}

// 定义响应消息
message HelloReply {
  string message = 1;
}

关键字段说明

  • 字段类型：支持基础类型（int32、int64、float、bool、string 等），也支持嵌套的消息类型。

  • 字段编号：每个字段都必须有一个唯一的数字编号，范围是 1~536870911，其中 1~15 占用 1 个字节，16~2047 占用 2 个字节，所以高频使用的字段尽量用小编号。

  • 重复字段：如果需要定义数组 / 列表，使用 repeated 关键字：

    1
2
3
4
5

    message Person {
  string name = 1;
  // repeated 表示这是一个列表
  repeated string hobbies = 2;
}

2.3 服务（Service）定义

服务定义了 gRPC 接口的方法，用来声明客户端可以调用的远程方法：

1
2
3
4
5
6

// 定义 Greeter 服务
service Greeter {
  // 定义一个简单的 RPC 方法
  // 格式: rpc 方法名(请求消息) returns (响应消息);
  rpc SayHello (HelloRequest) returns (HelloReply);
}

三、开发环境搭建

接下来我们分别介绍在 Windows、Linux、Mac 三大系统下的 gRPC Go 开发环境搭建步骤，你可以根据自己的系统选择对应的部分。

3.1 前置条件：安装 Go 语言

首先你需要安装 Go 语言环境，gRPC 要求 Go 版本 >= 1.19，推荐使用最新的稳定版本。

  • 下载地址：Go 官方下载页

  • 安装完成后，打开终端 / 命令行，执行 go version 验证是否安装成功：

    1
2

    go version
# 输出类似: go version go1.22.0 linux/amd64

3.2 安装 Protobuf 编译器（protoc）

protoc 是 Protobuf 的编译器，用来把我们的 .proto 文件编译成不同语言的代码。

Linux 系统（Ubuntu/Debian）

使用 apt 包管理器直接安装：

1
2
3
4
5

sudo apt update
sudo apt install -y protobuf-compiler
# 验证安装
protoc --version
# 输出: libprotoc 3.xx.x，确保版本 >= 3.0

Mac 系统

使用 Homebrew 安装：

1
2
3

brew install protobuf
# 验证安装
protoc --version

Windows 系统

  1. 前往 Protobuf 发布页，下载对应 Windows 版本的压缩包，比如 protoc-xx.x-x-win64.zip

  2. 解压压缩包，把解压后的 bin 目录下的 protoc.exe 所在的路径添加到系统的 Path 环境变量中：

    • 右键此电脑 -> 属性 -> 高级系统设置 -> 环境变量

    • 在系统变量中找到 Path，点击编辑，添加 protoc.exe 所在的文件夹路径

  3. 打开新的命令行，执行 protoc --version 验证是否安装成功。

3.3 安装 Go 语言的 Protobuf 插件

protoc 本身只支持基础的 C++ 等语言，要生成 Go 语言的代码，我们需要安装两个 Go 专属的插件：

  • protoc-gen-go：用来生成基础的 Protobuf 消息结构代码

  • protoc-gen-go-grpc：用来生成 gRPC 的服务端和客户端代码

执行以下命令安装这两个插件：

1
2
3
4
5

# 安装基础的 Protobuf 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

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

安装完成后，需要把 Go 的二进制目录添加到系统的 PATH 环境变量中，这样系统才能找到这两个插件：

1
2
3

# 查看 Go 的 GOPATH 路径
go env GOPATH
# 输出类似: /home/user/go 或者 C:\Users\YourName\go

  • Linux/Mac：在终端中执行以下命令，或者把它添加到 ~/.bashrc 或 ~/.zshrc 中永久生效：

    1

    export PATH="$PATH:$(go env GOPATH)/bin"

  • Windows：把 %GOPATH%\bin（通常是 C:\Users\你的用户名\go\bin）添加到系统的 Path 环境变量中。

验证插件是否安装成功：

1
2
3

# 执行这两个命令，如果没有提示命令不存在，就说明安装成功了
protoc-gen-go --version
protoc-gen-go-grpc --version

四、实战入门：Hello World 示例

现在我们来完成一个最基础的 Hello World 示例，带你完整走一遍 gRPC 开发的全流程。

4.1 创建项目结构

首先创建我们的项目目录，结构如下：

1
2
3
4
5
6
7
8
9

grpc-hello/
├── go.mod
├── go.sum
├── proto/
│   └── helloworld.proto  # 我们的 proto 定义文件
├── server/
│   └── main.go           # 服务端代码
└── client/
    └── main.go           # 客户端代码

执行以下命令初始化项目：

1
2
3
4
5

# 创建项目文件夹
mkdir grpc-hello && cd grpc-hello

# 初始化 Go mod
go mod init github.com/yourname/grpc-hello

4.2 编写 Protobuf 定义文件

创建 proto/helloworld.proto 文件，写入以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

syntax = "proto3";

package helloworld;

option go_package = "../pb;pb";

// 定义请求消息
message HelloRequest {
  string name = 1;
}

// 定义响应消息
message HelloReply {
  string message = 1;
}

// 定义 Greeter 服务
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

4.3 生成 Go 代码

现在我们使用 protoc 编译器，把上面的 .proto 文件编译成 Go 语言的代码。在项目根目录执行以下命令：

1

protoc --go_out=. --go-grpc_out=. proto/helloworld.proto

执行完成后，你会发现项目根目录下多了一个 pb 文件夹，里面有两个文件：

  • helloworld_grpc.pb.go：gRPC 相关的服务端、客户端代码

  • helloworld.pb.go：Protobuf 消息结构的代码

4.4 编写服务端代码

创建 server/main.go 文件，这是我们的 gRPC 服务端代码，用来处理客户端的请求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	pb "github.com/yourname/grpc-hello/pb" // 替换成你自己的模块路径
)

// 定义服务结构体，必须嵌入 pb.UnimplementedGreeterServer
// 这是为了兼容未来的接口扩展，保证向前兼容
type server struct {
	pb.UnimplementedGreeterServer
}

// 实现 SayHello 方法，这是我们在 proto 中定义的服务方法
func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
	// 打印收到的请求信息
	log.Printf("Received request from: %v", in.GetName())
	// 返回响应
	return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

func main() {
	// 监听 50051 端口，这是 gRPC 的默认端口
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}

	// 创建 gRPC 服务端实例
	s := grpc.NewServer()
	// 把我们的服务注册到 gRPC 服务端中
	pb.RegisterGreeterServer(s, &server{})

	log.Printf("server listening at %v", lis.Addr())
	// 启动服务，开始处理请求
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

4.5 编写客户端代码

创建 client/main.go 文件，这是我们的客户端代码，用来调用服务端的远程方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	pb "github.com/yourname/grpc-hello/pb" // 替换成你自己的模块路径
)

func main() {
	// 连接到 gRPC 服务端，这里我们连接本地的 50051 端口
	// 使用 insecure  credentials，因为我们的示例没有开启 TLS
	conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	// 函数结束时关闭连接
	defer conn.Close()

	// 创建 Greeter 客户端
	c := pb.NewGreeterClient(conn)

	// 设置超时时间，防止请求阻塞
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	// 调用远程的 SayHello 方法
	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: "World"})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}

	// 打印响应结果
	log.Printf("Greeting: %s", r.GetMessage())
}

4.6 运行测试

现在我们来启动服务端，然后运行客户端，测试我们的 gRPC 服务。

  1. 首先启动服务端：

    1

    go run server/main.go

    你会看到输出：server listening at [::]:50051，说明服务端已经启动成功了。

  2. 打开一个新的终端，运行客户端：

    1

    go run client/main.go

    客户端会输出：Greeting: Hello World，说明调用成功了！

  3. 回到服务端的终端，你会看到服务端输出：Received request from: World，说明服务端成功收到了客户端的请求。

恭喜你！你已经成功运行了你的第一个 gRPC 应用！

五、Docker 容器化部署

当我们开发完成后，我们可以把我们的 gRPC 服务打包成 Docker 镜像，方便部署和分发。这里我们使用多阶段构建的方式，来最小化镜像的体积。

5.1 编写 Dockerfile

在项目的根目录创建 Dockerfile 文件，内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 第一阶段：构建阶段，使用完整的 Go 环境来编译代码
FROM golang:1.22-alpine AS builder

# 设置工作目录
WORKDIR /app

# 复制 go.mod 和 go.sum，先下载依赖，利用 Docker 缓存
COPY go.mod go.sum ./
RUN go mod download

# 复制所有代码
COPY . .

# 编译代码，CGO_ENABLED=0 表示静态编译，不依赖动态库
# GOOS=linux 指定目标系统是 Linux
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o grpc-server ./server/main.go

# 第二阶段：运行阶段，使用极小的 alpine 镜像，只保留编译后的二进制文件
FROM alpine:latest

# 安装 ca-certificates，用于 TLS 证书验证
RUN apk --no-cache add ca-certificates

WORKDIR /root/

# 从构建阶段复制编译好的二进制文件
COPY --from=builder /app/grpc-server .

# 暴露服务端口
EXPOSE 50051

# 启动服务
CMD ["./grpc-server"]

5.2 构建 Docker 镜像

在项目根目录执行以下命令，构建 Docker 镜像：

1

docker build -t grpc-hello-server:latest .

这个命令会自动完成多阶段构建，最终生成的镜像体积非常小，通常只有十几 MB，比直接用 Go 基础镜像小了几十倍。

5.3 运行 Docker 容器

构建完成后，我们可以运行这个镜像，启动我们的 gRPC 服务：

1

docker run -p 50051:50051 grpc-hello-server:latest

这个命令会把容器的 50051 端口映射到主机的 50051 端口，这样我们就可以像之前一样，用本地的客户端来连接这个服务了。

5.4 测试容器化服务

现在你可以运行之前的客户端代码，来测试容器中的服务：

1

go run client/main.go

你会看到和之前一样的输出，说明容器化的服务已经正常工作了！

六、常见问题与排错

6.1 protoc: command not found

这说明系统找不到 protoc 命令，你需要检查：

  1. 是否已经正确安装了 protoc

  2. 是否把 protoc 的路径添加到了系统的 PATH 环境变量中

6.2 Plugin protoc-gen-go not found

这说明系统找不到 protoc-gen-go 插件，检查：

  1. 是否已经正确安装了插件

  2. 是否把 $GOPATH/bin 添加到了 PATH 环境变量中

6.3 模块路径错误

在导入 pb 包的时候，一定要替换成你自己的 go mod 初始化的模块路径，否则会出现导入错误。

6.4 连接超时

如果客户端连接服务端超时，检查：

  1. 服务端是否已经正常启动

  2. 端口是否正确，防火墙是否开放了对应的端口

  3. 如果是 Docker 部署，检查端口映射是否正确

总结

通过本指南，你已经完成了从 0 开始的 gRPC 学习，掌握了：

  1. gRPC 和 Protobuf 的核心概念

  2. 三大系统下的开发环境搭建

  3. 完整的 gRPC 服务开发流程

  4. Docker 容器化部署方案

接下来你可以继续深入学习 gRPC 的高级特性，比如 TLS 加密、认证拦截、流处理、负载均衡等，来构建生产级的微服务应用。