proto3声明必须位于文件首行且无BOM/空格，go_package路径决定import路径须与go.mod一致，字段编号不可复用并禁用19000–19999，流式RPC必须显式使用stream关键字。
proto3 版本声明必须写在第一行
不加 syntax = "proto3";，或者写在注释/空行之后，protoc 会默认按 proto2 解析，导致生成的 Go 代码字段行为异常（比如缺失零值、指针包装错误），尤其在跨语言调用时直接报 invalid wire type。
- 必须严格放在文件最开头，前面不能有任何内容（包括 UTF-8 BOM 或空格）
- 别写成
syntax = 'proto3';（单引号不合法）或syntax="proto3"（缺分号） - 所有团队成员的 proto 文件必须统一用 proto3，混用 proto2 和 proto3 在同一服务中等于埋雷
go_package 路径决定 import 路径，不是 package 名
go_package 是生成 Go 代码时真正的导入路径，和 package 声明无关。写错会导致编译报 cannot find package，哪怕文件结构看着没问题。
- 正确写法：
option go_package = "github.com/yourorg/yourproject/proto"; - 生成的
user.pb.go顶部会是package proto，但你 import 时必须用github.com/yourorg/yourproject/proto - 如果项目用了 Go Module，
go_package必须和go.mod的 module 名前缀一致，否则go build找不到包
字段编号不能复用，删除字段要留空并加注释
字段编号是二进制协议里的“列索引”，客户端和服务端靠它匹配字段。复用旧编号（比如把已删的 email = 3 改成 phone = 3）会导致老客户端把新字段当 email 解析，数据错乱且难以排查。
- 已废弃字段应保留编号 + 注释，例如：
string email = 3 [deprecated=true]; // DO NOT REUSE - 新增字段从当前最大编号 +1 开始，不要跳号（除非明确为未来扩展预留）
- 避免用 19000–19999 这段编号——这是 Protocol Buffers 保留区间，
protoc会直接报错
流式 RPC 的返回类型必须显式带 stream 关键字
写成 rpc ListUsers(ListUsersRequest) returns (User); 看似能编译，但实际是普通 RPC，只返回一个 User；想实现服务端流，必须写 returns (stream User)，否则客户端收不到多条响应。
立即学习“go语言免费学习笔记（深入）”；
- 四种模式对应的关键字组合：普通（无
stream）、服务端流（stream在 response）、客户端流（stream在 request）、双向流（request 和 response 都有stream） - 流式方法生成的 Go 接口签名完全不同，比如服务端流会生成
SendAndClose或Send方法，不是简单返回 struct - 别在流式 RPC 里混用
google.api.http扩展——HTTP/1.1 不支持原生流，gRPC-Gateway 会降级为分页，行为不一致
go_package 路径、stream 关键字这三处，改错一次可能要上下游全量回归测试——它们不是“写完能跑”就完事的语法点，而是运行时契约的硬边界。 
