proto文件第一行必须是syntax = "proto3";，且独占一行位于最顶部；go_package决定Go包路径而非package；字段编号不可复用，废弃需reserved；service必须显式定义，rpc参数返回值只能是message。

proto文件第一行必须是syntax = "proto3";

不是可选项，是强制语法声明。漏写、写成syntax = "proto2";或放在第二行，protoc可能静默降级或报错，但生成的 Go 代码会缺失零值语义处理——比如 string 字段本该是 ""，却变成 nil 引发 panic。

• 必须独占一行，且位于文件最顶部
• proto2 和 proto3 不兼容，尤其在 required/optional 语义和默认值行为上，混用会导致跨语言对接失败
• 所有字段默认可选（no presence），如需区分“未设置”和“设为空字符串”，得用 google.protobuf.StringValue 这类 wrapper 类型

option go_package 才决定 Go 包路径，package 只管 Protobuf 命名空间

很多人改了 package user; 就以为生成代码会进 user 包，结果 go build 报 undefined: GetUserRequest 或 import cycle——真正起作用的是 option go_package。

• 格式必须为 option go_package = "路径;包名";，例如 option go_package = "github.com/yourorg/api/pb;pb";
• 路径部分控制 .pb.go 输出位置（相对于 protoc 当前目录），包名部分才是文件顶部的 package pb
• 省略路径（如只写 option go_package = "pb";）会导致文件生成到当前目录，极易污染项目结构

字段编号不能复用，废弃字段要 reserved

Protobuf 序列化靠编号定位数据，不是字段名。线上服务一旦发布，改编号等于破坏 wire 协议：旧客户端发的 uid=1，新服务按 name=1 解析，数据全乱。

Evez Github Manager

在 OpenClaw 中管理 GitHub 仓库、Pull Request、Issue 与工作流。适用于审查 PR、管理 Issue、自动化 GitHub Actions、同步仓库等场景。

下载

• 每个 message 内编号必须唯一，重复会直接被 protoc 拒绝：Field number 1 has already been used
• 删除字段后，原编号必须保留并加注释，或用 reserved 3, 5; 或 reserved "old_field"; 显式锁定
• 新增字段推荐从 =100 起跳，给内部扩展、监控字段、预留字段留出安全空间

service 必须显式定义，rpc 方法参数返回值只能是 message

没写 service 块，protoc 就不会生成 *_grpc.pb.go 中的服务接口和注册函数，RegisterUserServiceServer 根本不存在，启动服务后调用必报 UNIMPLEMENTED。

立即学习“go语言免费学习笔记（深入）”；

• rpc 方法签名里，请求和响应类型必须是已定义的 message，不能是 string、int32 等基础类型
• 流式场景别硬套 unary：需要服务器推多条数据，就该写 rpc ListUsers(...) returns (stream User);，否则后期改接口要重写客户端逻辑
• 方法名和 service 名会直接映射为 Go 接口名（如 UserServiceServer），大小写、拼写必须和生成代码完全一致，否则 RegisterXXXServer 找不到目标

字段编号、go_package、syntax 这三处看似简单，却是 gRPC 编译期卡死最常见的源头——它们不报运行时错误，而是一上来就让 protoc 失败、go build 找不到符号、客户端连通却调不通。写完 proto，先检查这三处，比写完再调试快十倍。