zero-skills

面向 AI Agent 的 go-zero 技能

此技能提供全面的 go-zero 微服务框架知识，专为帮助开发者构建可用于生产环境的服务的 AI Agent 优化。内容涵盖 REST API、RPC 服务、数据库操作、弹性模式、高性能数据结构和故障排查。

🎯 何时使用此技能

使用 go-zero 时，请调用此技能：

• 创建服务：REST API、gRPC 服务或微服务架构
• 数据库集成：SQL、MongoDB、Redis 或连接池
• 数据结构：LRU Cache、Ring Buffer、TimingWheel 或并发映射
• 生产环境加固：熔断器、限流或错误处理
• 调试：理解错误、修复配置或解决问题
• 学习：了解 go-zero 模式和最佳实践

📚 知识结构

此技能将 go-zero 知识整理为多个专门模块。按需加载特定指南，而非一次性阅读所有内容：

快速入门指南

链接：go-zero 官方文档 包含内容：安装、第一个 API 服务、基本命令、Hello World 示例（请参阅官方文档）

模式指南（详细参考）

1. REST API 模式

文件：references/rest-api-patterns.md 加载时机：创建 HTTP 端点、实现 CRUD 操作、添加中间件 包含内容：

• Handler → Logic → Context 三层架构
• 使用适当类型处理请求和响应
• 中间件（身份验证、日志记录、指标、CORS）
• 使用 httpx.Error() 和 httpx.OkJson() 处理错误
• 完整的 CRUD 示例，展示 ✅ 正确与 ❌ 错误模式

2. RPC 服务模式

文件：references/rpc-patterns.md 加载时机：构建 gRPC 服务、实现服务间通信 包含内容：

• Protocol Buffers 定义和代码生成
• 使用 etcd/consul/kubernetes 进行服务发现
• 负载均衡策略
• 客户端配置和拦截器
• RPC 上下文中的错误处理

3. 数据库模式

文件：references/database-patterns.md 加载时机：实现数据持久化、缓存或复杂查询 包含内容：

• 使用 sqlx 执行 SQL 操作（CRUD、事务、批量插入）
• MongoDB 集成模式
• Redis 缓存策略和 Cache-Aside 模式
• 使用 goctl model 生成模型
• 连接池和性能调优

4. 弹性模式

文件：references/resilience-patterns.md 加载时机：加固生产环境、处理故障、管理系统负载 包含内容：

• 熔断器配置（Breaker）
• 限流和 API 节流
• 高负载下的负载削减
• 超时和重试策略
• 优雅关闭和降级

5. 集合模式

文件：references/collection-patterns.md 加载时机：使用高性能数据结构、本地缓存、超时管理 包含内容：

• 用于本地热点数据缓存的 LRU Cache（O(1) 操作）
• 用于固定大小循环缓冲区的 Ring Buffer
• 用于高效计时器管理的 TimingWheel（O(1) 添加/移除/执行）
• 用于并发安全映射操作的 SafeMap
• 内存管理最佳实践和常见陷阱

6. goctl 命令参考

文件：references/goctl-commands.md 加载时机：使用 goctl 生成代码、搭建新服务、执行代码生成后的步骤 包含内容：

• goctl 安装和检测
• 带精确标志的 API/RPC/Model 生成命令
• 代码生成后的流程（mod tidy、修复导入、验证构建）
• 配置模板（API、RPC、生产环境）
• 部署模板（Dockerfile、Kubernetes、Docker Compose）
• 中间件和错误处理器模板
• API 规范模式（CRUD、JWT、混合身份验证）

7. Swagger / OpenAPI 文档

文件：references/swagger-patterns.md 加载时机：从 .api 文件生成 Swagger/OpenAPI 文档，添加 API 文档注解 包含：

• 内置 goctl api swagger 命令参考（goctl ≥ 1.8.4，无需插件）
• info 块元数据：title、description、host、basePath、schemes、useDefinitions、wrapCodeMsg
• 用于 Swagger UI 分组的 @server 标签
• 用于端点摘要/描述的 @doc
• 字段标签：example、options（枚举）、range、default、optional
• 安全定义（securityDefinitionsFromJson + authType）
• 业务错误码（bizCodeEnumDescription）
• 包含最佳实践的完整多文件 .api 结构示例

8. 分布式事务模式

文件：references/distributed-transactions.md 加载时机：跨服务数据一致性、DTM 集成、SAGA/TCC 模式 包含：

• Workflow、Saga、TCC、XA、两阶段消息和 outbox 的模式选择指南
• 经过验证的 DTM HTTP Saga 骨架
• Barrier、幂等性、补偿、安全和故障测试检查清单

9. 可观测性模式

文件：references/observability.md 加载时机：生产环境监控、追踪、告警设置 包含：

