English
Protobuf Go Tool Differences: Detailed Explanation of protoc / protoc-gen-go / protoc-gen-go-grpc | Pitfalls in Go gRPC Code Generation

Companion screenshot version:
- 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)
One-sentence overview
Many people confuse these three; the root cause is that protoc is the compiler itself, while the other two are independent plugins with different responsibilities and generate code separately.
protoc: protobuf compiler, responsible for parsing.protoFile, scheduling pluginprotoc-gen-go: Generate message structure, correspondingxxx.pb.goprotoc-gen-go-grpc: Generate gRPC service, client stub, corresponding toxxx_grpc.pb.go
Looking at the screenshot confirms: acl.pb.go File header annotation Code generated by protoc-gen-goacl_grpc.pb.go File header annotation Code generated by protoc-gen-go-grpc
Project Address & Detailed Explanation of Purpose
1. protoc (Protocol Buffers compiler)
Warehouse address:https://github.com/protocolbuffers/protobuf
Official repository, C++ implementation, is the core program
Effect
Parse
.protoProtocol file, validate syntaxIt does not directly generate Go code by itself
Through the plugin mechanism, external plugins are invoked to generate code in the corresponding language.
Command characteristics:
protoc --go_out=. --go-grpc_out=. acl.protoScreenshot version:
protoc v3.15.8
You can simply understand it as: protoc is a scheduler; it does not directly generate business code, but is responsible for calling plugins to complete code generation.
2. protoc-gen-go (Go protobuf message plugin)
Repository address:https://github.com/golang/protobuf Module path:google.golang.org/protobuf/cmd/protoc-gen-go
Effect
Generate
xxx.pb.goFile containing Go structs for message and enum, and serialization and deserialization methodsOnly process data structures, do not generate any gRPC service code.
In the corresponding screenshot
acl.pb.go, annotation labelingprotoc-gen-go v1.23.0Installation command
bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest3. protoc-gen-go-grpc (Go gRPC service plugin)
Warehouse address:https://github.com/grpc/grpc-go Module path:google.golang.org/grpc/cmd/protoc-gen-go-grpc
Effect
Generate
xxx_grpc.pb.goFile containing service interfaces, service registration methods, and client invocation stubsOnly recognize in proto files
serviceDefinition, does not process ordinary messagesIn the corresponding screenshot
acl_grpc.pb.go, annotation labelingprotoc-gen-go-grpc v1.1.0Installation command
bash
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest💡 Note
Certain versions of protoc-gen-go-grp need to be compiled manually!
Version comparison + Generated file comparison table
| Tool | Product file name | Core content | Warehouse |
|---|---|---|---|
| protoc | - | Parse proto, scheduling plugin | protocolbuffers/protobuf |
| protoc-gen-go | xxx.pb.go | Message, Enum, serialization logic | golang/protobuf |
| protoc-gen-go-grpc | xxx_grpc.pb.go | Service, Server interface, Client stub | grpc/grpc-go |
Legacy pitfall reminder
In earlier versions, protoc-gen-go generated both pb and grpc code simultaneously, with a single plugin handling the generation of both types of files. Later versions split it, so the two plugins must be installed separately and their output parameters specified separately; if either plugin is missing, the corresponding code will be missing. Standard notation:--go_out Hand it over to the message plugin,--go-grpc_out Hand it over to the grpc plugin.
Minimal proto example 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);
}Description:
syntax = "proto3"Using proto3 syntax is currently mainstream.go_packageControl the package path of the generated code, format输出路径;包名message will be compiled into by protoc-gen-go
acl.pb.goservice will be compiled into by protoc-gen-go-grpc
acl_grpc.pb.go
Standard generation command
bash
protoc --go_out=. --go_opt=paths=source_relative \
--go-grpc_out=. --go-grpc_opt=paths=source_relative \
acl.proto--go_out: Specify the output of protoc-gen-go--go-grpc_out: Specify the output of protoc-gen-go-grpcpaths=source_relativeUsing the directory containing the proto file as the relative path is most commonly used in daily development.
Makefile script
New Makefile, placed in the same directory as the proto file
makefile
# Generate proto code
.PHONY: proto
proto:
protoc --go_out=. --go_opt=paths=source_relative \
--go-grpc_out=. --go-grpc_opt=paths=source_relative \
acl.proto
# Clean up the generated code
.PHONY: clean
clean:
rm -f acl.pb.go acl_grpc.pb.go
# View tool version
.PHONY: version
version:
protoc --version
protoc-gen-go --version
protoc-gen-go-grpc --versionUsage:
bash
# Generate code
make proto
# Clean generated files
make clean
# Check the versions of the three local tools
make versionCheck the versions of the three tools on this machine
bash
# Check the protoc compiler version
protoc --version
# Check the protoc-gen-go version
protoc-gen-go --version
# Check the protoc-gen-go-grpc version
protoc-gen-go-grpc --versionThe header comment of the generated pb.go file records the tool version used during generation, for aligning environments and troubleshooting version compatibility issues.
Summary of Common Misconceptions
Misconception 1: protoc can directly generate Go code
Correction: protoc is just a dispatcher and relies on plugins to generate Go code
Misconception 2: protoc-gen-go can generate gRPC service code
Correction: after the split, it is only responsible for message structures, and the gRPC code is handled separately by protoc-gen-go-grpc.
Misconception 3: The two plugin versions must be exactly the same.
Correction: version numbers do not need to match; they only need to be compatible across versions. For production, it is recommended to pin versions to avoid inconsistent code produced locally and in CI.
Compare one by one against the screenshot
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.protoBoth files record the protoc version, but each records the version of its own plugin, which is why the plugin versions in the headers of the two files are different.
Directory structure reference
.
├── acl.proto
├── acl.pb.go
├── acl_grpc.pb.go
└── Makefile
