Go 语言编码规范

本规范旨在为日常Go项目开发提供一个代码的规范指导，方便团队形成一个统一的代码风格，提高代码的可读性，规范性和统一性。本规范将从命名规范，注释规范，代码风格和 Go 语言提供的常用的工具这几个方面做一个说明。该规范参考了 go 语言官方代码的风格制定。

1 命名规范

命名是代码规范中很重要的一部分，统一的命名规则有利于提高的代码的可读性，好的命名仅仅通过命名就可以获取到足够多的信息。

1.1 包命名

保持package的名字和目录保持一致，尽量采取有意义的包名，简短，有意义，尽量和标准库不要冲突。包名应该为小写单词，不要使用下划线或者混合大小写。

1.2 文件命名

尽量采取有意义的文件名，简短，有意义，应该为小写单词，使用下划线分隔各个单词。

1.3 结构体命名

采用驼峰命名法，首字母根据访问控制大写或者小写

struct 申明和初始化格式采用多行，例如下面：

// 多行申明
type User struct{
Username  string
Email     string
}

// 多行初始化
u := User{
Username: "astaxie",
Email:    "astaxie@gmail.com",
}

1.4 接口命名

命名规则基本和上面的结构体类型

单个函数的结构名以 “er” 作为后缀，例如 Reader , Writer 。

type Reader interface {
Read(p []byte) (n int, err error)
}

1.5 变量命名

和结构体类似，变量名称一般遵循驼峰法，首字母根据访问控制原则大写或者小写，但遇到特有名词时，需要遵循以下规则：

如果变量为私有，且特有名词为首个单词，则使用小写，如 apiClient

其它情况都应当使用该名词原有的写法，如 APIClient、repoID、UserID

错误示例：UrlArray，应该写成 urlArray 或者 URLArray

若变量类型为 bool 类型，则名称应以 Has, Is, Can 或 Allow 开头

var isExist bool
var hasConflict bool
var canManage bool
var allowGitHook bool

1.6 常量命名

常量均需使用全部大写字母组成，并使用下划线分词

const APP_VER = "1.0"

如果是枚举类型的常量，需要先创建相应类型：

type Scheme string

const (
HTTP  Scheme = "http"
HTTPS Scheme = "https"
)

2 注释

注释可以帮我们很好的完成文档的工作，写得好的注释可以方便我们以后的维护。和其他语言类似，go 语言也提供了

/**/

的块注释和

//

的单行注释两种注释风格， 在我们的项目中为了风格的统一，全部使用单行注释。go 语言自带的 godoc 工具可以根据注释生成文档，生成可以自动生成对应的网站（ golang.org 就是使用 godoc 工具直接生成的），注释的质量决定了生成的文档的质量。下面从包注释、结构体（接口）注释、函数（方法）注释、代码逻辑注释以及注释规范方面进行说明。

2.1 包注释