• Prometheus 指标配置
• 自定义指标实现
• 使用 OpenTelemetry/Jaeger 进行分布式追踪
• 使用 logx 进行结构化日志记录
• Grafana 仪表板和告警规则
• 用于日志聚合的 ELK 集成

10. 消息队列模式

文件：references/message-queue.md 加载时机：异步处理、延迟任务、事件流 包含：

• 用于延迟任务的 go-queue dq（Beanstalkd）
• 用于高吞吐量消息传递的 go-queue kq（Kafka）
• 当前的生产者和消费者 API
• 生命周期、重试、幂等性和关闭指南

11. 高级组件

文件：references/advanced-components.md 加载时机：性能优化、并发处理、缓存 包含：

• 用于防止缓存穿透的布隆过滤器
• 用于延迟任务调度的 TimingWheel
• 用于并行处理的 MapReduce
• 用于批量任务缓冲的 Executors
• 用于防止重复执行的 SharedCalls（SingleFlight）

支持资源

最佳实践

文件：best-practices/overview.md 加载时机：生产环境部署、代码审查、优化 包含：配置管理、日志记录、监控、安全、性能

故障排查

文件：troubleshooting/common-issues.md 加载时机：调试错误、配置问题、运行时问题 包含：常见错误消息、解决方案、配置陷阱、调试技巧

Claude Code 集成

文件：getting-started/claude-code-guide.md 加载时机：设置 Claude Code 以实现零技能使用 包含：安装、调用方法、高级功能（子 Agent、动态上下文）

设计原则

文件：design/principles.md 加载时机：了解框架理念、架构决策 包含：三层架构原理、设计决策、性能考量、反模式

案例研究：go-zero-looklook

文件：examples/case-studies/looklook-overview.md 加载时机：从生产规模示例中学习、了解真实世界的架构 包含：基于源码的仓库地图、学习工作流、可复用模式和验证检查清单

工具集成指南

文件：getting-started/README.md 加载时机：使用 Cursor、GitHub Copilot、Windsurf 或 Codex 配置 zero-skills 时 包含内容：功能对比表、各工具的配置说明（Claude Code、Cursor、Copilot、Windsurf、Codex）

🚀 常见工作流

这些工作流将引导你完成典型的 go-zero 开发任务：

创建新的 REST API 服务

步骤：

1. 在 .api 文件中定义 API 规范，包括类型和路由
2. 生成代码：goctl api go -api user.api -dir .
3. 在 internal/logic/ 层实现业务逻辑
4. 使用 httpx 添加验证和错误处理
5. 使用适当的请求/响应处理测试端点

详细指南：references/rest-api-patterns.md

实现数据库操作

步骤：

1. 设计数据库架构并创建表
2. 生成模型：goctl model mysql datasource -url="..." -table="users" -dir="./model"
3. 将模型注入 internal/svc/service_context.go 中的 ServiceContext
4. 在逻辑层使用 sqlx 方法（Insert、FindOne、Update、Delete）
5. 通过传递 ctx 正确处理事务和错误

详细指南：references/database-patterns.md

添加中间件

步骤：

1. 在 internal/middleware/ 目录中创建中间件函数
2. 在 .api 文件中定义中间件，或通过编程方式注册
3. 实现身份验证/授权逻辑
4. 通过 r.Context() 传递经过验证的数据
5. 使用适当的 HTTP 状态码处理错误

详细指南：references/rest-api-patterns.md

构建 RPC 服务

步骤：

1. 在 .proto 文件中定义服务，包括消息和 RPC
2. 生成代码：goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.
3. 在 internal/logic/ 中实现服务逻辑
4. 配置服务发现（etcd/consul/kubernetes）
5. 使用 RPC 客户端进行测试并处理错误

详细指南：references/rpc-patterns.md

生成 Swagger 文档

步骤：

1. 在入口 .api 文件中添加包含 Swagger 元数据（标题、主机、basePath、协议）的 info 块
2. 在 @server 块中添加 tags，以便在 Swagger UI 中分组
3. 为每个端点添加 @doc 摘要
4. 为请求/响应字段添加 example/options/range 标签
5. 运行 goctl api swagger --api entry.api --dir docs/swagger --filename api

详细指南：references/swagger-patterns.md

使用高性能数据结构

步骤：

1. 根据使用场景选择合适的数据结构：
   • LRU Cache 用于本地热点数据缓存
   • Ring Buffer 用于固定大小的日志/消息缓冲区
   • TimingWheel 用于超时/延迟任务管理
   • SafeMap 用于并发安全的键值存储
2. 从 github.com/zeromicro/go-zero/core/collection 导入
3. 根据内存限制配置容量/参数
4. 处理淘汰回调以清理资源（LRU Cache）
5. 监控内存使用情况，并在必要时重建（SafeMap）

