| name | kratos-development |
| description | Develops Go microservices with Kratos v2 following official design philosophy, DDD/Clean Architecture layout, Protobuf API, error/config/middleware patterns, and observability. Use when building or modifying Kratos services, wiring servers, writing proto APIs, middleware, errors, config, or when the user mentions Kratos, go-kratos, kratos-layout, or microservice framework conventions. |
Kratos 微服务开发
基于 Kratos Design 与 Layout 官方文档，指导在 Moon monorepo 中用 Kratos v2 开发微服务。
何时使用
- 新建或改造 Kratos 微服务（HTTP/gRPC/Job）
- 编写 proto API、错误码、中间件、配置加载
- 接入注册发现、日志、监控、链路追踪
- 理解分层职责与依赖方向
Moon 具体模块实现（biz/data/service 等）请配合 proto-backend-module。
设计哲学（核心）
Kratos 是 Go 微服务工具箱，不是绑定特定基础设施的全家桶：
| 原则 | 含义 |
|---|
| 插件化 | 各功能模块定义标准接口，第三方库通过实现接口接入 |
| 可定制 | 不强制项目结构；layout 是推荐实践，可改 |
| 轻量 | 框架本身轻，按需选组件 |
| DDD + Clean Architecture | V2 重构目标：可读性、可测试性、可维护性 |
生态：kratos（核心）、contrib（配置/日志/注册等插件）、aegis（限流/熔断，可独立于 Kratos）、layout（项目模板）。
标准分层（Layout）
cmd/run/{http,grpc,job,all}/ # 入口 + wire 注入
internal/
conf/ # conf.proto → 配置结构
server/ # HTTP/gRPC 实例、中间件、Register*Service
service/ # 实现 proto Server 接口，DTO↔BO，薄层
biz/ # 业务逻辑；repository 接口定义于此（依赖倒置）
data/ # repo 实现；DB/缓存/远程调用封装
api/ 或 proto/ # .proto + 生成代码
config/ # 运行时 YAML
依赖方向：server → service → biz ← data（biz 定义接口，data 实现）。
| 层 | 职责 | 禁止 |
|---|
| service | 对接 API、参数转换、调用 biz | 复杂业务逻辑 |
| biz | 组合业务、定义 repository 接口 | 直接操作 DB |
| data | repo 实现、PO↔DTO 转换 | 跨表组合业务判断 |
Moon 差异：proto/ 在仓库根目录；各 app 独立 go.mod；共享能力在 magicbox/。
API 定义（Protobuf）
- 默认
protoc 生成 gRPC；HTTP 需在 proto 中加 google.api.http：
import "google/api/annotations.proto";
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = { get: "/helloworld/{name}" };
}
}
- HTTP 默认 JSON 序列化；其他格式见官方 Serialization 文档。
- 不适合 proto 的场景（文件上传、无法映射的 JSON）：用普通
http.Handler 挂到路由，或在 service 层用 struct 定义字段。
- Moon：
make api / make gen 生成；go_package 指向 github.com/aide-family/<app>/pkg/api/v1。
Metadata
服务间调用需传递、但不进 payload 的元信息，用 Kratos metadata 包读写。Moon 中常见：contextx 封装 namespace、user 等（见 magicbox/contextx）。
错误处理
Kratos 错误四要素：
| 字段 | 用途 |
|---|
code | 类 HTTP Status，网关可据此做重试/限流/熔断 |
reason | 服务内唯一可读错误码（如 USER_NOT_FOUND） |
message | 用户可读提示 |
metadata | 扩展信息 |
errors.New(500, "USER_NAME_EMPTY", "user name is empty")
api.ErrorUserNotFound("user %s not found", name)
if errors.Is(err, errors.BadRequest("USER_NAME_EMPTY", "")) { ... }
if api.IsUserNotFound(err) { ... }
e := errors.FromError(err)
HTTP 错误 JSON：{"code":500,"reason":"USER_NOT_FOUND","message":"...","metadata":{...}}
Moon：业务错误优先用 magicbox/merr 与 app 内 proto 生成的 errors，保持与现有模块一致。
配置
统一接口：实现 Source + Watcher 即可接入任意配置源。
内置/插件：file、apollo、etcd、kubernetes、nacos。
Moon 模式：
internal/conf/*.proto 定义 Bootstrap- 运行时
config/server.yaml 字段必须与 proto 同步
- 修改 conf.proto 后同步 YAML 并重新生成 pb
注册与发现
实现 Registrar + Discovery 接入注册中心。插件：consul、etcd、nacos、kubernetes、zookeeper 等。
Moon：data 层提供 Registry()；kratos.New 时 kratos.Registrar(registry) 注册服务。
日志
Logger：底层接口，仅 Log 方法，用于适配第三方库Helper：带级别与格式化，业务层推荐用 Helper
插件：std（内置）、zap、fluent。Moon 中 biz/service 注入 *klog.Helper，错误用 helper.Errorw(...)。
可观测性
| 能力 | 方式 |
|---|
| Metrics | 实现 Metrics 接口；插件 prometheus、datadog |
| Tracing | OpenTelemetry；server/client 初始化时加 tracing 中间件 |
| 负载均衡 | 客户端：Weighted RR（默认）、P2C、Random |
Moon HTTP 示例中间件链：recovery → logging → tracing → metadata → auth → validate（见 internal/server/http.go）。
中间件
通过实现 middleware.Middleware 统一横切逻辑。常用内置/官方：recovery、logging、tracing、metadata、ratelimit、circuitbreaker。
http.NewServer(http.Middleware(recovery.Recovery(), logging.Server(logger), ...))
authMiddleware := selector.Server(jwtMiddlewares...).
Match(middler.AllowListMatcher(skipList...)).Build()
限流/熔断算法在 aegis，可独立于 Kratos 使用。
应用生命周期
app := kratos.New(
kratos.Name("service.http"),
kratos.Server(httpSrv, grpcSrv),
kratos.Logger(logger),
kratos.Registrar(registry),
)
app.Run()
Moon：cmd/run/server.go 的 NewApp 为每个 transport 创建独立 kratos.App；wire 在 cmd/run/{http,grpc,all}/wire.go。
Wire 依赖注入
func WireApp(...) (*kratos.App, func(), error) {
panic(wire.Build(
server.ProviderSetServerHTTP,
service.ProviderSetService,
biz.ProviderSetBiz,
impl.ProviderSetImpl,
data.ProviderSetData,
run.NewApp,
))
}
各层用 wire.NewSet(...) 导出 ProviderSet；新增组件时注册到对应 ProviderSet。
新增 HTTP/gRPC 服务 checklist
- [ ] proto 定义 service + google.api.http（HTTP）
- [ ] make api 生成代码
- [ ] internal/service 实现生成的 Server 接口
- [ ] internal/biz 业务逻辑 + repository 接口
- [ ] internal/data/impl repository 实现
- [ ] ProviderSet 注册（service/biz/impl）
- [ ] internal/server Register*Service 注册路由
- [ ] 中间件白名单（若需跳过 auth/namespace）
- [ ] config/server.yaml 同步（若涉及配置）
数据库 / 缓存 / 消息队列
Kratos 不绑定 ORM/驱动，自选集成。常见：gorm、ent、go-redis、sarama/kafka-go。
Moon：GORM + gorm.io/gen；新增 model 后 gen query，禁止手写 SQL 字符串条件（见 proto-backend-module）。
反模式
- ❌ 在 service 层写复杂业务或直连 DB
- ❌ 在 data 层组合多表业务判断
- ❌ 跳过 wire ProviderSet 手动 new 依赖
- ❌ proto 改完不跑 make api / conf.proto 改完不同步 YAML
- ❌ 中间件链顺序随意（recovery/logging 应靠前）
延伸阅读
