Go 语言开发规范与最佳实践指南

对于复杂返回值，建议先判断错误再处理其他变量，避免逻辑耦合：

x, y, err := f()
if err != nil {
    return err
}
if y == nil {
    return fmt.Errorf("some error")
}

Go 1.13+ 推荐使用 fmt.Errorf("module xxx: %w", err) 包装错误。

Panic 与 Recover

业务逻辑中严禁使用 panic。仅在 main 包且程序完全不可运行时（如数据库连接失败）才可使用。导出的接口不应包含 panic。

建议在 main 包中使用 log.Fatal 记录错误并结束程序。每个自行启动的 goroutine 必须在入口处捕获 panic 并打印堆栈信息：

package main

import "log"

func main() {
    defer func() {
        if err := recover(); err != nil {
            log.Println("exec panic error:", err)
        }
    }()
    getOne()
}

func getOne() {
    var arr = []string{"a", "b", "c"}
    log.Println(arr[4]) // 模拟越界
}

单元测试

测试文件命名为 example_test.go，函数以 Test 开头。重要导出函数需编写测试用例，并与代码一同提交以便回归测试。

类型断言

类型断言失败会触发 panic，因此始终使用'逗号 ok'惯用法：

// 错误
// t := i.(string)

// 正确
t, ok := i.(string)
if !ok {
    // 优雅处理
}

注释规范

编码阶段应同步编写变量、函数和包的注释，支持通过 godoc 生成文档。注释应为完整句子，以被注释内容开头，句点结尾。所有导出的大写标识符必须有文档注释。Code Review 前请删除注释掉的代码，除非有明确的后续处理计划。

包与结构体

每个包应有包注释。结构体及其可导出成员若有生僻词需单独注释。

// User 用户结构定义了用户基础信息
type User struct {
    Name string
    Email string
    // Demographic 族群
    Demographic string
}

方法与变量

导出方法需描述功能及调用方。导出常量和变量需在定义前或末尾添加简要介绍。

命名规范

统一的命名能显著提升可读性。好的命名本身就能传达足够信息。

• 包名：小写单词，多级目录划分，避免无意义名称（如 util, common）。
• 文件名：小写，下划线分割。
• 结构体：驼峰命名，名词短语，避免 Data, Info 等泛义词。
• 接口：单个函数加 er 后缀（如 Reader），多函数综合命名。
• 变量：驼峰式，布尔类型以 Has, Is, Can 开头。私有变量首字母小写。
• 常量：驼峰式，枚举类型需先定义类型。
• 函数：驼峰式，首字母根据访问控制决定大小写。

控制结构

If 语句

接受初始化语句建立局部变量。判断两个值时，变量在左，常量在右。Bool 变量直接判断真假，避免 == true。

For 循环

优先使用短声明建立局部变量。

Range

只需 Key 则丢弃 Value，反之亦然。

Switch

必须包含 default 分支。

Return

尽早返回，发生错误立即退出，减少嵌套层级。

Goto

业务代码禁止使用 goto，底层框架源码也建议慎用。

函数设计

参数与返回值

相同类型的两三个参数或含义不明确时，使用命名返回。参数数量不超过 5 个。尽量值传递，Map/Slice/Chan/Interface 不传指针。

Defer

资源管理紧跟 defer。确认无错后再 defer 释放。禁止在循环中使用 defer，防止资源泄漏。

接收器与方法

接收器命名超过 20 行函数时避免单字符，禁用 me, this, self。

复杂度控制

• 文件长度不超过 800 行。
• 函数长度不超过 80 行。
• 嵌套深度不超过 4 层，过深应抽取子函数。

魔法数字

重复出现的数字定义为常量。

依赖管理

Go 1.11+ 必须使用 go modules 模式。

go mod init github.com/org/myrepo

建议非开源工程使用内部域名作为 module name。使用 modules 的项目不提交 vendor 目录，但 go.sum 应纳入版本控制。

应用服务

• 建议提供 README.md，包含服务描述、使用方法、环境依赖等。
• 应用服务必须包含接口测试。

常用工具

Go 生态提供了丰富的工具辅助规范落地：

• gofmt：自动格式化代码，是格式规范的基准。
• goimports：在 gofmt 基础上增加自动导入包。
• go vet：静态分析源码问题，如未使用的变量、错误的 struct tag 等。
• golint：检测代码不规范之处，类似 JS 中的 jslint。

编译前执行这些工具能有效预防潜在问题。