Debian下Golang代码风格指南

Debian下Golang代码风格指南

一 环境与工具链

• 在 Debian 上安装工具：sudo apt update && sudo apt install -y golang-go。
• 使用 Go Modules 管理依赖：go mod init ；go mod tidy。
• 代码格式化与导入管理：使用 gofmt -w . 统一格式；使用 goimports（go get golang.org/x/tools/cmd/goimports）自动整理导入分组与删除未使用导入。
• 建议将 gofmt/goimports 配置为编辑器保存时自动执行，减少风格争议与人工操作成本。

二 格式与命名

• 格式化
  • 使用 gofmt 统一缩进、空格与换行；缩进使用 Tab，大括号与控制结构遵循 Go 默认风格；建议将行长度控制在 80 字符以内以提升可读性。
• 命名
  • 包名使用全小写、简洁且有意义（如：http、json），避免使用下划线或混合大小写。
  • 变量与函数采用 MixedCaps（小驼峰）；导出成员首字母大写，未导出成员小写。
  • 常量使用 全大写 + 下划线（如：MAX_RETRY）。
  • 接口名通常以 -er 结尾（如：Reader、Writer），保持接口小而精。

三 项目结构与依赖管理

• 推荐结构
  • myproject/
    • cmd/ 主程序入口（如：myapp/main.go）
    • internal/ 项目内部代码（不对外引用）
    • pkg/ 可复用的公共库
    • go.mod / go.sum 模块与校验文件
• 依赖管理
  • 使用 Go Modules 作为唯一来源；go mod tidy 保持依赖干净；避免将 vendor 作为常态，除非有离线或合规约束。

四 错误处理与并发

• 错误处理
  • 函数返回 error 作为最后一个返回值；调用后立即检查，避免忽略错误。
  • 使用 fmt.Errorf(“…: %w”, err) 包装错误以添加上下文；必要时进行类型断言或类型开关进行精细化处理。
• 并发
  • 遵循“不要通过共享内存来通信；通过通信来共享内存”的并发哲学；优先使用 channel 控制并发与同步。
  • 限制并发数量（如 信号量/有界缓冲通道/工作池），避免无界 goroutine 导致资源耗尽。
  • 在循环中启动 goroutine 时，注意循环变量捕获问题，通常通过传参或 req := req 方式复制变量。

五 质量保障与工程实践

• 静态检查与代码质量
  • 集成 golint、go vet、gocyclo、misspell、ineffassign、errcheck 等工具到本地与 CI，统一阻断低质量提交。
• 测试与文档
  • 编写 单元测试 与 基准测试（Benchmark）；为导出函数与包编写清晰的注释与示例，保持自文档化。
• 性能分析
  • 需要时引入 net/http/pprof，在 localhost:6060/debug/pprof 查看 CPU/内存/阻塞等剖析信息，定位瓶颈。