Protobuf字段编号不可更改，否则导致跨语言解析错乱；必须用1–15编号高频字段以节省编码空间；废弃字段需用reserved显式保留；go_package须与go.mod路径一致且格式为"path;name"；新增字段必须用新编号，且需同步所有语言的.proto源文件。
Protobuf 不是用来“学 Go 语法”的，而是用来定义服务契约的——你写对 .proto 文件，生成的 Go 代码才真正可用；否则，哪怕 Go 写得再熟，跨语言调用也会在第一关就失败。
proto3 语法里字段编号不能乱改
字段编号（如 string name = 1; 中的 1）不是序号，是二进制序列化的 key。一旦服务上线，改编号等于破坏 wire format，Python/Java 客户端会静默丢字段或 panic。
- 新增字段必须用新编号，且编号建议 1–15（编码更省字节），高频字段优先分配
- 废弃字段不要删，改用
reserved 3;显式保留，防止后续误复用 -
repeated字段永远保序，但不保证去重；若需唯一性，得在业务层校验
go_package 选项必须显式声明且路径可导入
option go_package 决定生成代码的包路径和 import 路径，不是可选配置。它影响两件事：Go 编译器能否 resolve 包引用、其他语言客户端能否正确映射命名空间。
- 值格式应为
"github.com/yourorg/yourrepo/pb;pb"——分号前是 module 路径（对应go.mod的 module 名），分号后是生成文件的 package 名 - 如果只写
./pb，生成的.pb.go会放在当前目录，但无法被其他模块import；用相对路径还容易因执行protoc位置不同导致生成失败 - Go 模块名（
go.mod第一行）必须与go_package的路径前缀一致，否则go build报cannot find package
gRPC service 生成需两个插件协同：protoc-gen-go + protoc-gen-go-grpc
仅用 protoc-gen-go 只能生成 message 类型，service 接口（含 gRPC server/client stub）必须靠 protoc-gen-go-grpc。缺一个，Go 侧就只有数据结构，没有 RPC 调用能力。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 安装命令要分开执行：
go install google.golang.org/protobuf/cmd/protoc-gen-go@latestgo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest - 生成命令必须同时指定两个输出：
protoc -I=. --go_out=. --go-grpc_out=. user.proto - 若用 Buf 工具，
buf generate配置中也得同时启用plugin: go和plugin: go-grpc，否则生成的*_grpc.pb.go文件为空
跨语言调用失败时，先查 proto 文件是否被多处 copy 修改
这是最隐蔽也最常发生的错误：Python 团队改了 user.proto 加了个字段，但没同步给 Go 后端；Go 用旧版生成代码，客户端发来新字段，Go 服务解析时直接忽略——无报错、无日志、字段丢失。
- 所有语言必须共用同一份
.proto源文件，建议放入独立 Git 仓库（如api-specs），通过 submodule 或 vendor 管理 - 禁止在各语言项目里各自维护一份副本；哪怕只是改个注释，也要走统一 PR 流程
- CI 中加入
buf check breaking，自动检测是否引入不兼容变更（如删除字段、改类型）
真正卡住人的从来不是 Go 语法或 gRPC 启动逻辑，而是某次提交里悄悄改掉的一个字段编号，或者 go_package 路径里少了一个斜杠。协议即契约，契约一旦松动，跨语言就只剩沉默的失败。
