golandgotest_Go语言编码规范

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

命名规范

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

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

当命名(包括常量、变量、类型、函数名、结构字段等等)以一个大写字母开头&＃xff0c;如&＃xff1a;Group1&＃xff0c;那么使用这种形式的标识符的对象就可以被外部包的代码所使用(客户端程序需要先导入这个包)&＃xff0c;这被称为导出(像面向对象语言中的 public)。 命名如果以小写字母开头&＃xff0c;则对包外是不可见的&＃xff0c;但是他们在整个包的内部是可见并且可用的(像面向对象语言中的 private )。

包命名

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

package demopackage main

文件命名

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

my_test.go

结构体命名

采用驼峰命名法&＃xff0c;首字母根据访问控制大写或者小写。

struct 申明和初始化格式采用多行&＃xff0c;例如下面&＃xff1a;

// 多行申明type User struct{ Username string Email string}​// 多行初始化u :&＃61; User{ Username: "avatar", Email: "avatar&＃64;gmail.com",}

接口命名

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

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

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

变量命名

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

var isExist boolvar hasConflict boolvar canManage boolvar allowGitHook bool

常量命名

常量均需使用全部大写字母组成&＃xff0c;并使用下划线分词。

const APP_VER &＃61; "1.0"

如果是枚举类型的常量&＃xff0c;需要先创建相应类型&＃xff1a;

type Scheme string​const ( HTTP Scheme &＃61; "http" HTTPS Scheme &＃61; "https")

关键字

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

注释

Go提供C风格的/ /块注释和C &＃43;&＃43;风格的//行注释。行注释是常态&＃xff1b;块注释主要显示为包注释&＃xff0c;但在表达式中很有用或禁用大量代码。

• 单行注释是最常见的注释形式&＃xff0c;你可以在任何地方使用以 // 开头的单行注释
• 多行注释也叫块注释&＃xff0c;均已以 / 开头&＃xff0c;并以 / 结尾&＃xff0c;且不可以嵌套使用&＃xff0c;多行注释一般用于包的文档描述或注释成块的代码片段

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

详细的如何写注释可以 参考&＃xff1a;http://golang.org/doc/effective_go.html#commentary

包注释

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

• 包的基本简介(包名&＃xff0c;简介)
• 创建者&＃xff0c;格式&＃xff1a; 创建人&＃xff1a; rtx 名
• 创建时间&＃xff0c;格式&＃xff1a;创建时间&＃xff1a; yyyyMMdd

例如 util 包的注释示例如下:

// util 包&＃xff0c; 该包包含了项目共用的一些常量&＃xff0c;封装了项目中一些共用函数。// 创建人&＃xff1a; xlli5// 创建时间&＃xff1a; 20190522

结构(接口)注释

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

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

函数(方法)注释

每个函数&＃xff0c;或者方法(结构体或者接口下的函数称为方法)都应该有注释说明&＃xff0c;函数的注释应该包括三个方面(严格按照此顺序撰写)&＃xff1a;

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

示例如下&＃xff1a;

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

代码逻辑注释

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

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

注释风格

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

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

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

建议全部使用单行注释和代码的规范一样&＃xff0c;单行注释不要过长&＃xff0c;禁止超过 120 字符

代码风格

缩进和折行

• 缩进直接使用 gofmt 工具格式化即可(gofmt 是使用 tab 缩进的)
• 折行方面&＃xff0c;一行最长不超过120个字符&＃xff0c;超过的请使用换行展示&＃xff0c;尽量保持格式优雅

我们使用Goland开发工具&＃xff0c;可以直接使用快捷键&＃xff1a;ctrl&＃43;alt&＃43;L&＃xff0c;即可。

语句的结尾

Go语言中是不需要类似于Java需要冒号结尾&＃xff0c;默认一行就是一条数据

如果你打算将多个语句写在同一行&＃xff0c;它们则必须使用。

括号和空格

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

// 正确的方式if a > 0 {​}​// 错误的方式if a>0 // a &＃xff0c;0 和 > 之间应该空格{ // 左大括号不可以换行&＃xff0c;会报语法错误​}

import 规范

import在多行的情况下&＃xff0c;goimports会自动帮你格式化&＃xff0c;但是我们这里还是规范一下import的一些规范&＃xff0c;如果你在一个文件里面引入了一个package&＃xff0c;还是建议采用如下格式&＃xff1a;

import ( "fmt")

如果你的包引入了三种类型的包&＃xff0c;标准库包&＃xff0c;程序内部包&＃xff0c;第三方包&＃xff0c;建议采用如下方式进行组织你的包&＃xff1a;

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

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

在项目中不要使用相对路径引入包&＃xff1a;

// 这是不好的导入import "../net"​// 这是正确的做法import "github.com/repo/proj/src/net"

但是如果是引入本项目中的其他包&＃xff0c;最好使用相对路径。

错误处理

• 错误处理的原则就是不能丢弃任何有返回err的调用&＃xff0c;不要使用 _ 丢弃&＃xff0c;必须全部处理。接收到错误&＃xff0c;要么返回err&＃xff0c;或者使用log记录下来
• 尽早return&＃xff1a;一旦有错误发生&＃xff0c;马上返回
• 尽量不要使用panic&＃xff0c;除非你知道你在做什么
• 错误描述如果是英文必须为小写&＃xff0c;不需要标点结尾
• 采用独立的错误流进行处理

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

