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：

go version

安装 golangci-lint v1.64.8：

# 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，与低版本存在一些较大变化，不建议立刻升级。

验证安装

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. 检测命令说明

基本检测命令

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

自动修复命令

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

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

检测特定文件或目录

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

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

查看帮助

golangci-lint --help

常用检测场景

1. 新代码生成后检测

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

golangci-lint -v run

2. 修改现有代码后检测

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

golangci-lint -v run

3. 批量检测整个项目

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

golangci-lint -v run ./...

4. 检测特定包

检测特定包的代码：

golangci-lint -v run ./internal/service

常见问题处理

问题 1：import 排序问题

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

解决方案：

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

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

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

解决方案：

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

问题 3：错误处理缺失

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

解决方案：

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

问题 4：命名规范问题

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

解决方案：

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

问题 5：代码复杂度问题

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

解决方案：

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

集成到开发流程

在 CI/CD 中集成

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

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

在 Makefile 中集成

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

.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. 如果是误报，需要人为向团队反馈规则误报，不能随意更改规则文件