protoc-gen-go-http 生成的 HTTP handler 返回 404 是因默认仅支持严格匹配 proto 中 google.api.http option 定义的 GET/POST 路径，需检查是否漏写或写错 option、package 与 go_package 一致、BasePath 配置正确，并避免浏览器直接访问导致方法不匹配。

protoc-gen-go-http 生成的 HTTP handler 为什么总返回 404？

不是路由没注册，而是 protoc-gen-go-http 默认只生成基于 GET 和 POST 的 handler，且要求路径必须严格匹配 proto 中定义的 google.api.http option。常见错误是漏写或写错 option 值。

• 检查 proto 文件里是否为每个 rpc 方法都加了 option (google.api.http) = { ... };，比如 get: "/v1/environments" 或 post: "/v1/environments"
• 确保 package 和 go_package 路径一致，否则生成的 handler 注册时会找不到对应 service 实例
• kratos run 启动后，用 curl -I http://localhost:8000/v1/environments 测试，别直接浏览器访问——浏览器默认发 GET，但若你只定义了 post 就必然 404
• 如果用了自定义路径前缀（如 /api），必须在 http.Server 初始化时显式设置 BasePath: "/api"，否则生成的路由不会自动拼接

proto 验证规则（validate）不生效？

protoc-gen-validate 生成的校验代码默认只在 Unmarshal 或手动调用 Validate() 时触发，Kratos 的 HTTP middleware 不会自动调用它——这是最常被忽略的一环。

• 必须在 transport/http/handler.go 中显式插入验证逻辑，例如：if err := req.Validate(); err != nil { return nil, errors.BadRequest("VALIDATE", err.Error()) }
• 注意字段 tag 冲突：如果你同时用了 binding:"required"（gin 风格）和 validate:"required"（proto validate），后者会被忽略
• 嵌套 message 的验证需要递归启用，validate="true" 只作用于当前层；深层字段需单独加 validate:"required"
• 数值范围校验（如 int32 value = 1 [(validate.rules).int32 = {gt: 0, lte: 100}];）在生成代码中会转成 value > 0 && value ，但不会做类型转换——传字符串会 panic

错误码映射混乱：grpc error 和 http status 怎么对齐？

Kratos 默认把所有 errors.New 或 errors.Wrap 的错误都转成 HTTP 500，除非你用 errors.BadRequest、errors.Unauthorized 等语义化构造函数，且配合 protoc-gen-go-errors 插件生成的错误码表。

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

• 不要直接用 http.Error(w, msg, 400) ——这绕过了 Kratos 的错误中间件，OpenAPI 文档里也不会体现
• 定义错误时优先复用 errors 包的预设类型：errors.NotFound("env %s not found", id) → 自动映射到 404
• 自定义错误需继承 errors.Code 并在 errors.Register 中注册，否则 http.Transport 无法识别其状态码
• protoc-gen-go-errors 生成的 errors.pb.go 里包含 Code() 方法，但只有当错误值是该包生成的 struct 实例时才有效；用 fmt.Errorf("%w", yourErr) 会丢失 Code 信息

make all 编译失败：protoc 插件版本不兼容

protoc-gen-go v1.30.0 和 protoc-gen-go-grpc 若未同步升级，会导致生成代码中 import 路径冲突或缺少 XXX_Unmarshal 方法，编译报 undefined: proto.UnmarshalOptions 这类错误。

立即学习“go语言免费学习笔记（深入）”；

• 运行 go list -m google.golang.org/protobuf/cmd/protoc-gen-go 和 go list -m google.golang.org/grpc/cmd/protoc-gen-go-grpc，确认两者主版本号一致（如都是 v1.33.x）
• 删除 $GOPATH/bin 下旧插件，重新 go install，不要用 go get（已废弃）
• proto 文件里若含 import "google/protobuf/timestamp.proto";，需确保 GOOGLE_PROTOBUF_DIR 环境变量指向正确的 include 目录，否则 protoc 找不到基础类型定义
• Mac 上用 Homebrew 安装的 protoc 版本若低于 21.12，会解析新版 google.api.http option 失败，建议用 brew install protobuf@21 并软链

真正卡住人的往往不是语法，而是生成代码和运行时行为之间的隐式契约——比如 validate 不自动触发、error code 不自动映射、protoc 插件版本差一个 patch 就全挂。这些点没有日志提示，只能靠查生成代码和 debug handler 初始化流程。