# Go Zero Init

> 使用团队内部的脚手架工具 xlab-goctl 来初始化基于 go-zero 框架的项目。当用户需要创建新的 go-zero 微服务项目、快速搭建包含标准组件的项目结构，或询问如何使用 xlab-goctl 时使用此 skill。

- Skill: `migoxlab/go-zero-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add migoxlab/go-zero-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/migoxlab/go-zero-init/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: migoxlab (https://skillmd.com/u/migoxlab)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/migoxlab/go-zero-init

---

# Go-Zero 项目初始化 Skill

## 描述

这个 skill 帮助开发者使用团队内部的脚手架工具 `xlab-goctl` 来初始化基于 go-zero 框架的项目。当用户需要创建新的 go-zero 微服务项目时，应该使用这个 skill。

## 何时使用

在以下场景中使用这个 skill：

- 用户需要初始化一个新的 go-zero 项目
- 用户想要创建一个基于 go-zero 框架的微服务
- 用户需要快速搭建包含标准组件的 go-zero 项目结构
- 用户询问如何使用 xlab-goctl 或 go-zero 项目初始化

## 前置要求

在使用 xlab-goctl 之前，确保满足以下依赖：

1. **Golang**: >= 1.20
2. **Goctl**: version >= 1.6.3
3. **Git**: 已安装并配置
4. **网络**: 需要能够访问 GitHub

## 安装脚手架

首先安装 xlab-goctl 工具：

```bash
go install gitlab.pjlab.org.cn/cloud/xlab-goctl@latest
```

验证安装：

```bash
xlab-goctl version
```

## AI 交互指导

当用户请求初始化 go-zero 项目时，AI 必须遵循以下交互原则：

### ⚠️ 重要：必须停止执行并等待用户确认

**关键原则：当用户意图未明确或未提及可选功能时，AI 必须：**

1. **停止执行** - 不要执行任何初始化命令
2. **主动询问** - 向用户询问可选功能需求
3. **等待确认** - 明确告知用户"在您确认之前，我不会执行初始化命令"
4. **获得确认后执行** - 只有在用户明确回复后，才执行初始化命令

**禁止行为：**

- ❌ 禁止在询问后立即执行命令
- ❌ 禁止假设或猜测用户意图
- ❌ 禁止使用默认值自动执行
- ❌ 禁止在用户未回复时继续执行

### 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 可以直接执行命令，因为所有信息都已明确：
  ```bash
  xlab-goctl init my-service -r -s -o ./projects
  ```

### 3. 执行原则（必须严格遵守）

1. **用户意图明确时**：所有必需参数和可选参数都已明确 → 直接执行命令，无需询问
2. **用户意图不明确时**：
  - **必须停止执行**
  - **必须主动询问**缺失的信息或可选参数
  - **必须明确告知**"在您确认之前，我不会执行初始化命令"
  - **必须等待用户回复**，不要继续执行任何操作
  - **获得用户确认后**，才执行初始化命令
3. **用户未提供项目名称时**：
  - **必须停止执行**
  - **必须询问项目名称**（这是必需参数）
  - **必须等待用户提供项目名称**后才能继续

### 4. 标准询问模板

当需要询问用户时，使用以下模板：

```
好的，我将为您初始化 [项目名称] 项目。在开始之前，我需要确认一些信息：

[列出需要确认的可选功能或缺失信息]

**在您确认之前，我不会执行初始化命令。** 请告诉我您的选择。
```

**重要：询问后必须停止，等待用户回复，不要执行任何命令。**

## 初始化项目

### 基本用法

```bash
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. 基础项目初始化（默认配置）

```bash
xlab-goctl init my-service
```

这将创建一个包含以下功能的项目：

- 基于 go-zero 框架的完整工程
- 带有一个示例 API
- 基础 Makefile
- Nacos 配置中心支持（支持动态热更新）
- 全局统一的错误处理
- 全局统一的 response 格式
- MySQL 支持（默认）
- Auth 中间件（校验请求中的用户 ID）
- Metrics 中间件（针对推理服务的自定义指标）

#### 2. 指定输出目录

```bash
xlab-goctl init my-service --output-dir /path/to/your/project/dir
```

或使用短选项：

```bash
xlab-goctl init my-service -o /path/to/your/project/dir
```

#### 3. 启用 Redis 支持

```bash
xlab-goctl init my-service --with-redis
```

或使用短选项：

```bash
xlab-goctl init my-service -r
```

#### 4. 启用多个可选功能

```bash
xlab-goctl init my-service --with-redis --with-asyncinfer --with-sso
```

或使用短选项组合：

```bash
xlab-goctl init my-service -r -a -s
```

#### 5. 完整示例（指定目录并启用所有功能）

```bash
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 来生成：**

```bash
make genapi
```

**不要直接使用 goctl 命令生成代码**，否则可能会与项目模板不兼容。

### 版本要求

- SSO 功能需要 xlab-goctl V0.0.3 版本及以上
- CI/CD 功能（`--with-cicd`）暂未实现

## 工作流程示例

### 典型的新项目初始化流程

1. **安装工具**（如果尚未安装）:
  ```bash
   go install gitlab.pjlab.org.cn/cloud/xlab-goctl@latest
  ```
2. **初始化项目**:
  ```bash
   xlab-goctl init my-service -r -a -s -o ./my-service
  ```
3. **进入项目目录**:
  ```bash
   cd my-service
  ```
4. **编写 API 文件**（编辑 `.api` 文件）
5. **生成代码**:
  ```bash
   make genapi
  ```
6. **运行项目**:
  ```bash
   go run main.go
  ```

## 故障排查

### 问题：无法访问 GitHub

- **解决方案**: 确保网络可以访问 GitHub，xlab-goctl 需要从 GitHub 获取模板

### 问题：goctl 版本过低

- **解决方案**: 升级 goctl 到 1.6.3 或更高版本
  ```bash
  go install github.com/zeromicro/go-zero/tools/goctl@latest
  ```

### 问题：生成的代码与模板不匹配

- **解决方案**: 确保使用 `make genapi` 而不是直接使用 `goctl api go` 命令