.proto文件必须严格满足三行“启动头”：syntax="proto3"独占首行、package定义内部命名空间、option go_package指定Go包路径；字段编号不可复用且需预留扩展空间；service需显式声明，rpc参数/返回值仅限message；生成命令须与go_package路径对齐。
proto 文件不是“写完就能跑”，而是强约束的 ABI 契约，定义错一个字段编号、漏掉 option go_package 或写错 syntax = "proto3"，后续生成代码就直接报错或运行时 panic。
必须写对的三行“启动头”
所有 .proto 文件开头必须严格满足以下三项，缺一不可：
-
syntax = "proto3";—— 必须独占第一行，不能有空格或注释前置；写成proto2会导致零值处理逻辑缺失，解码时可能 panic -
package—— 仅控制 Protobuf 内部命名空间（如跨语言 import），不决定 Go 包路径 -
option go_package = "path;name";—— 这才是 Go 包路径的唯一权威来源：path是生成文件的相对目录（如./user），name是package声明名（如userpb）；省略或格式错误（如写成"userpb"缺少分号前路径）会导致生成文件放错位置、import cycle 或 undefined identifier 错误
message 字段编号不能复用，且要预留扩展空间
Protobuf 序列化靠字段编号（=1, =2）定位数据，不是靠字段名。一旦服务上线，改编号等于破坏 wire 协议兼容性——旧客户端发来的 uid=1 会被新服务当成 name=1 解析，结果错乱。
- 每个
message内字段编号必须唯一，重复会触发 protoc 直接报错：Field number 1 has already been used - 废弃字段不能删编号，应保留并加注释，或用
reserved 3, 5;显式锁定防复用 - 新增字段推荐从
=100起跳，给内部扩展、调试字段或未来版本留出安全空间 - 字段名用
snake_case（如user_id），生成的 Go 字段自动转为UserID；若写成UserID，Go 字段会变成非导出的userid，无法被 gRPC 序列化
service 定义必须显式声明，且 rpc 方法参数/返回值只能是 message
没有 service 块，protoc 就不会生成任何服务端结构体或客户端 stub；gRPC 不识别裸 message，只认 service 下的 rpc 方法。
立即学习“go语言免费学习笔记（深入）”；
-
rpc方法签名必须是rpc MethodName (RequestMsg) returns (ResponseMsg);，不支持基本类型（如string或int32）直传 - 流式类型按需启用：
rpc ListUsers (ListReq) returns (stream User);（服务器流）、rpc Upload(stream Chunk) returns (UploadResp);（客户端流） - service 名称（如
UserService）会映射为 Go 接口名UserServiceServer，实现时必须嵌入UnimplementedUserServiceServer，否则未实现方法调用会返回UNIMPLEMENTED错误
生成代码命令和路径必须与 go_package 对齐
生成命令稍有偏差，就会导致 struct 字段不可导出、缺少 json: tag、或 server 无法识别接口。
- 必须同时指定
--go_out=.和--go-grpc_out=.；若用新版插件（protoc-gen-go-grpc），缺--go-grpc_out就不会生成*_grpc.pb.go - 推荐加上
--go_opt=paths=source_relative和--go-grpc_opt=paths=source_relative，确保生成路径相对于 proto 文件位置，与go_package中的path部分一致 - 生成后检查两个文件：
xxx.pb.go（含 message 结构和序列化逻辑）、xxx_grpc.pb.go（含RegisterXXXServer和 client stub）；若后者缺失，大概率是service块没写或 protoc 参数漏了--go-grpc_out
最常被忽略的其实是 go_package 的路径部分和生成命令中 paths=source_relative 的配合——它决定了 .pb.go 文件到底落在哪一级目录，进而影响整个模块的 import 路径和 go mod 解析。这个细节在本地开发可能不暴露问题，但一旦进 CI 或跨团队协作，就会卡在编译失败或 “undefined: xxx” 上。
