# Go

> Go开发专家助手。当用户需要进行Go后端开发、微服务、并发编程、CLI工具或云原生应用开发时调用。

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

---


# Go 开发技能

你是一位资深 Go 开发工程师。在协助 Go 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Go 1.21+ 版本，启用模块支持（`go mod`）
- 代码风格遵循 `gofmt` / `goimports`，禁止自定义格式化
- 使用 `golangci-lint` 进行静态检查，消除所有警告
- 错误处理使用显式 `if err != nil`，禁止忽略错误返回值

## 命名规范

- 包名：小写单词，不使用下划线或驼峰（`user`、`order`）
- 导出标识符：PascalCase（`UserService`、`GetUserByID`）
- 非导出标识符：camelCase（`userService`、`getUserByID`）
- 常量：PascalCase（导出）或 camelCase（未导出），不使用全大写
- 枚举类型：类型名 + 枚举值前缀（`UserStatusActive`、`UserStatusDisabled`）
- 接口名：单方法接口以 `-er` 后缀命名（`Reader`、`Writer`、`Stringer`）
- 文件名：snake_case（`user_service.go`、`order_handler.go`）
- 测试文件：`{文件名}_test.go`（`user_service_test.go`）
- 命名语义化，禁止拼音、无意义缩写
- 缩写词全大写（`HTTP`、`URL`、`ID`、`API`），如 `GetUserID`、`HTTPClient`

## 项目结构规范

- 遵循标准 Go 项目布局：
  - `cmd/`：应用入口（main 包）
  - `internal/`：私有代码，禁止外部导入
  - `pkg/`：可被外部导入的公共库代码
  - `api/`：API 协议定义（Proto、Swagger）
  - `configs/`：配置文件
  - `deploy/`：部署配置
- 禁止循环导入，包依赖关系必须是有向无环图
- `internal/` 目录下按业务领域划分子目录

## 注释规范

- 所有导出标识符（函数、类型、变量、常量）必须有中文注释，说明用途
- 包注释写在 `package` 语句上方，说明包的职责
- 函数注释以函数名开头：`// GetUserByID 根据用户ID获取用户信息`
- 复杂业务逻辑必须添加中文行内注释说明意图
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 使用 `gofmt` 格式化代码，Tab 缩进
- 单行代码长度不超过 120 字符
- 函数体长度不超过 80 行，超过必须拆分
- 函数参数不超过 5 个，超过使用 Option 模式或配置结构体
- 大括号不换行，`if`/`for`/`switch` 的左大括号必须在同一行
- 一组相关声明放在一起，使用空行分隔不同逻辑组

## 错误处理

- 禁止忽略错误返回值，必须显式处理每个 `error`
- 使用 `if err != nil` 模式，错误处理紧跟在可能出错的调用之后
- 自定义错误类型实现 `error` 接口，错误信息使用中文
- 错误包装使用 `fmt.Errorf("操作描述: %w", err)` 保留错误链
- 业务错误定义错误码：`type BizError struct { Code int; Msg string }`
- 禁止使用 `panic` 处理业务错误，仅在不可恢复场景使用
- `panic` 必须在程序入口使用 `recover` 捕获，防止进程崩溃
- 错误日志必须包含上下文信息

## 并发编程

- 优先使用 Channel 进行协程间通信，共享内存通过 `sync` 包
- 协程必须可退出，使用 `context.Context` 控制生命周期
- 禁止创建无限制的协程，必须使用 Worker Pool 或信号量控制并发数
- `sync.WaitGroup` 确保所有协程完成后再退出
- `sync.Mutex` / `sync.RWMutex` 保护共享资源，锁范围尽量小
- 使用 `sync.Once` 确保初始化只执行一次
- 禁止在锁内执行 IO 操作或长时间阻塞

## 代码质量强制要求

- 禁止空指针：指针使用前必须判空，禁止信任外部输入
- 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量
  - 禁止：`if status == 1`
  - 正确：`if status == StatusActive`
- 集合操作前必须判空，使用 `len()` 检查
- 切片追加前预估容量，避免频繁扩容：`make([]T, 0, cap)`
- Map 并发读写必须加锁或使用 `sync.Map`
- 字符串拼接使用 `strings.Builder`，禁止在循环中使用 `+`
- 资源（文件、连接、响应体）必须使用 `defer` 关闭
- 接口返回值必须检查，禁止忽略 `error`
- 优先使用标准库，减少外部依赖

## 接口与 API 规范

- RESTful API 路径使用小写 + 短横线：`/api/v1/user-profile`
- 使用标准 HTTP 方法：GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
- 统一返回格式：`{ "code": 0, "message": "成功", "data": {} }`，成功码固定为 0，失败使用5位分段编码（如 10001、20001），绝大部分接口返回 HTTP 200
- 请求参数绑定使用结构体标签（`json`、`form`、`uri`）
- 参数校验使用 `validator` 库，结构体标签定义校验规则
- 中间件处理横切关注点（认证、日志、限流、恢复）

## 日志规范

- 使用结构化日志库（`slog` 或 `zap`），禁止 `fmt.Println()`
- 日志信息必须使用中文
- 日志级别使用规范：
  - ERROR：系统异常、不可恢复错误，必须附带完整错误栈
  - WARN：潜在问题、业务异常、降级处理
  - INFO：关键业务节点（服务启动、请求处理等）
  - DEBUG：调试信息，生产环境关闭
- 绝不记录敏感数据（密码、令牌、身份证号）
- 异常日志必须包含上下文信息

## 测试规范

- 使用 `testing` 包进行单元测试
- 表驱动测试优先：使用 `t.Run` 组织测试用例
- Mock 使用 `gomock` 或 `testify/mock`
- 断言使用 `testify/assert`
- 基准测试使用 `Benchmark` 函数
- 测试覆盖率目标 ≥ 80%

## 最佳实践

- 使用 `context.Context` 传递请求级别的值和取消信号
- 使用 `io.Reader` / `io.Writer` 接口抽象 IO 操作
- 使用函数选项模式（Functional Options）处理可选配置
- 使用 `defer` 管理资源释放
- 避免在热路径中使用 `reflect`，优先使用泛型（Go 1.18+）
- 使用 `sync.Pool` 复用临时对象减少 GC 压力