kratos-skills

面向 AI Agent 的 Kratos 技能

此技能提供全面的 go-kratos 微服务框架知识，专为帮助开发者构建可用于生产环境的服务而优化。

🎯 何时使用此技能

在使用 go-kratos 时调用此技能：

• 创建服务：REST API、gRPC 服务或微服务架构
• 分层架构：使用 DDD 实现 Service → Biz → Data 分层
• 依赖注入：使用 Wire 进行编译时 DI
• 生产环境强化：熔断器、限流、中间件
• 调试：理解错误、修复配置或解决问题
• 学习：了解 kratos 模式和最佳实践

📚 知识结构

根据需要加载特定指南，而不是一次性阅读所有内容：

快速入门

链接：Kratos 官方文档 包含内容：安装、项目创建、基本命令、Hello World 示例

模式指南

API 与传输

文件	加载时机
references/api-patterns.md	定义 Protobuf API、生成 HTTP/gRPC 代码
references/transport-patterns.md	配置 HTTP/gRPC 服务端和客户端
references/encoding-patterns.md	自定义序列化、内容协商
references/openapi-guide.md	生成 OpenAPI/Swagger 文档

架构与设计

文件	加载时机
references/architecture-patterns.md	DDD 分层、仓储模式、Wire DI
references/error-patterns.md	错误定义、断言、Proto 错误
references/middleware-patterns.md	自定义中间件、请求过滤

基础设施

文件	加载时机
references/config-patterns.md	配置加载、热重载、配置中心
references/registry-patterns.md	服务发现（etcd、consul、nacos、k8s）
references/selector-patterns.md	负载均衡（P2C、WRR、随机）

弹性与可靠性

文件	加载时机
references/circuit-breaker-patterns.md	容错、SRE 熔断器
references/ratelimit-patterns.md	令牌桶、BBR 限流
references/recovery-patterns.md	Panic 恢复、堆栈跟踪日志记录

可观测性

文件	加载时机
references/logging-patterns.md	结构化日志、Zap/Logrus 适配器
references/metrics-patterns.md	Prometheus 指标收集
references/tracing-patterns.md	OpenTelemetry、Jaeger/Zipkin 链路追踪
references/metadata-patterns.md	上下文传播、跟踪 ID

安全与验证

文件	加载时机
references/auth-patterns.md	JWT 身份验证、声明、令牌生成
references/validate-patterns.md	Proto 字段验证、protoc-gen-validate

数据与工具

文件	加载时机
references/ent-patterns.md	Ent ORM 集成、架构设计
references/cli-guide.md	kratos CLI、代码生成命令

支持的资源

文件	加载时机
best-practices/overview.md	生产环境部署、代码审查清单
troubleshooting/common-issues.md	调试错误、protoc/wire 问题
getting-started/claude-code-guide.md	Claude Code 集成、高级功能

🚀 常见工作流

创建新服务

1. 创建项目：kratos new <project-name>
2. 定义 API：创建带有 google.api.http 注解的 .proto
3. 生成代码：kratos proto client api/demo/v1/demo.proto
4. 生成服务：kratos proto server api/demo/v1/demo.proto -t internal/service
5. 实现各层：在 internal/biz/ 中编写 Biz 逻辑，在 internal/data/ 中实现数据访问
6. 配置 Wire：使用 provider sets 更新 cmd/server/wire.go
7. 运行：go generate ./... && kratos run

详情：references/api-patterns.md

实现分层架构

1. 在 internal/biz/ 中定义接口（biz 层）
2. 在 internal/data/ 中实现仓库（data 层）
3. 在 internal/biz/ 中编写用例（biz 层）
4. 在 internal/service/ 中实现处理器（service 层）
5. 创建 ProviderSets：data.ProviderSet、biz.ProviderSet、service.ProviderSet
6. 在 cmd/server/wire.go 中完成组装

详情：references/architecture-patterns.md

添加中间件

http.Middleware(
    recovery.Recovery(),           // 1. Catch panics first
    validate.Validator(),          // 2. Validate requests
    jwt.Server(keyFunc),           // 3. Authentication
    ratelimit.Server(limiter),     // 4. Rate limiting
    logging.Server(logger),        // 5. Logging
)

详情：references/middleware-patterns.md

配置服务发现

// Server-side
reg := etcd.New(client)
app := kratos.New(kratos.Registrar(reg))

// Client-side
dis := etcd.New(client)
conn, _ := grpc.DialInsecure(
    context.Background(),
    grpc.WithEndpoint("discovery:///service-name"),
    grpc.WithDiscovery(dis),
)

详情：references/registry-patterns.md

⚡ 核心原则

✅ 始终遵循

• 分层：Service（API）→ Biz（业务）→ Data（持久化）
• 依赖倒置：接口定义在 biz 层，实现放在 data 层
• Protobuf 优先：在 .proto 文件中定义 API 和错误
• Wire 注入：编译时依赖注入，不使用全局状态
• 上下文传递：在所有层之间传递 ctx context.Context
• 基于接口设计：面向接口编程，而非具体实现
• 错误码：使用包含代码、原因、消息和元数据的结构化错误

❌ 绝不这样做

• 将业务逻辑放入 service 处理器中（违反分层架构）
• 跳过接口定义，直接使用具体类型
• 使用全局变量管理依赖
• 手动定义 HTTP 处理器（使用由 proto 生成的代码）
• 硬编码配置值
• 跳过验证或忘记检查 err != nil
• 修改生成的 .pb.go 文件

📖 渐进式学习路径

🟢 刚接触 kratos？

1. 官方快速入门 - 安装 CLI，创建第一个项目
2. references/architecture-patterns.md - 了解 Service → Biz → Data
3. references/api-patterns.md - 学习 Protobuf API 定义

🟡 正在构建生产服务？

1. best-practices/overview.md - 生产环境检查清单
2. references/circuit-breaker-patterns.md + references/ratelimit-patterns.md - 增强韧性
3. references/registry-patterns.md - 服务发现
4. troubleshooting/common-issues.md - 避免常见问题

🔵 想扩展能力？

1. getting-started/claude-code-guide.md - Claude Code 高级功能
2. Kratos 示例 - 示例项目

🔗 Kratos 生态系统

项目	用途
kratos	框架核心、CLI 工具
kratos-layout	官方项目模板
contrib	用于配置、注册、日志、指标的插件
aegis	可用性算法
gateway	API 网关
examples	示例代码

📝 版本兼容性

• 目标版本：kratos v2.0.0+
• Go 版本：建议使用 Go 1.19 或更高版本
• Protoc：3.0+

---

快速调用：使用 /kratos-skills，或询问“如何使用 kratos 完成 [task]？”