测试

单元测试文件名命名规范为 example_test.go 测试用例的函数名称必须以 Test 开头&＃xff0c;尽量避免使用 main 方法测试。例如&＃xff1a;TestExample 每个重要的函数都要首先编写测试用例&＃xff0c;测试用例和正规代码一起提交方便进行回归测试。

配置文件

编写代码时提供三套配置文件&＃xff0c;分别是开发环境 [dev] , 测试环境 [test] , 现网环境 [prod] 。 目录如下&＃xff1a;

./├── dev│ ├── seelog.xml│ └── service.yml├── prod│ ├── seelog.xml│ └── service.yml└── test ├── seelog.xml └── service.yml

常用工具

代码格式化

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

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

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

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

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

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

使用如下&＃xff1a;

go vet .

依赖包管理

GoModule

Golang官方在1.11版本初步引入的GoModule模块。1.12版本正式开始支持。GoModule是官方提供的包管理解决方案。通过GoModule&＃xff0c;开发者可以把工程放在GOPATH之外的位置。相比于之前的包管理方案: dep&＃xff0c;vendor。GoModule的管理方案更加灵活。 可以运行go mod help来看看GoModule中有哪些命令。

• go mod init [module]&＃xff1a;初始化.mod 包管理文件到当前工程。
• go mod vendor&＃xff1a;vendor版本的解决方案&＃xff0c;将依赖复制到vendor下面。
• go mod tidy&＃xff1a;移除未用的模块&＃xff0c;以及添加缺失的模块。
• go mod verify&＃xff1a;验证所有模块是否正确。

亮点&＃xff1a;

使用replace替换无法直接获取的package 依赖包冲突问题 自动查找包依赖

总结

两个等级: [S] 建议, [M] 必须。以下是细节。

代码组织结构

• [M] 一个目录只包含一个包&＃xff0c;模块复杂拆分子模块/子目录
• [S] 内部项目GOPATH如果指向多个工作目录。公开项目为第一个工作区间(即 go get 默认下载到第一个目录)
• [M] 非测试文件 (*_test.go) 禁止使用&＃xff0c;简化包
• [M] 禁止相对路径导入包
• [S] 建议goimports或者IDE管理import
• [S] 建议使用GoModule管理第三方包

代码风格

• [M] 提交代码时 gofmt 格式化代码&＃xff0c; golint 检查代码(使用IDE时默认这两个工具会自动用到)
• [S] json 字符串建议使用反单引号(&＃96;)
• [M] 文件名必须小写&＃xff0c;允许下划线&＃39;_’&＃xff0c;但头尾不能。避免与 _test.go 或者系统相关 _386.go 等冲突
• [S] 文件名以功能为指引&＃xff0c;不需要再出现模块名
• [M] 目录名必须小写&＃xff0c;允许中划线&＃39;-&＃39;&＃xff0c;但头尾不能
• [S] 不建议目录名出现下划线&＃39;_&＃39;
• [M] 包名必须全部小写&＃xff0c;无下划线&＃xff0c;越短越好&＃xff0c;尽量不要与标准库重名&＃xff0c;禁止通过中划线连接多个单词
• [S] 包名尽量与目录名一致
• [M] 函数名和结构体名必须为大小写驼峰模式&＃xff0c;最好不带特殊字符如划线等
• [S] 函数名建议动词或者动宾结构单词&＃xff0c;结构体建议名词或者动名词
• [S] 常量和枚举名&＃xff0c;大小写驼峰法&＃xff0c;不允许下划线&＃xff0c;第三方包例外。
• [M] 函数参数首字母小写&＃xff0c;不能有下划线&＃xff0c;按大小驼峰法
• [S] 函数参数按紧密程度安排位置&＃xff0c;同类型参数应该相邻
• [S] 参数不大于5个
• [M] 变量名不允许下划线&＃xff0c;大小写驼峰法&＃xff0c;局部变量首字母小写&＃xff0c;全局变量首字母大写
• [S] 避免全局变量多使用&＃xff0c; for 循环可用单字母
• [M] 接口名大小写驼峰法&＃xff0c;首字母大写&＃xff0c;不能下划线&＃xff0c;名词
• [S] 接口名 &＃39;er&＃39; 结尾
• [M] 复杂功能请多写注释备注&＃xff0c;注释表达需清晰&＃xff0c;不要啰嗦。注释标准暂时不强制&＃xff0c;最好参考 godoc &＃xff0c;如包注释使用 /**/ ,首字母大写&＃xff0c;注释后空一行&＃xff0c;函数注释写在函数上方等。

总而言之&＃xff0c;文件名和目录名&＃xff0c;包名都必须小写。数据类型变量和参数等定义最好使用驼峰大小写法&＃xff0c;不要使用下划线或者中划线

单元测试/程序效率

• [S] 建议少使用 main 方法测试&＃xff0c;而是使用 _test.go 做测试
• [M] 与其他语言类似&＃xff0c;避免多级 if 或者 for 嵌用&＃xff0c;代码层次需简单&＃xff0c;绕脑层次少
• [M] 避免有歧义的命名&＃xff0c;如 IsTrue 变量&＃xff0c;if(!IsTrue).
• [M] 请熟悉 Go 语言各特征&＃xff0c;避免低效用法。