简体中文
Protobuf Go工具区别:protoc / protoc-gen-go / protoc-gen-go-grpc 详解|Go gRPC代码生成踩坑

配套截图版本:
- protoc v3.15.8
- protoc-gen-go v1.23.0
- protoc-gen-go-grpc v1.1.0 (Note: there is no corresponding release, so it must be compiled manually)
一句话总览
很多人混淆这三者,根源在于:protoc 是编译器本体,另外两个是独立插件,分工不同,分开生成代码。
protoc:protobuf 编译器,负责解析.proto文件,调度插件protoc-gen-go:生成消息结构体,对应xxx.pb.goprotoc-gen-go-grpc:生成 gRPC 服务、客户端 stub,对应xxx_grpc.pb.go
看截图可以印证: acl.pb.go 文件头部标注 Code generated by protoc-gen-goacl_grpc.pb.go 文件头部标注 Code generated by protoc-gen-go-grpc
项目地址 & 作用详解
1. protoc(Protocol Buffers 编译器)
仓库地址:https://github.com/protocolbuffers/protobuf
- 官方仓库,C++ 实现,是核心程序
- 作用
- 解析
.proto协议文件,校验语法 - 本身不会直接生成 Go 代码
- 通过插件机制,调用外部插件产出对应语言代码
- 解析
- 命令特征:
protoc --go_out=. --go-grpc_out=. acl.proto - 截图版本:
protoc v3.15.8
可以简单理解:protoc 是调度器,不直接生成业务代码,负责调用插件完成代码生成。
2. protoc-gen-go(Go protobuf 消息插件)
仓库地址:https://github.com/protocolbuffers/protobuf-go 模块路径:google.golang.org/protobuf/cmd/protoc-gen-go
- 作用
- 生成
xxx.pb.go文件,包含 message、enum 的 Go 结构体、序列化与反序列化方法 - 只处理数据结构,不生成任何 gRPC service 代码
- 对应截图中
acl.pb.go,注释标注protoc-gen-go v1.23.0
- 生成
- 安装命令
bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest3. protoc-gen-go-grpc(Go gRPC 服务插件)
仓库地址:https://github.com/grpc/grpc-go 模块路径:google.golang.org/grpc/cmd/protoc-gen-go-grpc
- 作用
- 生成
xxx_grpc.pb.go文件,包含服务接口、服务注册方法、客户端调用 stub - 只识别 proto 文件中的
service定义,不处理普通 message - 对应截图中
acl_grpc.pb.go,注释标注protoc-gen-go-grpc v1.1.0
- 生成
- 安装命令
bash
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest💡 注意
特定版本的 protoc-gen-go-grp 需要手动编译!
版本对照 + 生成文件对照表
| 工具 | 产物文件名 | 核心内容 | 仓库 |
|---|---|---|---|
| protoc | - | 解析proto,调度插件 | protocolbuffers/protobuf |
| protoc-gen-go | xxx.pb.go | Message、Enum、序列化逻辑 | golang/protobuf |
| protoc-gen-go-grpc | xxx_grpc.pb.go | Service、Server接口、Client stub | grpc/grpc-go |
历史坑提醒
早期版本,protoc-gen-go 同时生成 pb 和 grpc 代码,一个插件完成两类文件生成。 后续版本做了拆分,必须两个插件分开安装、分开指定输出参数,缺少任意一个插件就会缺失对应代码。 标准写法:--go_out 交给消息插件,--go-grpc_out 交给grpc插件。
最小 proto 示例 acl.proto
protobuf
syntax = "proto3";
package acl;
option go_package = "./acl;acl";
message CheckRequest {
string user_id = 1;
string resource = 2;
}
message CheckResponse {
bool allow = 1;
string reason = 2;
}
service AclService {
rpc Check(CheckRequest) returns (CheckResponse);
}说明:
syntax = "proto3"使用 proto3 语法,是目前主流go_package控制生成代码的包路径,格式输出路径;包名- message 会被 protoc-gen-go 编译进
acl.pb.go - service 会被 protoc-gen-go-grpc 编译进
acl_grpc.pb.go
标准生成命令
bash
protoc --go_out=. --go_opt=paths=source_relative \
--go-grpc_out=. --go-grpc_opt=paths=source_relative \
acl.proto--go_out:指定 protoc-gen-go 的输出--go-grpc_out:指定 protoc-gen-go-grpc 的输出paths=source_relative:以 proto 文件所在目录作为相对路径,日常开发最常用
Makefile 脚本
新建 Makefile,放在 proto 文件同级目录
makefile
# 生成 proto 代码
.PHONY: proto
proto:
protoc --go_out=. --go_opt=paths=source_relative \
--go-grpc_out=. --go-grpc_opt=paths=source_relative \
acl.proto
# 清理生成的代码
.PHONY: clean
clean:
rm -f acl.pb.go acl_grpc.pb.go
# 查看工具版本
.PHONY: version
version:
protoc --version
protoc-gen-go --version
protoc-gen-go-grpc --version使用方式:
bash
# 生成代码
make proto
# 清理生成文件
make clean
# 查看本地三个工具版本
make version查看本机三个工具版本
bash
# 查看protoc编译器版本
protoc --version
# 查看protoc-gen-go版本
protoc-gen-go --version
# 查看protoc-gen-go-grpc版本
protoc-gen-go-grpc --version生成后的 pb.go 文件头部注释,记录了生成时使用的工具版本,用于对齐环境、排查版本兼容问题。
常见误区总结
- 误区1:protoc 可以直接生成Go代码
- 纠正:protoc只是调度器,依靠插件生成Go代码
- 误区2:protoc-gen-go 可以生成gRPC服务代码
- 纠正:拆分之后,它仅负责消息结构,grpc代码单独由 protoc-gen-go-grpc 处理
- 误区3:两个插件版本必须完全一致
- 纠正:不需要版本号一致,只要版本之间兼容即可;生产环境建议固定版本,避免本地和CI产出代码不一致
和截图一一对照
go
// acl.pb.go
// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
// protoc-gen-go v1.23.0
// protoc v3.15.8
// source: acl.protogo
// acl_grpc.pb.go
// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
// versions:
// - protoc-gen-go-grpc v1.1.0
// - protoc v3.15.8
// source: acl.proto两个文件都会记录 protoc 版本,但各自记录自身插件的版本,这就是两个文件头部插件版本不一样的原因。
目录结构参考
.
├── acl.proto
├── acl.pb.go
├── acl_grpc.pb.go
└── Makefile

