Kratos 项目初始化应选用官方 kratos-layout：它预置 Protobuf、HTTP/gRPC 双协议、Wire 依赖注入及配置加载链路，避免手动拼凑出错；删改自动生成的 grpc.go/http.go 或错误配置 registry 地址是常见失败主因。
kratos 不是“必须微服务才能用”的框架，它天然支持单体与微服务双模演进。如果你正在评估是否该在新项目中引入 kratos，答案很明确：从单体起步更稳妥，且不牺牲未来拆分能力。
kratos 项目初始化时该选什么 layout？
官方 kratos-layout 是唯一推荐起点，它已预置 Protobuf + HTTP/gRPC 双协议 + Wire 依赖注入 + 配置加载链路，避免你手动拼凑中间件顺序出错。
常见错误现象：kratos new myapp 后直接改 main.go 手动注册 gRPC server，结果 registry 没注入、服务没注册到 Consul、健康检查接口 404。
- 始终用
kratos proto server api/xxx/xxx.proto -t internal/service生成 service 模板，它会自动挂载到app.Run()的生命周期里 - 不要删掉
internal/server下的grpc.go和http.go—— 它们不是样板，而是配置绑定入口 - 若需单体部署，把
configs/config.yaml中的registry配置块注释掉即可，不影响其他功能
Protobuf 定义里哪些字段会影响运行时行为？
google.api.http 和 validate.rules 不是装饰性注解，它们在生成代码时直接参与路由注册和参数校验逻辑。
典型踩坑点：定义了 get: "/users/{id}" 却收不到请求，日志显示 no route matched。
-
{id}必须对应HelloRequest中同名字段（如string id = 1;），否则 HTTP 路由解析失败 -
validate.rules的校验在中间件层触发，失败时返回400 Bad Request，而非透传到 service 方法 - 若同时启用 gRPC-Gateway 和 OpenAPI，
protoc-gen-openapiv2会读取这些注解生成 swagger.json，别漏装插件
服务注册失败的三个高频原因
本地 kratos run 能跑通，但部署后服务在 Consul/Nacos 上看不到 —— 这类问题 80% 出在配置加载时机或地址格式上。
错误信息示例：failed to register instance: Get "http://127.0.0.1:8500/v1/agent/service/register": dial tcp 127.0.0.1:8500: connect: connection refused
-
registry.consul.address必须是容器/集群内可访问地址，写127.0.0.1在 Docker 中必然失败，应改用宿主机 IP 或服务名（如consul-server） - Consul 的
scheme默认是http，若启用了 TLS，则必须显式设为https，否则 client 初始化静默失败 - 服务注册发生在
app.Run()阶段，若你在init()里提前调用registry.Register()，会因 registry 实例未初始化而 panic
为什么 JWT 中间件不拦截 OPTIONS 预检请求？
middleware/auth/jwt/jwt.go 默认跳过 OPTIONS 方法，这是故意设计，不是 bug。CORS 预检必须放行，否则前端跨域请求直接卡在预检阶段。
但这也意味着：如果你的 API 允许匿名 POST /login，又没加额外限流，攻击者可绕过 JWT 校验发起暴力爆破。
- 真正需要保护的 endpoint（如
GET /user/profile）才应用jwt.Server()，登录接口用ratelimit.Server()更合适 - 若必须对 OPTIONS 做鉴权（极少见），需自定义中间件，在
jwt.Server()前插入逻辑，但注意不要破坏 CORS 头 -
jwt.WithSigningMethod(jwt.SigningMethodRS256)要求密钥是 PEM 格式私钥，硬编码字符串只适用于 HS256；生产环境务必从文件或 KMS 加载
真实项目里最易被忽略的，是配置加载顺序与环境变量覆盖关系 —— file.NewSource() 和 env.NewSource() 的先后顺序，决定了 CONSUL_ADDRESS 环境变量能否覆盖 YAML 里的值。这个细节不验证，上线后服务就“消失”在注册中心里。
