syntax = "proto3";、option go_package 和字段编号是 Protobuf 编译期强制契约：前者必须独占首行且不可省略或错写，go_package 决定 Go 包路径和生成位置，字段编号一旦发布不可变更，否则导致 wire 不兼容与解码错位。
proto3 语法是硬门槛，不是可选项
不写 syntax = "proto3"; 或写成 syntax = "proto2";，后续所有生成和通信都会出问题——不是报错就是静默错乱。Protobuf 官方早已弃用 proto2 的 required/optional 语义，gRPC Go 实现也只认 proto3 的 wire 格式。
- 必须独占第一行，且不能带空格或注释：
syntax = "proto3"; - proto2 文件混入项目（尤其被 import）会导致
protoc解析失败或生成代码缺失零值处理逻辑，运行时可能 panic - 字段默认“无 presence”，
string name = 1;解析到空字符串就是""，不是nil；如需区分“未传”和“传了空串”，得用google.protobuf.StringValue
go_package 不是 package，它决定生成路径和导入名
package user; 只影响 Protobuf 命名空间（比如跨语言引用时的全限定名），真正控制 Go 包路径、go mod 识别、以及 protoc-gen-go 输出位置的，只有 option go_package。
- 格式必须是
option go_package = "./user;userpb";：分号前是输出子目录（相对当前protoc工作路径），分号后才是生成文件顶部的package userpb - 漏写或写成
option go_package = "userpb";（缺路径），生成的.pb.go会落到当前目录，极易引发 import cycle 或undefined: xxx - 多个 proto 文件若共用同一
go_package路径，会生成同名文件冲突；不同服务建议按目录隔离，例如./auth;authpb和./user;userpb
字段编号不是序号，是序列化协议的 ABI 键
Protobuf 不靠字段名、而靠编号（=1, =2）在二进制里定位数据。一旦上线，改编号 = 破坏 wire 兼容性 —— 旧客户端发的 uid=1，新服务会当成 name=1 解析，字段直接错位。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 每个
message内编号必须唯一，重复会触发Field number X has already been used - 删除字段后，编号绝不能复用；应加
reserved 3, 5;或reserved "old_field";锁死 - 新增字段推荐从
100起跳，为未来扩展留空间，避免和早期字段冲突
service 方法类型要匹配真实通信模式，别全写 unary
gRPC 支持四种调用模式：unary（一来一回）、server streaming（一请求多响应）、client streaming（多请求一响应）、bidi streaming（双向多消息）。硬套 rpc GetX(Req) returns (Resp)，等真要流式传输日志或实时状态时，就得重写接口、客户端和服务端全量升级。
立即学习“go语言免费学习笔记（深入）”；
- 查列表用服务器流：
rpc ListUsers(ListUsersRequest) returns (stream User); - 上传大文件用客户端流：
rpc UploadFile(stream FileChunk) returns (UploadResponse); - 实时协作场景用双向流：
rpc SyncEvents(stream Event) returns (stream EventAck); - 流式方法一旦定义，客户端必须用对应 stream 类型调用，否则连接直接断开或收不到数据
go_package、syntax 这三样，不是“写完能跑就行”的配置项，而是编译期就卡死的契约锚点。错一个，轻则包路径混乱、字段解码错位，重则上下游服务彻底失联——它们没在运行时报错，是因为根本没机会运行。 
