protobuf字段名必须用snake_case（如user_id），否则grpc跨语言序列化失败；go生成器默认转camelcase导出，但wire格式仍用原始名；需用(json_name)选项兼容camelcase；grpc超时需综合考虑链路各环节而非仅context.withtimeout。
Protobuf定义里字段命名用snake_case还是camelCase
Go的protobuf生成器（protoc-gen-go）默认把snake_case字段名转成CamelCase导出字段，但前提是.proto文件里**必须用snake_case**。如果手误写成userName，生成的Go结构体里会变成UserName（符合Go导出规则），但gRPC wire格式仍按原始名字序列化——这会导致其他语言客户端解析失败。
常见错误现象：grpc: failed to unmarshal the message 或 Go服务收不到字段值，而Python/Java客户端日志显示“unknown field 'userName'”。
- 所有
.proto字段名统一用snake_case（如user_id、created_at） - 在
go.mod中锁定google.golang.org/protobufv1.30+，避免旧版对oneof字段生成不一致 - 若需兼容已有
camelCase字段名，加(json_name)选项：string user_name = 1 [(json_name) = "userName"];
GRPC服务端超时控制不能只靠context.WithTimeout
在云原生环境里，单靠context.WithTimeout包住handler逻辑，解决不了长连接空闲断连、TLS握手延迟、LB健康检查超时等链路问题。Kubernetes Service的externalTrafficPolicy: Cluster模式下，kube-proxy可能引入额外毫秒级延迟；Istio sidecar默认HTTP/2流空闲60秒关闭，但gRPC stream可能卡在半开状态。
使用场景：服务间调用耗时波动大（如依赖下游DB或缓存），且SLA要求P99
立即学习“go语言免费学习笔记（深入）”；
- 服务端必须同时配置
grpc.KeepaliveParams：设置Time: 30s、Timeout: 5s，防止连接僵死 - 客户端发起调用前，用
context.WithTimeout(ctx, 800*time.Millisecond)，比SLA留20%余量 - 在K8s Deployment中加readinessProbe：
exec: ["grpc_health_probe", "-addr=:8080"]，避免流量打到未就绪实例
Go struct嵌套Proto消息时别直接用*pb.XXX当字段类型
Protobuf生成的Go结构体（如*pb.User）是纯数据载体，没有方法、无并发安全保证，也不支持JSON标签透传。如果在业务层定义type UserWrapper struct { Data *pb.User `json:"user"` }，再用json.Marshal序列化，会丢失pb.User内部的XXX_字段和UnmarshalJSON行为，导致前端收到空对象。
性能影响：每次访问UserWrapper.Data.Name都要做nil检查；若Data为nil，panic风险高。
- 业务层应封装为独立struct，显式复制字段：
type UserDTO struct { ID string; Name string }，用copier.Copy(&dto, pbUser)或手动赋值 - 需要JSON兼容时，在
.proto里加option go_tag = "json:\"user,omitempty\"";，而非依赖外部struct tag - 禁止在HTTP handler里直接返回
*pb.XXX指针——它不是标准Go API响应体设计意图
云内gRPC调用失败时，错误码别全转成codes.Internal
很多团队习惯在中间件里把所有error统一转成status.Errorf(codes.Internal, "xxx")，结果监控系统看到全是500，根本分不清是下游超时、权限不足还是参数校验失败。Prometheus指标grpc_server_handled_total{grpc_code="Internal"}暴涨，却无法定位真实瓶颈。
容易踩的坑：用errors.Is(err, context.DeadlineExceeded)判断超时后，仍返回codes.Internal；或调用pb.Validate()失败后没映射到codes.InvalidArgument。
- 网络类错误（
context.DeadlineExceeded、net.OpError）→codes.Unavailable - 参数校验失败（
validate.Error）→codes.InvalidArgument - 权限不足（
auth.ErrPermissionDenied）→codes.PermissionDenied - 自定义错误必须实现
GRPCStatus() *status.Status方法，否则status.Convert(err)拿不到正确code
云环境里，错误码是服务拓扑里唯一能跨进程传递的语义信息。少一个codes.NotFound，链路追踪里就多一次人工翻日志。