每个包都应该有一个包注释，一个位于package子句之前的块注释或行注释。包如果有多个go文件，只需要出现在一个go文件中（一般是和包同名的文件）即可。 包注释应该包含下面基本信息(请严格按照这个顺序，简介，创建人，创建时间）：

包的基本简介（包名，简介）

创建者，格式： 创建人： rtx 名

创建时间，格式：创建时间： yyyyMMdd

例如

util

包的注释示例如下

// util 包， 该包包含了项目共用的一些常量，封装了项目中一些共用函数。
// 创建人： barryqiu
// 创建时间： 20171125

2.2 结构（接口）注释

每个自定义的结构体或者接口都应该有注释说明，该注释对结构进行简要介绍，放在结构体定义的前一行，格式为： 结构体名， 结构体说明。同时结构体内的每个成员变量都要有说明，该说明放在成员变量的后面（注意对齐），实例如下：

// User ， 用户对象，定义了用户的基础信息
type User struct{
Username  string // 用户名
Email     string // 邮箱
}

2.3 函数（方法）注释

每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明，函数的注释应该包括三个方面（严格按照此顺序撰写）：

简要说明，格式说明：以函数名开头，“，”分隔说明部分

参数列表：每行一个参数，参数名开头，“，”分隔说明部分

返回值： 每行一个返回值

示例如下：

// NewtAttrModel ， 属性数据层操作类的工厂方法
// 参数：
//      ctx ： 上下文信息
// 返回值：
//      属性操作类指针
func NewAttrModel(ctx *common.Context) *AttrModel {
}

2.4 代码逻辑注释

对于一些关键位置的代码逻辑，或者局部较为复杂的逻辑，需要有相应的逻辑说明，方便其他开发者阅读该段代码，实例如下：

// 从 Redis 中批量读取属性，对于没有读取到的 id ， 记录到一个数组里面，准备从 DB 中读取
xxxxx
xxxxxxx
xxxxxxx

2.5 注释风格

统一使用中文注释，对于中英文字符之间严格使用空格分隔， 这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔，例如：

// 从 Redis 中批量读取属性，对于没有读取到的 id ， 记录到一个数组里面，准备从 DB 中读取

上面 Redis 、 id 、 DB 和其他中文字符之间都是用了空格分隔。

* 全部使用单行注释，禁止使用多行注释（代码规范就是要独裁，要定死，让我们不用纠结应该用哪个）；

* 和代码的规范一样，单行注释不要过长，禁止超过 120 字符。

3 代码风格

3.1 缩进和折行

缩进直接使用 gofmt 工具格式化即可（gofmt 应该是使用 tab 缩进的）；

折行方面，一行最长不超过120个字符，超过的请使用换行展示，尽量保持格式优雅。

3.2 括号和空格

括号和空格方面，也可以直接使用 gofmt 工具格式化（go 会强制左大括号不换行，换行会报语法错误），所有的运算符和操作数之间要留空格。

// 正确的方式
if a > 0 {

}

// 错误的方式
if a>0  // a ，0 和 > 之间应该空格
{       // 左大括号不可以换行，会报语法错误

}

3.3 import 规范

如果你的包引入了三种类型的包，标准库包，程序内部包，第三方包，建议采用如下方式进行组织你的包，每种之间用空行分隔

package main

import (
"fmt"
"os"

"kmg/a"
"kmg/b"

"code.google.com/a"
"github.com/b"
)

在项目中不要使用相对路径引入包：

// 错误示例
import “../net”

// 正确的做法
import “github.com/repo/proj/src/net”

3.4 错误处理

错误处理的原则就是不能丢弃任何有返回err的调用，不要使用

_

丢弃，必须全部处理。接收到错误，要么返回err，或者使用log记录下来

尽早return：一旦有错误发生，马上返回

尽量不要使用panic，除非你知道你在做什么

错误描述如果是英文必须为小写，不需要标点结尾

采用独立的错误流进行处理

// 错误写法
if err != nil {
// error handling
} else {
// normal code
}

// 正确写法
if err != nil {
// error handling
return // or continue, etc.
}
// normal code

3.5 测试

单元测试文件名命名规范为 example_test.go

测试用例的函数名称必须以 Test 开头，例如：TestExample

每个重要的函数都要首先编写测试用例，测试用例和正规代码一起提交方便进行回归测试

4 常用工具

上面提到了很过规范， go 语言本身在代码规范性这方面也做了很多努力，很多限制都是强制语法要求，例如左大括号不换行，引用的包或者定义的变量不使用会报错，此外 go 还是提供了很多好用的工具帮助我们进行代码的规范，

gofmt

大部分的格式问题可以通过gofmt解决， gofmt 自动格式化代码，保证所有的 go 代码与官方推荐的格式保持一致，于是所有格式有关问题，都以 gofmt 的结果为准。

goimport

我们强烈建议使用 goimport ，该工具在 gofmt 的基础上增加了自动删除和引入包.

go get golang.org/x/tools/cmd/goimports

go vet

vet工具可以帮我们静态分析我们的源码存在的各种问题，例如多余的代码，提前return的逻辑，struct的tag是否符合标准等。

go get golang.org/x/tools/cmd/vet

使用如下：

go vet .