kratos grpc接口定义必须将.proto文件置于api/子目录下且package名与路径严格一致，否则代码生成静默失败或运行异常；需显式声明go_package、import google/api/annotations.proto以支持http映射。
要在Kratos项目中正确添加并管理gRPC接口定义，必须严格遵循proto文件的路径放置规则与package命名规范，否则后续代码生成将静默失败或运行时panic。
执行kratos proto add命令前的必要准备
确保当前目录是项目根目录（即包含go.mod的目录），且已安装kratos v2命令行工具（验证方式：kratos version输出v2.x.x）。
确认api/目录已存在——若不存在，需手动创建：【kratos proto add只扫描api/子目录，不支持proto/、internal/api/等任意其他路径】。
这一步操作起来很简单，直接在终端输入mkdir -p api即可完成。
kratos proto add命令的标准用法
在项目根目录下执行：
kratos proto add api/user/v1/user.proto
该命令会在指定路径创建一个基础proto模板文件，内容含syntax、package、go_package及空service定义。
注意：命令中路径必须以api/开头，且文件名须以.proto结尾；中间目录层级不限，但必须符合后续package语义。
proto文件必须满足的两个硬性约定
第一步：package名必须与目录结构完全一致。例如文件路径为api/user/v1/user.proto，则package必须声明为package user.v1; ——【若写成package user 或 package v1，生成的Go包路径将错乱，wire注入和gRPC注册均失败】。
第二步：option go_package必须显式声明，格式为"相对路径;别名"，如option go_package = "user/api/user/v1;v1";。其中左侧路径应与文件系统路径对应，右侧别名用于Go import时标识。
第三步：若需启用HTTP网关映射，必须import "google/api/annotations.proto"并启用protoc-gen-go-http插件，否则option (google.api.http) = { get: "/xxx" };将被完全忽略。
常见错误路径与后果对照
方法一：把proto文件放在api/xxx.proto（顶层）→ kratos proto server能扫描到，但package无法匹配任何合理Go路径，生成代码无法被正常import。
方法二：放在internal/api/user.proto → 【kratos proto client/server命令静默跳过，不报错也不生成任何文件】。
方法三：package写成kratos.api.user但目录是api/user/v1/ → 生成的.pb.go中import路径为kratos/api/user/v1，与实际目录api/user/v1不匹配，编译失败。
验证proto是否就位的最快方式
执行make api（前提是项目已配置Makefile）。
观察输出日志中是否出现类似“generate api/user/v1/user.pb.go”字样；若无任何生成记录，说明proto未被识别。
也可手动检查：ls api/user/v1/user*.go —— 正常应看到user.pb.go、user_grpc.pb.go、user_http.pb.go（启用HTTP插件时）三个文件。
