详解 Protobuf 编译工具 protoc：从基础到实战应用

原创于 2025-07-29 00:54:33 发布 · 696 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#go

golang 专栏收录该内容

323 篇文章

订阅专栏

详解 Protobuf 编译工具 protoc：从基础到实战应用

1. 依赖找不到：File not found

2. 选项不识别：Option "(validate.rules)" unknown

3. 路径分隔符问题（Windows 环境）

四、进阶：用 buf 简化依赖管理

五、总结

在云原生和微服务架构盛行的当下，高效的接口定义与数据序列化方案至关重要。Protobuf（Protocol Buffers）凭借其高效性与跨语言特性，成为众多项目的首选，而 protoc 作为 Protobuf 的核心编译工具，是实现 .proto 文件向多语言代码转换的关键。本文将从基础概念讲起，结合实战案例，带你全面掌握 protoc 的使用。

一、`protoc` 是什么？

protoc 是 Protobuf 官方提供的命令行编译工具，作用是将 .proto 文件（定义了接口、消息结构的 IDL 文件）编译为 目标编程语言（如 Go、Java、Python 等）的代码，让不同语言的服务能基于统一的 Protobuf 定义进行交互。

核心能力：

解析 .proto 文件的语法和结构。
调用对应语言的代码生成插件（如 protoc-gen-go），输出可直接使用的代码。
支持扩展依赖（如引入 googleapis、protovalidate 等公共 .proto 库）。

二、`protoc` 基础使用流程

1. 安装 `protoc`

通用方式：从 Protobuf 官方 releases 下载对应系统的二进制包，解压后将 protoc 可执行文件加入系统 PATH。

Go 生态（可选）：通过 go install 安装辅助插件（如 protoc-gen-go）：

bash

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

2. 编写 `.proto` 文件

示例 api_gateway.proto：

syntax = "proto3";
package bilibili.api.gateway.v1;

import "google/protobuf/duration.proto";
import "proto/protovalidate/buf/validate/validate.proto"; // 自定义校验依赖

option go_package = "github.com/bilibili/api-gateway/internal/api;api";

message UserRequest {
  string user_id = 1 [(validate.rules).string.min_len = 1]; // 校验规则
  google.protobuf.Duration timeout = 2;
}

service ApiGateway {
  rpc GetUser(UserRequest) returns (UserResponse);
}

3. 基础编译命令

最简化的 protoc 命令结构：

protoc \
  -I 依赖路径1 \
  -I 依赖路径2 \
  --语言_out=输出目录 \
  你的.proto文件

实战示例（生成 Go 代码）：

protoc \
  -I . \ # 当前目录（项目根，找自己的.proto文件）
  -I D:/A_software/go1.24.5/workspace/pkg/mod/googleapis \ # 引入googleapis公共依赖
  -I D:/A_software/go1.24.5/workspace/src/protovalidate \ # 引入protovalidate校验依赖
  --go_out=./pb \ # 生成Go结构体代码
  --go-grpc_out=./pb \ # 生成gRPC服务代码（若有service定义）
  --validate_out="lang=go:./pb" \ # 生成校验逻辑代码（protovalidate插件）
  bilibili/api/gateway/v1/api_gateway.proto

三、实战痛点与解决方案

1. 依赖找不到：`File not found`

现象：编译时报 google/api/annotations.proto: File not found 或自定义依赖找不到。
原因：-I 参数未正确映射依赖路径。
解决：

公共依赖（如 googleapis）：通过 -I 指向其本地路径（或使用 buf 管理依赖）。
自定义依赖：确保 -I 包含依赖的根目录，如 protovalidate 需指向 src/protovalidate，让 import "proto/protovalidate/..." 能被解析。

2. 选项不识别：`Option "(validate.rules)" unknown`

现象：使用 protovalidate 校验规则时，protoc 无法识别 (validate.rules)。
原因：

validate.proto 未正确导入，或文件内容缺失扩展定义。
未安装 protoc-gen-validate 插件。
解决：

确保 .proto 中正确导入 validate.proto：

import "proto/protovalidate/buf/validate/validate.proto";

安装插件并在命令中启用：

go install github.com/bufbuild/protoc-gen-validate@latest

验证 validate.proto 内容，确保包含：

extend google.protobuf.FieldOptions {
  ValidationRule rules = 1047;
}

3. 路径分隔符问题（Windows 环境）

现象：在 Windows 的 cmd/PowerShell 中，路径用 / 可能导致找不到文件。
解决：统一使用反斜杠 \（或保持 / 但用引号包裹路径），示例：

protoc -I . -I D:\A_software\go1.24.5\workspace\pkg\mod\googleapis ...

四、进阶：用 `buf` 简化依赖管理

若手动管理 -I 路径繁琐，推荐用 buf 工具自动化处理：

安装 buf：

go install github.com/bufbuild/buf/cmd/buf@latest

编写 buf.yaml 管理依赖：

version: v1
name: buf.build/your-project
deps:
  - buf.build/googleapis/googleapis # 自动拉取googleapis依赖
  - buf.build/bufbuild/protovalidate # 自动拉取protovalidate依赖
build:
  roots:
    - proto # .proto文件目录

一键编译：

buf generate --template buf.gen.yaml

配合 buf.gen.yaml 定义生成规则：

version: v1
plugins:
  - name: go
    out: pb
    opt: paths=source_relative
  - name: go-grpc
    out: pb
    opt: paths=source_relative
  - name: validate
    out: pb
    opt: lang=go