详细指南：references/collection-patterns.md

⚡ 核心原则

生成或审查 go-zero 代码时，始终遵循以下原则：

✅ 始终遵循

• 三层分离：保持 Handler（路由）→ Logic（业务）→ Model（数据）各层独立
• 结构化错误：HTTP 错误使用 httpx.Error(w, err)，不要使用 fmt.Errorf
• 配置：使用 conf.MustLoad(&c, *configFile) 加载，并通过 ServiceContext 注入
• 上下文传递：通过所有层传递 ctx context.Context，以支持追踪和取消
• 类型安全：在 .api 文件中定义请求/响应类型，并使用 goctl 生成代码
• goctl 生成：始终使用 goctl 生成样板代码，不要手写处理器/路由

❌ 切勿这样做

• 将业务逻辑直接写在处理程序中（违反三层架构）
• 使用 w.Write() 或 fmt.Fprintf() 返回原始错误，而不使用 httpx 辅助函数
• 将配置值硬编码（端口、主机、数据库凭据）
• 跳过用户输入验证，或忘记检查 err != nil
• 修改生成的代码（应通过 logic 层进行自定义）
• 绕过 ServiceContext 注入（会导致耦合紧密和测试问题）

📖 渐进式学习路径

根据你的需求，遵循以下路径：

🟢 刚接触 go-zero？

1. 从这里开始：go-zero 官方快速入门 安装 go-zero，创建你的第一个 API，了解基本概念

2. 添加数据库：references/database-patterns.md 连接 MySQL/PostgreSQL，生成模型，实现 CRUD

🟡 正在构建生产服务？

1. 查看最佳实践：best-practices/overview.md 配置、日志记录、监控、安全检查清单

2. 增强弹性：references/resilience-patterns.md 熔断器、速率限制、优雅降级

3. 优化数据结构：references/collection-patterns.md LRU Cache、Ring Buffer、TimingWheel，提升性能

4. 检查常见陷阱：troubleshooting/common-issues.md 避免常见错误，并了解如何调试问题

5. 设置可观测性：references/observability.md Prometheus 指标、分布式追踪、结构化日志

🔴 高级场景？

1. 分布式事务：references/distributed-transactions.md DTM 集成、SAGA/TCC 模式、数据一致性

2. 消息队列：references/message-queue.md 使用 go-queue 进行异步处理、延迟任务、Kafka 集成

3. 性能优化：references/advanced-components.md Bloom filter、MapReduce、TimingWheel、SharedCalls

4. 理解设计：design/principles.md 框架理念、架构决策、反模式

5. 从示例中学习：examples/case-studies/looklook-overview.md 生产规模的架构、实际应用模式

🔵 扩展能力？

1. 与 Claude Code 搭配使用：getting-started/claude-code-guide.md 学习子 Agent、动态上下文和参数传递等高级功能 运行演示项目，验证你的环境

2. 验证知识：examples/verify-tutorial.sh 检查示例是否正常运行的脚本

🔗 与 go-zero AI 生态系统集成

此技能是面向 AI 辅助 go-zero 开发的双层生态系统的一部分：

工具	用途	最适合
ai-context	精简的工作流说明（约 5KB）	GitHub Copilot、Cursor、Windsurf
zero-skills（本仓库）	全面的知识库 + goctl 参考（约 45KB）	所有 AI 工具、深入学习、参考

AI 会直接在终端中运行 goctl 来生成代码，无需单独的 MCP 服务。完整的命令参考请见 references/goctl-commands.md。

在 Claude Code 中使用：

• 使用 go-zero 项目时，此技能会自动加载
• 使用 /zero-skills 手动调用，获取 go-zero 指引
• AI 会直接在终端中运行 goctl 命令来生成代码
• 需要时参考特定模式文件（Claude 会按需加载）

详细使用说明请见 getting-started/claude-code-guide.md。

🌐 其他资源

• 官方文档：go-zero.dev - 最新 API 参考和指南
• GitHub：zeromicro/go-zero - 源代码和示例
• 社区：欢迎在主仓库中参与讨论、提交问题和贡献代码

📝 版本兼容性

• 稳定版目标：go-zero v1.10.3（需要 Go 1.24 或更高版本）
• Master 兼容性：针对 go-zero master 分支进行测试时，请使用 Go 1.25 或更高版本
• 更新：定期更新模式，以反映框架的演进
• 破坏性变更：请查阅官方文档，了解不同版本间的 API 变更

---

快速调用：使用 /zero-skills，或询问“如何使用 go-zero 完成 [任务]？” 需要帮助？ 请参阅相应的模式指南，了解详细示例和说明。