Golang Kratos框架怎么用_Golang Kratos教程【指南】

kratos new 项目跑不起来的主因是环境链路断裂：kratos 命令未全局可用、go.mod 版本不兼容、模板拉取超时、proto 路径 / 插件 / 语法错误、HTTP 路由未注册、端口冲突等。

kratos new 命令生成的项目为什么跑不起来？

常见错误是 kratos new 后直接 kratos run 报错：找不到 go.mod、main.go 缺失，或提示 command not found: kratos。这不是框架问题，而是环境链路断了。

• kratos 命令必须能全局调用——确认 $GOPATH/bin 已加入 $PATH，执行 which kratos 有输出才真正安装成功
• 新项目默认基于 Go Modules，但部分旧版模板生成的 go.mod 里写的是 go 1.16，而你本地是 Go 1.21+，会导致 go mod tidy 失败；建议删掉 go.mod，手动运行 go mod init your-project-name
• kratos new helloworld 会拉取远程模板（默认 GitHub），国内常超时；可换源：kratos new helloworld -r https://gitee.com/go-kratos/kratos-layout.git

定义 API 时 device.proto 编译失败怎么排？

Protobuf 是 Kratos 的契约核心，但 device.proto 写完后 make api 报错，90% 出在三处：路径、插件、语法。

• 确保 .proto 文件放在 api/ 目录下（不是 proto/ 或根目录），且 package 声明为 package api;
• protoc-gen-go 和 protoc-gen-go-http 必须都装全，缺一个就只生成 gRPC 代码、不生成 HTTP 路由；推荐用 go install google.golang.org/protobuf/cmd/protoc-gen-go@latest + go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest
• 字段类型别写 float，要写 float32 或 float64；syntax="proto3"; 开头必须顶格，不能缩进

服务启动后 HTTP 接口 404，但 gRPC 能连上

这是新手最常卡住的点：Kratos 默认把 HTTP 和 gRPC 绑定在同一端口（如 8000），但路由注册逻辑藏在 internal/server/http.go 的 RegisterGreeterHandler 里，不是自动扫包。

• 检查 internal/server/http.go 中是否调用了 v1.RegisterGreeterHTTPServer（或你自己的 RegisterDeviceHTTPServer）
• 确认 api/v1/greeter_http.pb.go 已生成（即 make api 成功），否则注册函数不存在
• 路径前缀默认是 /v1，比如 curl http://localhost:8000/v1/say/hello，不是 /say/hello；这个前缀由 http.proto 里的 option (google.api.http) = {……}; 控制

要不要一开始就加 Consul 或 Prometheus？

不用。Kratos 的「开箱即用」是分层的：HTTP/gRPC/ 日志 / 配置这些是默认启用的；服务注册、指标采集、链路追踪都是可选插件，加得早反而干扰理解。

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

• 刚起步时，先删掉 cmd/server/main.go 里所有 consul.New、prometheus.New 相关代码，专注跑通一个 GET /v1/device/list
• 等接口稳定、数据模型跑通，再按需接入注册中心——此时你才知道自己真需要 registry 还是只是想本地多开几个实例调试
• 注意：一旦引入 consul，kratos run 就依赖本地 Consul 进程；没起 Consul 时启动失败，错误日志里往往只报 connection refused，容易误判成代码问题

最常被忽略的是：Kratos 的 conf/conf.yaml 里 server.http.addr 和 server.grpc.addr 默认都是 0.0.0.0:8000，两个协议抢同一个端口会静默失败——必须改成不同端口，或者明确指定其中一个关闭。