Kratos 的 proto 接口需同时满足三要素:显式 import google/api/annotations.proto、正确书写 option (google.api.http)(如 get:"/hello/{name}")、装齐 protoc-gen-go-grpc 与 protoc-gen-go-http 插件,否则 HTTP 路由不生成、参数绑定失败或 RegisterXXXServiceServer 函数缺失。

Kratos 的 proto 接口定义不是“写完就能用”,关键在于 google.api.http 注解、插件组合、参数绑定三者必须对齐,否则生成的 HTTP 路由不生效、参数取不到、甚至 RegisterXXXServiceServer 函数缺失。
proto 文件里必须显式 import google/api/annotations.proto
没这行 import,option (google.api.http) 就是非法语法,protoc 直接报错;即使侥幸通过(比如用了旧版插件),生成的 *_http.pb.go 里也不会有 HTTP 映射逻辑。
- 必须放在 proto 文件顶部,紧挨着
syntax = "proto3"和package声明之后 - 路径要对:Bilibili 官方维护的
google/api/annotations.proto默认在third_party/google/api/下,kratos 脚手架已预置,别自己下载乱放 - 如果用
buf编译,需在buf.yaml的deps里声明https://github.com/bufbuild/protoc-gen-validate等依赖,否则annotations.proto找不到
option (google.api.http) 的写法决定参数怎么进 struct
HTTP 方法和路径模板直接控制 HelloRequest 字段如何从 URL 或 body 中提取——写错一个符号,name 就是空字符串。
-
get: "/hello/{name}"→ URL 路径段/hello/kratos会自动赋值给HelloRequest.Name字段(字段名必须小写匹配) -
get: "/hello" body: "*"→ 不合法,GET不能带body;POST才能用body: "*"把整个 JSON body 映射到 request struct -
post: "/user" body: "user"→ 请求 body 中的{"user": {"name": "a", "age": 18}}才会把user对象赋给CreateUserRequest.User字段 - 路径参数名(如
{id})必须在message定义中存在同名字段,且类型一致(int64 id = 1对应/user/123)
生成代码前必须装齐两个插件:protoc-gen-go-grpc 和 protoc-gen-go-http
只装 protoc-gen-go 会生成基础 .pb.go,但没有 RegisterXXXServiceServer 函数,也没有 xxx_http.pb.go,service.Register() 必 panic。
-
protoc-gen-go-grpc:负责生成 gRPC Server 注册函数(如RegisterGreeterServiceServer) -
protoc-gen-go-http:负责生成 HTTP 路由注册逻辑(如registerGreeterServiceHandlerFromEndpoint) - 安装命令(Go 1.21+):
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest和go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest - 执行
make api时,命令行里必须同时指定这两个插件,缺一不可
字段校验和错误码定义得靠额外 proto 导入
单纯定义 string name = 1 不会做长度检查;返回 500 还是 400 也不由框架自动判断——这些都得靠 validate 和 errors 扩展。
- 加校验:import
"validate/validate.proto",然后string name = 1 [(validate.rules).string.min_len = 1]; - 定错误码:import
"errors/errors.proto",在enum ErrorReason里用[(errors.code) = 404]标注具体枚举项 - 注意:
validate规则只在生成的 Go struct 上加 tag(如json:"name" validate:"min=1"),实际校验要靠中间件手动调用validator.Validate() - 错误码映射不是自动的——你得在 service 实现里
return errors.BadRequest("USER_NOT_FOUND", "用户不存在"),才能触发 404
最常被跳过的其实是路径参数字段命名一致性:proto 里字段是 string name = 1,URL 写成 get: "/hello/{Name}"(首字母大写)就完全不匹配,参数永远为空。这种细节不跑一遍请求根本看不出来。











