migoxlab Go-Zero 项目初始化 Skill
描述
这个 skill 帮助开发者使用团队内部的脚手架工具 xlab-goctl 来初始化基于 go-zero 框架的项目。当用户需要创建新的 go-zero 微服务项目时，应该使用这个 skill。
何时使用
在以下场景中使用这个 skill：
- 用户需要初始化一个新的 go-zero 项目
- 用户想要创建一个基于 go-zero 框架的微服务
- 用户需要快速搭建包含标准组件的 go-zero 项目结构
- 用户询问如何使用 xlab-goctl 或 go-zero 项目初始化
前置要求
在使用 xlab-goctl 之前，确保满足以下依赖：
- Golang: >= 1.20
- Goctl: version >= 1.6.3
- Git: 已安装并配置
- 网络: 需要能够访问 GitHub
安装脚手架
首先安装 xlab-goctl 工具：
go install gitlab.pjlab.org.cn/cloud/xlab-goctl@latest
验证安装：
xlab-goctl version
AI 交互指导
当用户请求初始化 go-zero 项目时，AI 必须遵循以下交互原则：
⚠️ 重要：必须停止执行并等待用户确认
关键原则：当用户意图未明确或未提及可选功能时，AI 必须：
- 停止执行 - 不要执行任何初始化命令
- 主动询问 - 向用户询问可选功能需求
- 等待确认 - 明确告知用户"在您确认之前，我不会执行初始化命令"
- 获得确认后执行 - 只有在用户明确回复后，才执行初始化命令
禁止行为：
- ❌ 禁止在询问后立即执行命令
- ❌ 禁止假设或猜测用户意图
- ❌ 禁止使用默认值自动执行
- ❌ 禁止在用户未回复时继续执行
1. 主动询问可选参数
当用户意图未明确或未提及可选功能时，AI 必须停止执行并询问用户是否需要以下可选功能：
- Redis 支持 (
--with-redis/-r): 询问用户是否需要 Redis 缓存支持 - 大模型工程基座 (
--with-asyncinfer/-a): 询问用户是否需要集成 AsyncInferClient（用于大模型推理服务） - SSO 对接支持 (
--with-sso/-s): 询问用户是否需要 SSO 单点登录功能 - 输出目录 (
--output-dir/-o): 询问用户是否需要在指定目录生成项目（默认在当前目录）
2. 交互示例
场景 1：用户只提供了项目名称
- 用户："帮我初始化一个叫 user-service 的项目"
- AI 必须停止执行，并询问：
好的，我将为您初始化 user-service 项目。在开始之前，我需要确认一些可选功能： 请问您是否需要以下可选功能？ - Redis 支持（用于缓存） - 大模型工程基座 AsyncInferClient（用于推理服务） - SSO 单点登录支持 另外，您希望项目生成在哪个目录？（默认在当前目录） **在您确认之前，我不会执行初始化命令。** 请告诉我您的选择。 - 等待用户回复，不要执行任何命令
场景 2：用户明确指定了部分功能
- 用户："初始化一个项目，需要 Redis"
- AI 必须停止执行，并询问：
好的，我将为您初始化项目并启用 Redis 支持。在开始之前，我还需要确认： 请问您还需要： - 大模型工程基座 AsyncInferClient - SSO 单点登录支持 吗？ 另外，项目名称是什么？您希望项目生成在哪个目录？（默认在当前目录） **在您确认之前，我不会执行初始化命令。** 请告诉我您的选择。 - 等待用户回复，不要执行任何命令
场景 3：用户意图完全明确
- 用户："初始化 my-service 项目，需要 Redis 和 SSO，输出到 ./projects 目录"
- AI 可以直接执行命令，因为所有信息都已明确：
xlab-goctl init my-service -r -s -o ./projects
3. 执行原则（必须严格遵守）
- 用户意图明确时：所有必需参数和可选参数都已明确 → 直接执行命令，无需询问
- 用户意图不明确时：
- 必须停止执行
- 必须主动询问缺失的信息或可选参数
- 必须明确告知"在您确认之前，我不会执行初始化命令"
- 必须等待用户回复，不要继续执行任何操作
- 获得用户确认后，才执行初始化命令
- 用户未提供项目名称时：
- 必须停止执行
- 必须询问项目名称（这是必需参数）
- 必须等待用户提供项目名称后才能继续
4. 标准询问模板
当需要询问用户时，使用以下模板：
好的，我将为您初始化 [项目名称] 项目。在开始之前，我需要确认一些信息：
[列出需要确认的可选功能或缺失信息]
**在您确认之前，我不会执行初始化命令。** 请告诉我您的选择。
重要：询问后必须停止，等待用户回复，不要执行任何命令。
初始化项目
基本用法
xlab-goctl init [appName] $OPTIONS
参数说明
appName: 项目名称（必需）OPTIONS: 可选的功能特性选项
选项参数
| 选项 | 短选项 | 说明 |
|---|---|---|
--output-dir |
-o |
生成代码库位置，不填则默认在当前目录下生成 |
--with-redis |
-r |
启用 Redis 支持 |
--with-asyncinfer |
-a |
启用大模型工程基座 AsyncInferClient 支持 |
--with-sso |
-s |
启用 SSO 对接支持（V0.0.3 版本及以上支持） |
--with-cicd |
-c |
启用 CI/CD 支持（暂未实现） |
使用示例
1. 基础项目初始化（默认配置）
xlab-goctl init my-service
这将创建一个包含以下功能的项目：
- 基于 go-zero 框架的完整工程
- 带有一个示例 API
- 基础 Makefile
- Nacos 配置中心支持（支持动态热更新）
- 全局统一的错误处理
- 全局统一的 response 格式
- MySQL 支持（默认）
- Auth 中间件（校验请求中的用户 ID）
- Metrics 中间件（针对推理服务的自定义指标）
2. 指定输出目录
xlab-goctl init my-service --output-dir /path/to/your/project/dir
或使用短选项：
xlab-goctl init my-service -o /path/to/your/project/dir
3. 启用 Redis 支持
xlab-goctl init my-service --with-redis
或使用短选项：
xlab-goctl init my-service -r
4. 启用多个可选功能
xlab-goctl init my-service --with-redis --with-asyncinfer --with-sso
或使用短选项组合：
xlab-goctl init my-service -r -a -s
5. 完整示例（指定目录并启用所有功能）
xlab-goctl init my-service -o ./projects/my-service -r -a -s
项目结构说明
初始化后的项目包含以下核心功能：
1. 基础框架
- go-zero 框架: 完整的微服务框架支持
- 示例 API: 包含一个示例 API 供参考
2. 工程化支持
- Makefile: 提供统一的本地生成 API、编译、lint 等指令
make genapi: 生成 API 代码（重要：编写 API 文件后必须使用此命令生成代码）- 其他常用命令：编译、lint 等
3. 配置管理
- Nacos 配置中心: 支持配置的动态热更新
- 无需手动重启服务即可应用配置变更
4. 错误处理
- 全局统一错误处理: 提供组内规范的 error 库使用示例
- 无需额外手动将 err 置空，框架自动处理
5. 响应格式
- 全局统一 response 格式: 业务代码无需组装公共的 code、msg、trace_id 字段
- 仅返回业务内容结构即可，框架自动封装
6. 数据存储组件
MySQL（默认）
- 默认包含 MySQL 支持
- 已配置数据库连接和操作示例
Redis（可选）
- 通过
--with-redis或-r选项启用 - 提供 Redis 客户端和操作示例
7. 大模型工程基座（可选）
- AsyncInferClient: 通过
--with-asyncinfer或-a选项启用 - 支持大模型推理服务的集成
8. SSO 对接支持（可选）
通过 --with-sso 或 -s 选项启用，包含以下接口：
/users/getUserInfo: 获取用户信息/users/auth: 用户认证/users/logout: 用户登出
注意: 此功能需要 xlab-goctl V0.0.3 版本及以上支持
9. 中间件
Auth 中间件
- 对于需要鉴权的接口，校验请求中是否包括用户 ID
- 表示能够通过网关认证
Metrics 中间件
- 提供针对推理服务的自定义指标
- 支持监控和性能分析
重要注意事项
⚠️ 使用 Makefile 生成代码
由于改变了原始模板，在使用中编写了 API 文件后生成代码时务必使用 Makefile 来生成：
make genapi
不要直接使用 goctl 命令生成代码，否则可能会与项目模板不兼容。
版本要求
- SSO 功能需要 xlab-goctl V0.0.3 版本及以上
- CI/CD 功能（
--with-cicd）暂未实现
工作流程示例
典型的新项目初始化流程
- 安装工具（如果尚未安装）:
go install gitlab.pjlab.org.cn/cloud/xlab-goctl@latest
- 初始化项目:
xlab-goctl init my-service -r -a -s -o ./my-service
- 进入项目目录:
cd my-service
- 编写 API 文件（编辑
.api文件） - 生成代码:
make genapi
- 运行项目:
go run main.go
故障排查
问题：无法访问 GitHub
- 解决方案: 确保网络可以访问 GitHub，xlab-goctl 需要从 GitHub 获取模板
问题：goctl 版本过低
- 解决方案: 升级 goctl 到 1.6.3 或更高版本
go install github.com/zeromicro/go-zero/tools/goctl@latest
问题：生成的代码与模板不匹配
- 解决方案: 确保使用
make genapi而不是直接使用goctl api go命令