Go语言代码规范指导

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

1、 命名规范

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

Go在命名时以字母a到Z或a到Z或下划线开头，后面跟着零或更多的字母、下划线和数字(0到9)。Go不容许在命名时中使用@、$和%等标点符号。Go是一种区分大小写的编程语言。所以，Manpower和manpower是两个不一样的命名。

1. 当命名（包括常量、变量、类型、函数名、结构字段等等）以一个大写字母开头，如：Group1，那么使用这种形式的标识符的对象就能够被外部包的代码所使用（客户端程序须要先导入这个包），这被称为导出（像面向对象语言中的 public）；
2. 命名若是以小写字母开头，则对包外是不可见的，可是他们在整个包的内部是可见而且可用的（像面向对象语言中的 private ）

一、包命名：package

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

package demo
​
package main

二、 文件命名

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

my_test.go

三、 结构体命名

• 采用驼峰命名法，首字母根据访问控制大写或者小写
• struct 申明和初始化格式采用多行，例以下面：

// 多行申明
type User struct{
    Username  string
    Email     string
}
​
// 多行初始化
u := User{
    Username: "astaxie",
    Email:    "astaxie@gmail.com",
}

四、 接口命名

• 命名规则基本和上面的结构体类型
• 单个函数的结构名以 “er” 做为后缀，例如 Reader , Writer 。

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

五、变量命名

• 和结构体相似，变量名称通常遵循驼峰法，首字母根据访问控制原则大写或者小写，但遇到特有名词时，须要遵循如下规则： 
• 若是变量为私有，且特有名词为首个单词，则使用小写，如 apiClient
• 其它状况都应当使用该名词原有的写法，如 APIClient、repoID、UserID
• 错误示例：UrlArray，应该写成 urlArray 或者 URLArray
• 若变量类型为 bool 类型，则名称应以 Has, Is, Can 或 Allow 开头

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

六、常量命名

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

const APP_VER = "1.0"

若是是枚举类型的常量，须要先建立相应类型：

type Scheme string
​
const (
    HTTP  Scheme = "http"
    HTTPS Scheme = "https"
)

七、 关键字

下面的列表显示了Go中的保留字。这些保留字不能用做常量或变量或任何其余标识符名称

2、注释

Go提供C风格的/* */块注释和C ++风格的//行注释。行注释是常态；块注释主要显示为包注释，但在表达式中颇有用或禁用大量代码。

• 单行注释是最多见的注释形式，你能够在任何地方使用以 // 开头的单行注释
• 多行注释也叫块注释，均已以 /* 开头，并以 */ 结尾，且不能够嵌套使用，多行注释通常用于包的文档描述或注释成块的代码片断

go 语言自带的 godoc 工具能够根据注释生成文档，生成能够自动生成对应的网站（ http://golang.org就是使用 godoc 工具直接生成的），注释的质量决定了生成的文档的质量。每一个包都应该有一个包注释，在package子句以前有一个块注释。对于多文件包，包注释只须要存在于一个文件中，任何一个均可以。包评论应该介绍包，并提供与整个包相关的信息。它将首先出如今godoc页面上，并应设置下面的详细文档。

详细的如何写注释能够 参考：http://golang.org/doc/effective_go.html#commentary

一、包注释

每一个包都应该有一个包注释，一个位于package子句以前的块注释或行注释。包若是有多个go文件，只须要出如今一个go文件中（通常是和包同名的文件）便可。 包注释应该包含下面基本信息(请严格按照这个顺序，简介，建立人，建立时间）：

• 包的基本简介（包名，简介）
• 建立者，格式： 建立人： rtx 名
• 建立时间，格式：建立时间： yyyyMMdd

例如 util 包的注释示例以下

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

二、结构（接口）注释

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

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

三、函数（方法）注释

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

• 简要说明，格式说明：以函数名开头，“，”分隔说明部分
• 参数列表：每行一个参数，参数名开头，“，”分隔说明部分
• 返回值： 每行一个返回值

示例以下：

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

四、代码逻辑注释

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

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

五、注释风格

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

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

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

• 建议所有使用单行注释
• 和代码的规范同样，单行注释不要过长，禁止超过 120 字符。

3、代码风格

一、缩进和折行

• 缩进直接使用 gofmt 工具格式化便可（gofmt 是使用 tab 缩进的）；
• 折行方面，一行最长不超过120个字符，超过的请使用换行展现，尽可能保持格式优雅。

咱们使用Goland开发工具，能够直接使用快捷键：ctrl+alt+L，便可。

二、语句的结尾

Go语言中是不须要相似于Java须要冒号结尾，默认一行就是一条数据

若是你打算将多个语句写在同一行，它们则必须使用 ;

三、括号和空格

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

// 正确的方式
if a > 0 {
​
} 
​
// 错误的方式
if a>0  // a ，0 和 > 之间应该空格
{       // 左大括号不能够换行，会报语法错误
​
}
​

四、import 规范

import在多行的状况下，goimports会自动帮你格式化，可是咱们这里仍是规范一下import的一些规范，若是你在一个文件里面引入了一个package，仍是建议采用以下格式：

import (
    "fmt"
)

若是你的包引入了三种类型的包，标准库包，程序内部包，第三方包，建议采用以下方式进行组织你的包：

import (
    "encoding/json"
    "strings"
​
    "myproject/models"
    "myproject/controller"
    "myproject/utils"
​
    "github.com/astaxie/beego"
    "github.com/go-sql-driver/mysql"
)   

有顺序的引入包，不一样的类型采用空格分离，第一种实标准库，第二是项目包，第三是第三方包。

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

// 这是很差的导入
import “../net”
​
// 这是正确的作法
import “github.com/repo/proj/src/net”

可是若是是引入本项目中的其余包，最好使用相对路径。

五、错误处理

• 错误处理的原则就是不能丢弃任何有返回err的调用，不要使用 _ 丢弃，必须所有处理。接收到错误，要么返回err，或者使用log记录下来
• 尽早return：一旦有错误发生，立刻返回
• 尽可能不要使用panic，除非你知道你在作什么
• 错误描述若是是英文必须为小写，不须要标点结尾
• 采用独立的错误流进行处理

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

六、测试

单元测试文件名命名规范为 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 .