---
name: std-go
description: 提供 Go 编码规范（基于 Google Go Style Guide）。当编写或 review Go 代码（.go 文件）时使用。
---

# Go 编码规范

> 基于 Google Golang 代码规范，结合实际工程经验进行了调整和补充。

## 规范等级定义

| 等级 | 定义 |
|------|------|
| **必须（Mandatory）** | 用户必须采用，代码扫描工具应将其视为错误 |
| **推荐（Preferable）** | 用户理应采用，但如有特殊情况可以不采用 |
| **可选（Optional）** | 用户可参考，自行决定是否采用 |

## 核心规则速查

| 类别 | 必须遵守 |
|------|----------|
| **格式化** | 使用 `gofmt` 格式化代码 |
| **import** | 使用 `goimports`，禁止相对路径导入，标准包在最上 |
| **错误处理** | 必须处理 `error`，`error` 必须是最后一个返回值 |
| **panic** | 禁止用于一般错误处理，仅用于不变量断言 |
| **命名** | 驼峰式，包名小写无下划线，文件名小写下划线分隔 |
| **注释** | 导出名字必须有文档注释，格式 `// Name 描述` |
| **switch** | 必须有 `default` 分支 |
| **goto** | 业务代码禁止使用 |
| **嵌套** | 深度不超过 4 层 |
| **代码行数** | 文件 ≤ 800 行，函数 ≤ 80 行 |
| **依赖管理** | 使用 `go modules` |

## 完整规范

详见 [reference/full-standards.md](reference/full-standards.md)，包含：
- 代码风格（格式化、换行、括号空格、import）
- 错误处理（error、panic、recover）
- 注释规范（包、结构体、方法、变量、常量、类型）
- 命名规范（包、文件、结构体、接口、变量、常量、函数）
- 控制结构（if、for、range、switch、return、goto）
- 函数规范（参数、defer、接收器、代码行数、嵌套、变量声明、魔法数字）
- 依赖管理和应用服务规范