Kratos接口定义必须用Protobuf文件，至少包含syntax="proto3"、package与go_package声明、service及rpc方法、request和reply message；加google.api.http选项并正确导入annotations.proto才能生成HTTP路由。
Kratos 微服务的接口定义必须用 Protobuf（.proto 文件），不是写 HTTP handler，也不是直接写 Go 接口；不加 google.api.http 选项就只有 gRPC，加了才能生成 HTTP 路由。
Protobuf 文件必须包含哪些基础结构
一个可被 Kratos 正常识别并生成代码的 .proto 文件，至少要满足这四点：
-
syntax = "proto3"—— 必须是 proto3，proto2 不支持 -
package+option go_package—— 后者决定生成的 Go 包路径，不能漏，否则依赖注入失败 - 至少一个
service定义，里面含rpc方法 - 每个
rpc方法必须有明确的request和replymessage 类型（哪怕空）
常见错误：go_package 写成相对路径（如 "./api/v1"）或没写，导致 protoc 生成的 .pb.go 文件无法被 Kratos 的 DI 容器识别，启动时报 cannot find package 或 unknown service。
HTTP 路由怎么绑定到 rpc 方法上
靠 google.api.http 扩展选项，它不是标准 protobuf 语法，需显式 import "google/api/annotations.proto"。绑定方式分三类：
-
get: "/hello"—— 查询参数自动映射到 request message 字段（如HelloRequest.name） -
get: "/hello/{name}"—— 路径参数，字段名必须完全匹配（name字段必须存在且类型为string） -
post: "/hello" body: "*"—— POST 请求体全量映射到 request message，适用于 JSON body 提交
注意：body: "*" 是最常用写法；若只映射部分字段（比如只取 name），得写成 body: "name"，但容易和路径参数冲突，不推荐初学者用。
为什么生成的 HTTP handler 总是 404
90% 是以下三个原因导致的：
-
protoc没启用 HTTP 插件：命令里漏了--go-http_out=.或插件未安装（go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http@latest） -
service名或rpc名没在internal/server/http.go中注册 —— Kratos 不自动扫描，必须手动调用v1.RegisterGreeterHTTPServer()（函数名由package和service名拼成） - HTTP server 启动时没加载对应路由组 —— 检查
http.NewServer()构造时是否传入了正确的http.Router实例，以及该 router 是否已挂载生成的 handler
典型表现：gRPC 端口（如 :9000）能连上，HTTP 端口（如 :8000）返回 404，但日志里没有报错 —— 这说明 HTTP server 起来了，只是没注册 handler。
参数校验和错误码怎么写进 proto
Kratos 支持通过 proto 扩展直接声明校验规则和错误码，不用在 service 层手写 if 判断：
- 字段校验用
validate：先import "validate/validate.proto"，再给字段加[(validate.rules).string = {min_len: 1, max_len: 16}] - 错误码用
errors：导入errors/errors.proto，定义enum ErrorReason，并在每个枚举值上加[(errors.code) = 400] - 这些扩展不会影响 gRPC 通信，但会注入到 HTTP middleware 中，自动拦截非法请求并返回对应状态码
容易忽略的一点：校验只对 HTTP 请求生效（Kratos 的 validator middleware 默认只 hook HTTP transport），gRPC 请求即使字段非法，也会透传到 service 层 —— 如果你同时暴露两种协议，得额外在 service 层做兜底校验。
