Go生成代码需显式启用experimental_allow_proto3_optional，访问optional字段用GetValue()；gRPC服务需HTTP/2支持，禁用curl直连；超时错误须用status.Convert解包；Protobuf解包必须用proto.Unmarshal，修改proto后务必重新生成代码。
proto文件里message字段加了optional，Go生成代码报错
Go 1.21+ 默认启用 protoc-gen-go v1.32+，而新版 protoc 插件已弃用 optional 字段的隐式支持——除非显式启用 experimental_allow_proto3_optional。不加这个参数，protoc 会直接报错：Field 'xxx' is optional but proto3 does not support optional fields。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
protoc命令中加入--go_opt=paths=source_relative --go-grpc_opt=paths=source_relative同时，必须加--proto_path=.和--experimental_allow_proto3_optional - 如果你用的是
buf，需在buf.gen.yaml的plugins下为go和go-grpc都配置opt: ["paths=source_relative", "experimental_allow_proto3_optional"] - Go 代码里访问
optional字段不再是req.GetName()，而是req.GetName().GetValue()或先判空：if req.GetName() != nil { ... }
gRPC Server启动后立刻panic：“transport: http2Server.HandleStreams failed to read frame”
这不是 gRPC 服务本身写错了，而是客户端发来的不是合法 HTTP/2 流量——常见于用 curl 直接调 http://localhost:8080/YourService/YourMethod，或浏览器直接访问服务地址。gRPC 不是 REST，它依赖 HTTP/2 + Protocol Buffers 编码，裸 HTTP 请求会被底层 http2.Server 拒绝并 panic。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 调试阶段优先用
grpcurl：grpcurl -plaintext localhost:8080 list，确认服务可发现 - 确保 server.Listen 使用
net.Listen("tcp", ":8080")，且grpc.NewServer()未误传grpc.Creds(credentials.NewTLS(...))（本地开发没配 TLS 就别传） - 如果用 Nginx 或 Envoy 做反向代理，必须开启 HTTP/2 支持，并透传
Upgrade和Connection头；否则流量降级成 HTTP/1.1，server 直接丢弃
Client端调用超时但没返回error，ctx.Done() 触发却拿不到具体原因
gRPC 的超时控制完全依赖 context，但默认情况下，超时仅触发 context.DeadlineExceeded，不会附带 gRPC 层错误码（如 codes.DeadlineExceeded），导致上层难区分是网络断开、服务未响应，还是单纯慢。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 永远用
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)，而不是直接传context.Background() - 检查 error 时，先用
status.Convert(err)解包：s := status.Convert(err); if s.Code() == codes.DeadlineExceeded { ... } - 避免在 client.Dial 时设全局
WithTimeout，应只在每次Invoke或NewStream时传 context——否则一次超时会影响后续所有调用 - 如果服务端也做了 deadline 传递，记得在 server 端用
runtime.ServerMetadataFromContext(ctx)提取客户端传来的 timeout 值（需配合 grpc-gateway 或自定义 interceptor）
Protobuf嵌套message在Go里解包后字段全零值，但wire上数据明明存在
典型症状：Wireshark 抓包看到 payload 有完整二进制数据，Go struct 打印出来却是 &{Name:\"\" Age:0}。根本原因是 protobuf 的 field presence 规则和 Go struct tag 不匹配，尤其当 proto 中字段是 sint32、bytes 或嵌套 message 但未设 optional 时，生成的 Go struct 字段类型是指针（如 *string），但你用了 json.Unmarshal 或手动赋值，绕过了 proto 的反序列逻辑。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 绝不手动 new struct 并赋值；一律用
proto.Unmarshal(data, &msg)解析原始字节 - 嵌套 message 字段非
optional时，生成代码中该字段是值类型（如Child ChildMsg），但其内部字段仍可能是指针——所以打印msg.Child.Name前，先确认msg.Child.Name != nil - 若需 JSON 互通，用
jsonpb.Marshaler{EmitDefaults: true}（旧版）或protojson.MarshalOptions{UseProtoNames: true, EmitUnpopulated: true}（新版），否则默认跳过 zero value 字段
最易被忽略的一点：proto 文件修改后，必须重新生成 Go 代码并 rebuild，哪怕只改了一个字段注释——缓存的 .pb.go 文件和实际 wire 格式对不上，解包就会静默失败。
