protoc 生成的 Go 类型不能直接用作 HTTP 响应结构体，因其字段无 json tag、零值语义与 JSON 不一致、指针字段缺失；根本原因是 proto3 语法、命名规则与 protoc-gen-go 插件约定未对齐，需严格遵守 syntax="proto3"、字段小写下划线、go_package 完整路径等规范，并正确配置 protoc 参数及 JSON 序列化方式。
protoc 生成的 Go 类型不能直接当 HTTP 响应结构体用，字段没 json tag、零值语义和 JSON 不一致、指针字段缺失——这不是配置问题，是设计前提没对齐。
proto3 语法和命名规则必须严格遵守
Go 的 protoc-gen-go 插件对 proto 文件有硬性约定：不满足就生成不可导出字段或错乱的 JSON 映射。
常见错误是字段名用了 PascalCase 或混用 optional（proto3 默认所有字段可选，加 optional 反而需要额外插件支持）。
必须做到：
- syntax = "proto3" 开头，不用 proto2
- message 名用 PascalCase（如 UserProfile）
- 字段名全小写 + 下划线（如 user_id），否则生成的 Go 字段名变成 UserId 但未导出
- 避免嵌套 message，提至 package 级，否则生成 UserProfile_UserSetting 这类非标准类型
- go_package 必须是完整 import path，例如 option go_package = "github.com/yourorg/userapi/pb";
protoc 命令参数顺序和路径不能错
protoc 报 “plugin not found” 或生成文件里 import 路径错，90% 是参数顺序或路径配置偏差。
它不自动查 $PATH，也不默认识别 $GOPATH/bin，必须显式对齐。
推荐写法：
- 先确认 protoc-gen-go 在 $PATH 中（运行 which protoc-gen-go）
- 使用 --go_out=. 而不是 --go_out=:（末尾冒号是旧版语法，新版会报错）
- 总带上 --go_opt=paths=source_relative 和 --go-grpc_opt=paths=source_relative，避免生成路径跳转错乱
- 若项目用 Go modules，加 --go_opt=module=github.com/yourorg/userapi，否则生成代码 import 的模块名可能和 go.mod 不一致
- 输出目录必须提前存在，protoc 不自动创建父级路径
生成的 *pb.User 不能直接进 HTTP handler
生成的 struct 字段默认没有 json tag，且所有字段是值类型（string、int32），没有 nil 概念。HTTP 返回时字段全为空字符串或 0，不是“未设置”，而是“设成了零值”。
两种安全做法：
- 用 google.golang.org/protobuf/encoding/protojson 替代 json.Marshal，它按 proto 规则处理字段存在性（需配 protojson.MarshalOptions{EmitUnpopulated: true} 控制是否输出零值）
- 若必须用原生 json 包，手动给 struct 加 json tag（不推荐改生成文件，应在 .proto 里用 json_name 选项，如 string user_id = 1 [json_name = "user_id"];）
- 要表达“未设置”，必须用 wrapper 类型，如 google.protobuf.StringValue，而不是原生 string
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
gRPC server 注册失败常因接口签名不匹配
生成的 pb.UnimplementedUserServiceServer 是桩接口，你实现的服务 struct 必须完全遵循其方法签名——参数必须是 *pb.GetUserRequest，不能改成 pb.GetUserRequest（值类型）或自定义 struct；返回必须是 *pb.GetUserResponse, error，不能少 error。
容易忽略的点：
- 方法名首字母大写，但 proto 里定义的是小写（如 get_user），生成后变成 GetUser，别手写成 getUser
- 所有请求/响应参数必须是指针类型，proto 生成的 struct 本身已是 pointer-friendly，但你不该再包一层指针
- 如果用了 streaming，ServerStreaming 方法第二个参数是 pb.UserService_GetUserServer，不是 grpc.ServerStream
真正卡住人的从来不是“怎么写 proto”，而是生成后类型和 runtime 行为不一致——比如 HTTP 返回空对象、gRPC 调用 panic、字段莫名丢失。这些几乎都源于 go_package 路径、protoc 参数、JSON 序列化方式这三处没对齐。
