够用，但必须理解每层职责，否则后续扩展会失控；kratos默认api/internal/cmd三层结构是强制约束：协议定义在api/下，业务逻辑限于internal/service与internal/biz，数据访问封装在internal/data。
kratos new 生成的项目结构是否够用？
够用，但必须理解每层职责，否则后续扩展会失控。Kratos 默认生成的 api/internal/cmd 三层结构不是摆设，而是强制约束：协议定义（.proto）必须在 api/ 下；业务逻辑只能写在 internal/service 和 internal/biz；数据访问封装在 internal/data。一旦把数据库查询直接塞进 handler，或把 HTTP 参数校验逻辑混进 service，很快就会变成“大厂级技术债现场”。
常见错误现象：
- 改一个接口要动
handler、service、data三个包，因为职责没切清 -
internal/service里出现sql.DB或redis.Client实例，违反了依赖倒置原则 -
api/order/v1/order.proto里定义了GetOrderRequest，但实际 handler 接收的是 raw JSON body，绕过了 Protobuf 校验
protoc-gen-go-http 生成的 HTTP 路由是否可靠？
可靠，但必须配合 http.proto 显式声明，不能只靠注释。Kratos 的 HTTP 路由不是靠反射或 magic string 解析，而是由 protoc-gen-go-http 从 http.proto 文件中读取 HttpRule 生成代码。如果漏写 http.proto，或者 option (google.api.http) 写错位置（比如写在 message 里而非 rpc 方法上），make api 后根本不会生成路由注册逻辑，服务启动后该接口 404。
实操建议：
- 每个
rpc方法上方必须加option (google.api.http) = { ... };，且只支持get/post/put/delete四种 method - 路径参数必须用
{id}形式，且对应 request message 中字段名一致，例如GetOrderRequest.id - 不要手动修改
internal/server/http.go中的路由注册块——那是生成代码，下次make api会被覆盖
wire 依赖注入失败时怎么快速定位？
看 wire_gen.go 是否为空，以及 go run ./cmd/xxx -v 启动时 panic 的第一行错误。Wire 不是运行时 DI 容器，而是在编译前生成构造函数代码。如果 wire.Build(...) 中漏传某个 provider，或类型不匹配（比如期望 *sql.DB 却传了 sql.DB），wire 命令会静默失败，wire_gen.go 里只剩空函数，最终服务 panic 提示 “nil pointer dereference” 或 “interface conversion: interface {} is nil”。
关键检查点：
- 确认
cmd/xxx/wire.go中wire.Build列表包含所有必要 provider，尤其是data.NewData、service.NewService、handler.NewHandler - 检查每个 provider 函数签名：返回值类型必须和依赖注入目标完全一致（包括指针/值语义）
- 执行
cd cmd/xxx && wire手动触发生成，观察终端输出——成功时会打印 “Writingwire_gen.go”，失败则报具体 missing type
HTTP 和 gRPC 双协议共存时容易忽略什么？
忽略 errors.proto 的统一错误映射规则，导致 HTTP 返回 500 而 gRPC 返回 UNKNOWN。Kratos 默认将 Protobuf error code 映射为 HTTP status code，但这个映射只对 rpc 方法内显式返回的 errors.BadRequest 等生效。如果业务逻辑里直接 return nil, errors.New("xxx")，gRPC 会转成 codes.Unknown，HTTP 则变成 500，破坏可观测性一致性。
正确做法：
- 所有错误必须通过
errors.NewCode或errors.BadRequest等预定义函数构造，不能用原生errors.New - 在
api/order/v1/error.proto中定义业务错误码，并确保protoc-gen-go-errors已安装并参与make api - HTTP 中间件里不要用
ctx.Error()捕获 panic 并转成 500——这会绕过 Kratos 错误体系，应让错误自然冒泡到 handler 层再统一处理
真正的大厂级架构，不在于堆砌组件，而在于每一层契约是否被严格执行。Kratos 的模板看似简单，但只要有一处越界（比如 handler 直连 DB、service 返回裸 error），整个链路的可维护性就会断崖下跌。最常被跳过的其实是 make api 后手动检查生成代码——别嫌烦，那几行 srv.Handle 注册代码，就是你服务暴露边界的最后一道防线。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
