Skip to content

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

Protobuf Go 三剑客彻底分清示意图

配套截图版本:

一句话总览 ​

很多人混淆这三者,根源在于:protoc 是编译器本体,另外两个是独立插件,分工不同,分开生成代码。

  • protoc:protobuf 编译器,负责解析 .proto 文件,调度插件
  • protoc-gen-go:生成消息结构体,对应 xxx.pb.go
  • protoc-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++ 实现,是核心程序
  • 作用
    1. 解析 .proto 协议文件,校验语法
    2. 本身不会直接生成 Go 代码
    3. 通过插件机制,调用外部插件产出对应语言代码
  • 命令特征: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

  • 作用
    1. 生成 xxx.pb.go 文件,包含 message、enum 的 Go 结构体、序列化与反序列化方法
    2. 只处理数据结构,不生成任何 gRPC service 代码
    3. 对应截图中 acl.pb.go,注释标注 protoc-gen-go v1.23.0
  • 安装命令
bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

3. protoc-gen-go-grpc(Go gRPC 服务插件) ​

仓库地址:https://github.com/grpc/grpc-go 模块路径:google.golang.org/grpc/cmd/protoc-gen-go-grpc

  • 作用
    1. 生成 xxx_grpc.pb.go 文件,包含服务接口、服务注册方法、客户端调用 stub
    2. 只识别 proto 文件中的 service 定义,不处理普通 message
    3. 对应截图中 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-goxxx.pb.goMessage、Enum、序列化逻辑golang/protobuf
protoc-gen-go-grpcxxx_grpc.pb.goService、Server接口、Client stubgrpc/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.proto
go
// 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
最后更新2026/11/18 12:10
如果你觉得这篇文章有帮助,或者想聊聊技术、工作,欢迎通过下面方式联系我:
contact fishfinal
京ICP备2024063630号-1