# Golangci Lint

> 使用团队内部的 golangci-lint 配置进行 Go 代码规范检测和自动修复。在每次生成或修改 Go 代码后，自动执行代码规范检测，并根据检测结果修正代码规范问题。当用户需要检查 Go 代码规范、修复 lint 问题，或确保代码符合团队规范时使用此 skill。

- Skill: `migoxlab/golangci-lint` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add migoxlab/golangci-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/migoxlab/golangci-lint/raw
- Safety review: pending (external: skill-scanner WARNING, 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/golangci-lint

---

# Go 代码规范检测 Skill

## 描述

这个 skill 帮助开发者使用团队内部的 golangci-lint 配置来检测和修复 Go 代码规范问题。当 AI 生成或修改 Go 代码后，会自动执行代码规范检测，并根据检测结果修正代码规范问题。

## 何时使用

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

- AI 生成或修改了 Go 代码后，需要自动检测代码规范
- 用户需要检查现有 Go 代码的规范问题
- 用户需要修复代码中的 lint 问题
- 用户需要确保代码符合团队内部的代码规范
- 用户询问如何使用 golangci-lint 或代码规范检测

## 前置要求

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

1. **Golang**: <= 1.24.0（重要：必须使用 1.24.0 或更低版本）
2. **golangci-lint**: v1.64.8（与 Go 版本匹配，避免引入最新版本的 Go）
3. **项目配置**: 项目根目录需要有 `.golangci.yml` 配置文件

## 安装 golangci-lint

### 安装步骤

首先确保已安装 Go 环境，且版本 <= 1.24.0：

```bash
go version
```

安装 golangci-lint v1.64.8：

```bash
# binary will be $(go env GOPATH)/bin/golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.64.8
```

**注意**：这里使用 v1.64.8 版本的 golangci-lint，与 Go 版本匹配，否则会被引入最新版本的 Go，与低版本存在一些较大变化，不建议立刻升级。

### 验证安装

```bash
golangci-lint --version
```

查看版本号确保安装成功，应该显示类似：

```
golangci-lint has version v1.64.8 built with go1.24.0 from ...
```

## 配置文件

### 使用团队内部配置

项目根目录需要有 `.golangci.yml` 配置文件。如果项目中没有此文件，可以从 skill 目录下的 `template/.golangci.yml` 模板复制到项目根目录。

### 配置说明

团队内部的 `.golangci.yml` 配置包含以下 linter：

- **errcheck**: 检查错误处理
- **goimports**: 自动格式化 import 语句
- **revive**: Go 代码风格检查（替代 golint）
- **govet**: Go 官方 vet 工具
- **staticcheck**: 静态代码分析
- **misspell**: 拼写检查

详细的配置规则请参考项目根目录的 `.golangci.yml` 文件。

## AI 交互指导

### ⚠️ 重要：自动执行代码规范检测

**关键原则：在每次生成或修改 Go 代码后，AI 必须：**

1. **检查配置文件** - 在执行检测前，检查项目根目录是否存在 `.golangci.yml` 文件
  - 如果不存在，自动从 skill 目录下的 `template/.golangci.yml` 模板复制到项目根目录
2. **自动执行检测** - 在代码生成完成后，立即执行 `golangci-lint -v run` 进行代码规范检测
3. **分析检测结果** - 仔细分析 lint 检测的输出结果
4. **自动修复问题** - 对于可以自动修复的问题，执行 `golangci-lint -v run --fix` 进行自动修复
5. **手动修复剩余问题** - 对于无法自动修复的问题，根据检测结果手动修正代码
6. **验证修复结果** - 修复后再次运行检测，确保所有问题都已解决

**禁止行为：**

- ❌ 禁止跳过代码规范检测
- ❌ 禁止忽略 lint 检测结果
- ❌ 禁止在检测到问题后不进行修复
- ❌ 禁止在修复后不验证结果

### 1. 标准工作流程

**当 AI 生成或修改 Go 代码后，必须遵循以下流程：**

1. **生成代码** - 完成用户请求的代码生成或修改
2. **检查配置文件** - 检查项目根目录是否存在 `.golangci.yml` 文件
  - 如果不存在，从 skill 目录下的template/.golangci.yml模板复制到项目根目录
  - 如果存在，继续下一步
3. **执行检测** - 运行 `golangci-lint -v run` 检测代码规范
4. **分析结果** - 查看检测输出，识别所有问题
5. **自动修复** - 运行 `golangci-lint -v run --fix` 自动修复可修复的问题
6. **手动修复** - 对于无法自动修复的问题，根据检测结果修改代码
7. **再次检测** - 运行 `golangci-lint -v run` 验证所有问题已解决
8. **报告结果** - 向用户报告检测和修复的结果

### 2. 执行示例

**场景 1：生成新代码后**

```
[AI 生成代码]

检查配置文件...

[检查: 项目根目录是否存在 .golangci.yml]

如果配置文件不存在：
[从 skill 目录下的template/.golangci.yml模板复制到项目根目录]

现在执行代码规范检测...

[执行: golangci-lint -v run]

检测到以下问题：
- [文件路径]:[行号]:[列号]: [问题描述] ([linter名称])

正在自动修复可修复的问题...

[执行: golangci-lint -v run --fix]

已自动修复部分问题。现在手动修复剩余问题...

[AI 根据检测结果修改代码]

再次验证修复结果...

[执行: golangci-lint -v run]

✅ 所有代码规范问题已解决！
```

**场景 2：修改现有代码后**

```
[AI 修改代码]

执行代码规范检测以确保修改后的代码符合规范...

[执行: golangci-lint -v run]

检测结果：无问题 ✅
```

### 3. 处理检测结果

**当检测到问题时：**

1. **可自动修复的问题**（如 import 排序、格式问题）：
  - 执行 `golangci-lint -v run --fix` 自动修复
  - 验证修复结果
2. **需要手动修复的问题**（如逻辑错误、命名问题）：
  - 仔细阅读检测输出的问题描述
  - 根据团队规范修改代码
  - 重新运行检测验证
3. **误报或特殊情况**：
  - 如果确认是误报，可以在 `.golangci.yml` 中添加排除规则
  - 但应优先修复代码，避免过度排除

### 4. 检测命令说明

#### 基本检测命令

```bash
# 详细模式运行检测
golangci-lint -v run
```

#### 自动修复命令

```bash
# 自动修复部分问题（依赖 lint 工具支持）
golangci-lint -v run --fix
```

**注意**：`--fix` 选项只能修复部分问题（如 import 排序、格式等），对于逻辑问题、命名问题等需要手动修复。

#### 检测特定文件或目录

```bash
# 检测特定文件
golangci-lint -v run path/to/file.go

# 检测特定目录
golangci-lint -v run path/to/directory/
```

#### 查看帮助

```bash
golangci-lint --help
```

## 常用检测场景

### 1. 新代码生成后检测

当 AI 生成新的 Go 文件或函数后，必须执行检测：

```bash
golangci-lint -v run
```

### 2. 修改现有代码后检测

当 AI 修改了现有 Go 代码后，必须执行检测：

```bash
golangci-lint -v run
```

### 3. 批量检测整个项目

检测整个项目的代码规范：

```bash
golangci-lint -v run ./...
```

### 4. 检测特定包

检测特定包的代码：

```bash
golangci-lint -v run ./internal/service
```

## 常见问题处理

### 问题 1：import 排序问题

**症状**：检测输出显示 import 排序不正确

**解决方案**：

```bash
# 自动修复
golangci-lint -v run --fix
```

### 问题 2：未使用的变量或导入

**症状**：检测输出显示未使用的变量或导入

**解决方案**：

- 删除未使用的变量或导入
- 如果确实需要保留（如接口实现），可以使用 `_` 忽略

### 问题 3：错误处理缺失

**症状**：检测输出显示函数调用后未检查错误

**解决方案**：

- 添加适当的错误检查和处理逻辑
- 根据业务需求决定是返回错误还是记录日志

### 问题 4：命名规范问题

**症状**：检测输出显示变量、函数或类型命名不符合规范

**解决方案**：

- 根据 Go 命名规范修改名称
- 公开的标识符使用大写字母开头
- 私有的标识符使用小写字母开头

### 问题 5：代码复杂度问题

**症状**：检测输出显示函数过于复杂

**解决方案**：

- 重构函数，拆分为更小的函数
- 减少嵌套层级
- 提取公共逻辑

## 集成到开发流程

### 在 CI/CD 中集成

在 CI/CD 流程中添加代码规范检测：

```yaml
# .gitlab-ci.yml 示例
lint:
  stage: test
  script:
    - golangci-lint -v run
  only:
    - merge_requests
    - main
```

### 在 Makefile 中集成

在项目的 Makefile 中添加 lint 命令：

```makefile
.PHONY: lint
lint:
	golangci-lint -v run

.PHONY: lint-fix
lint-fix:
	golangci-lint -v run --fix
```

## 工作流程示例

### 典型的新功能开发流程

1. **AI 生成代码** - 根据用户需求生成新的 Go 代码
2. **检查配置文件** - AI 检查项目根目录是否存在 `.golangci.yml` 文件
  - 如果不存在，自动从 skill 目录下的 `template/.golangci.yml` 模板复制到项目根目录
3. **自动检测** - AI 自动执行 `golangci-lint -v run`
4. **自动修复** - AI 执行 `golangci-lint -v run --fix` 修复可修复的问题
5. **手动修复** - AI 根据检测结果手动修复剩余问题
6. **验证结果** - AI 再次运行检测，确保所有问题已解决
7. **提交代码** - 用户确认后提交代码

### 代码审查流程

1. **接收代码变更** - 用户提供需要审查的代码
2. **执行检测** - 运行 `golangci-lint -v run` 检测代码规范
3. **分析问题** - 分析检测结果，识别需要修复的问题
4. **提供建议** - 向用户报告检测结果和修复建议
5. **协助修复** - 帮助用户修复代码规范问题

## 故障排查

### 问题：golangci-lint 未找到

**症状**：执行命令时提示 `command not found`

**解决方案**：

1. 检查是否已安装：`golangci-lint --version`
2. 检查 PATH 环境变量是否包含 `$(go env GOPATH)/bin`
3. 重新安装：按照安装步骤重新安装

### 问题：版本不匹配

**症状**：检测时出现版本相关错误

**解决方案**：

1. 确保使用 v1.64.8 版本：`golangci-lint --version`
2. 确保 Go 版本 <= 1.24.0：`go version`
3. 如果版本不匹配，重新安装指定版本

### 问题：配置文件未找到

**症状**：检测时提示配置文件不存在

**解决方案**：

1. 确保项目根目录有 `.golangci.yml` 文件
2. 如果不存在，从 skill 目录下的 `template/.golangci.yml` 模板复制到项目根目录
3. **AI 自动处理**：AI 在执行检测前会自动检查配置文件，如果不存在会自动从 skill 目录下的 `template/.golangci.yml` 模板复制到项目根目录

### 问题：检测速度慢

**症状**：检测执行时间过长

**解决方案**：

1. 检查配置中的 `deadline` 设置（默认 5m）
2. 使用 `--fast` 选项进行快速检测（但可能遗漏部分问题）
3. 只检测修改的文件或目录

### 问题：误报问题

**症状**：检测结果中包含明显误报

**解决方案**：

1. 确认是否为真正的误报
2. 如果是误报，需要人为向团队反馈规则误报，不能随意更改规则文件