# Golang 代码质量规范：遵守最佳实践并与 Claude Code 集成

Golang 代码质量规范：遵守最佳实践并与 Claude Code 集成

引言

这个规范旨在为 Golang（Go 语言）开发提供一个全面的代码质量指南，基于官方文档（如 Effective Go）和社区最佳实践（如 Google Go Style Guide）。它强调可读性、可维护性、安全性和性能，同时融入 Claude Code（Anthropic 的 AI 编码代理工具）的集成最佳实践。Claude Code 可以作为 AI 配对编程助手，帮助生成、审查和优化代码，尤其适合 Go 项目。

规范分为两部分：

1. 纯 Go 代码质量最佳实践：聚焦于编写习惯用法的 Go 代码。
2. 与 Claude Code 集成的最佳实践：如何利用 Claude Code 提升开发效率和质量。

这些实践适用于个人开发者、团队和大型项目。定期审查和自动化工具（如 linters）是关键。

第一部分：Go 代码质量最佳实践

以下是核心实践，按类别组织。目标是编写简洁、可靠且高效的代码。

1. 代码格式化

• 使用 gofmt：始终运行 go fmt 或 gofmt 来自动化格式化。避免手动调整缩进（使用制表符 tab）。
• 行长和换行：无严格行长限制，但长行应换行并额外缩进一个 tab。控制结构（如 if、for）无需括号。
• 括号和分号：开括号 { 置于同一行尾，避免自动分号插入问题。
• 注释：使用 // 行注释；包级文档使用 /* */ 或 godoc 风格。注释应解释“为什么”而非“是什么”。

2. 命名规范

• 包名：短小、全小写、单词（如 bytes、json）。避免重复包名在函数中。
• 导出名称：大写开头（如 Reader）。避免 Get 前缀（如 Owner() 而非 GetOwner()）。
• 接口名：单方法接口用方法名 + -er（如 Formatter）。
• 变量和函数：使用 MixedCaps（如 mixedCaps），避免下划线。函数名：动词式（如 WriteTo）或名词式（如 JobName）。
• 测试相关：测试包名加 test 后缀；存根用行为名（如 AlwaysCharges）。
• 避免阴影：小心使用 := 以防意外阴影标准库名。

3. 错误处理

• 返回错误：函数最后返回 error 类型。始终检查错误（避免忽略 _, err）。
• 结构化错误：使用自定义类型或哨兵值（如 errors.Is、errors.As）便于检查。包装错误用 %w 添加上下文（如 fmt.Errorf("read failed: %w", err)）。
• Panic 和 Recover：仅用于不可恢复错误（如初始化失败）。在 defer 中使用 recover 处理 goroutine 崩溃。
• 日志：记录错误时添加上下文，但让调用者决定传播。避免日志泛滥，使用速率限制。

4. 并发和数据结构

• 通信而非共享：使用通道（channels）传递数据，避免共享内存。goroutine 用 go 前缀启动。
• 通道：用 make 创建（如 make(chan int)）。无缓冲用于同步，有缓冲用于队列。
• 数据初始化：用 new(T) 或 &T{} 分配零值；make 用于 slice/map/channel。优先 slice 而非数组。
• 指针接收器：方法修改状态时用指针接收器；否则用值接收器。
• 嵌入：在结构体或接口中嵌入类型以复用方法。

5. 测试和质量保证

• 表驱动测试：使用表格输入/输出测试相似场景。
• 断言：直接用 t.Error/t.Fatalf，避免自定义助手。
• 钩子：使用 Git pre-commit 钩子运行 lint、test 和覆盖率检查。
• Linting：配置 .golangci.yml 强制规则（如无未用变量、复杂度限制）。
• TDD：先写测试，确认失败，再实现代码。覆盖率目标 >80%。

6. 其他实践

• 包设计：保持包专注（单一责任）。避免 util 包，用描述性名称。
• 全局状态：避免包级变量；优先实例状态和依赖注入。
• 字符串连接：简单用 +；复杂用 fmt.Sprintf 或 strings.Builder。
• 文档：非显见参数/行为需文档。使用标题、缩进和示例。
• 安全性：验证输入、用 HTML 模板防 XSS、保护 SQL 注入。

类别	关键规则	为什么重要
格式化	gofmt 自动化	一致性，提升可读性
命名	MixedCaps，无重复	简洁，减少认知负担
错误	始终检查，结构化	可靠性，易调试
并发	通道优先	避免数据竞争
测试	表驱动，钩子	质量保证，自动化

第二部分：与 Claude Code 集成的 Go 最佳实践

Claude Code 是 Anthropic 的 AI 工具，支持代码生成、审查和自动化。集成时，专注于计划-执行流程、上下文管理和 Go 特定结构。

1. 设置和基础

• 安装和初始化：全局安装 CLI（curl -fsSL https://claude.ai/install.sh | bash），项目中运行 claude 初始化。连接 Claude 账户或 API。
• CLAUDE.md 文件：在根目录创建，记录 Go 规范（如目录结构、lint 规则）、核心文件和测试指南。用 /init 自动生成。层次化（全局/项目/子文件夹）以覆盖具体指导。
• 目录结构：早定义 cmd/、pkg/、internal/ 等。提示 Claude 参考（如 “在 internal/handlers/ 创建 handler”）。
• 工具和插件：启用 MCP（外部工具，如数据库）、自定义命令（/commands）。安装 Go 相关插件（如 LSP for Go）。允许文件编辑和 Git 操作。
• .gitignore 和 Linting：让 Claude 生成 .gitignore 和 .golangci.yml，强制 Go 最佳实践。

2. 工作流优化

• 计划模式优先：新功能用 Shift+Tab 进入 Plan Mode，生成步骤计划（如 “ultrathink: 实现用户认证”）。确认后执行。
• TDD 流程：先让 Claude 写测试（避免 mocks），运行确认失败，提交；然后生成代码迭代通过。
• 子代理（Sub-Agents）：隔离任务（如一个写接口，一个写实现，一个审查）。Go 中用于并行处理服务/模型/测试。
• Git 集成：用分支/Worktrees 隔离任务。Claude 处理 commit、PR 和冲突。频繁提交以追踪变化。
• 审查和迭代：用子代理或第二 LLM 审查代码。简化测试输出总结失败。
• 上下文管理：具体提示（如引用文件、提供 URL/图像）。用 /clear 重置长会话；/compact 压缩上下文。

3. Go 特定集成提示

• 接口优先：定义接口，让 Claude 实现，确保模块化。
• Makefile：让 Claude 生成标准目标（如 make test）。
• API 开发：从 OpenAPI spec 开始，生成 handlers 和 DTOs。
• 自动模式：用 --dangerously-skip-permissions 生成样板代码（如 lint 修复），但在容器中运行以安全。
• 性能和质量：Claude 审计优化（如查询、包大小），生成 CI/CD（如 GitHub Actions）。

实践	与 Claude Code 集成	益处
计划执行	Plan Mode + 子代理	减少错误，提高效率
测试	TDD + 审查代理	覆盖率提升
文档	CLAUDE.md 自动生成	一致规范

通过这个规范，你的 Go 项目将更健壮，并利用 Claude Code 加速开发。定期更新 CLAUDE.md 以适应项目演进。