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；错误码分段规则与响应结构详见 common/skills/api-design 技能 - 请求参数绑定使用结构体标签（`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 压力