golang代码规范

golang代码规范

1.go fmt 和go imports

• 格式化：所有的代码都需要用gofmt格式化。
• 换行：一行代码不超过120列
• 括号和空格：运算符和操作数之间要留空格；作为输入参数或者数组下标时，运算符和运算数之间不需要空格
• import:使用 go imports自动格式化引入的包名

2.error处理

• error作为函数的返回值，必须对error进行处理，或者将返回值赋值给明确忽略

• error作为函数的值返回且有多个返回值的时候，error必须是最后一个参数

• 错误描述不需要标点结尾

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

• 错误返回的判断独立处理，不与其他变量组合逻辑判断

  举例：

  if err!=nil{
      //handle
  }else{
      
  }
  //这种格式是错误的
  //应该采用如下格式
  if err!=nil{
      //handle
      return //or continue etc.
  }
  //normal code
  

3. 单元测试

• 单元测试的文件名命名规范为 example_test.go
• 测试用例的函数必须以Test开头，例如TextExample.
• 每个重要的可导出函数都要首先编写测试用例，测试用例和正规代码一起提交方便进行回归测试。
• 类型断言失败处理：使用 "common ok“的惯用法

4.panic处理

• 在业务逻辑处理中禁止使用pannic
• 在main包中只有当完全不可运行的情况下可使用panic。例如文件无法打开，数据库无法连接等
• 建议在main包中使用log.Fatal来记录错误，这样可以通过log来结束程序，或者将panic抛出异记录到日志文件中，方便排查问题
• panic捕获只能到goroutine最顶层，每个自行启动的goroutine，必须在入口处捕获panic，并打印堆栈信息或者进行其他处理

5.recover处理

• recover用于捕获runtime的异常，禁止滥用recover
• 必须在defer中使用，一般用于捕获程序运行期间发生异常抛出的panic或者程序主动抛出的panic

6.注释

• 在编码阶段同步写好变量，函数，包注释，注释可以通过godoc导出生成文档
• 注释必须是完整的句子，以需要注释的内容作为开头，句点作为结尾
• 程序中每个被导出的（大写的）名字，都应该有一个文档注释

6.1 包注释

• 每个包都应该有包注释，如果一个包中有多个go文件，只需要出现在一个go文件中（一般为和包同名的文件）
• 格式：// Package包名 包信息描述

6.2 结构体注释

• 每个需要导出的自定义结构体或者接口都必须有注释说明
• 注释对结构进行简要介绍，放在结构体定义的前一行
• 结构体内的每个需要导出的成员变量都要有说明，放在该成员变量的前一行
• 格式： // 结构体名 结构体信息描述

6.3 方法注释

• 每个需要导出的方法或者函数都必须有注释
• 注释描述函数或者方法的功能，调用方等信息
• 格式： //函数名 函数信息描述

6.4 变量注释

• 每个需要导出的常量或者变量都必须有注释说明
• 该注释对常量或者变量进行简要介绍，放在常量或者变量的前一行
• 格式 ：// 变量名 变量信息描述

6.5 类型注释

• 每个需要导出的类型定义和类型别名都必须有注释说明
• 该注释对类型进行简要介绍，放在定义的前一行
• 格式： // 类型名 类型信息描述

7.命名规范

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

7.1 包命名

• 保持package名字和目录一致
• 尽量采用有意义、简短的包名，尽量不要与标准库冲突
• 包名应该为小写单词，不要使用下划线或者混合大小写，使用多级目录来划分层级
• 项目名可以通过中划线来连接多个单词
• 使用简单明了的包命名，不要使用无意义的包名

7.2 文件命名

• 采用有意义，简短的文件名
• 文件名应该采用小写，并且使用下划线分割各个单词

7.3 结构体命名

• 采用驼峰命名方式，首字母根据访问控制采用大写或者小写，需要导出大写，不需要导出小写
• 结构体应该是名词或者名词短语，不应该是动词
• 结果体的申明和初始化采用多行

7.4 接口命名

• 命名规则基本保持和结构体命名规则一致
• 单个函数的结构体以“er"作为后缀，例如Reader
• 两个函数的接口名综合两个函数名
• 三个以上函数的接口名，类似于结构体名

7.5 变量命名

• 变量名必须遵守驼峰命名规则，首字母根据访问控制决定使用大写或者小写

• 特有名词，遵循以下规则：

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

  其他情况都应该使用该名词原有的写法：APIClient

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

• 私有全局变量和局部变量规范一致，均以小写字母开头

7.6 常量命名

• 常量均采用驼峰命名法
• 如果是枚举类型的常量，需要先创建相应类型
• 私有全局常量和局部变量规范一致，均以小写字母开头

8.函数参数

• 函数的返回相同类型的两个或者三个参数，或者从上下文不清楚结果的含义，使用命名返回，其他情况不建议使用命名返回
• 传入变量和返回变量以小写字母开头
• 参数数量不能超过5个
• 尽量使用值传递，非指针传递
• 传入参数是map,slice,chan,interface不要传递指针

9.defer

• 当存在资源管理时，应紧跟defer函数进行资源释放
• 判断是否有错误发生之后，再defer释放资源
• 禁止在循环中使用defer

10. 方法接收器&代码行数&嵌套

• 方法接收器
  • 接收器的命名在函数超过20行的时候不要再用单字符
  • 命名不能采用me,this,self这类易混淆名称
• 代码行数
  • 文件长度不超过800行
  • 函数长度不超过80行
• 嵌套
  • 嵌套深度不能超4层

11.变量声明和魔数

• 变量申明
  • 变量申明尽量放在变量第一次使用前面，就近原则
• 魔法数字
  • 如果魔法数字出现超过2次，则禁止使用

12.依赖管理和代码提交

• go1.11以上必须使用go modules模式
• 建议使用go modules作为依赖管理的项目不提交vendor目录
• 建议使用go modules管理依赖的项目将go.sum文件不添加到忽略提交规则中

13.应用服务

• 应用服务接口建议有readme.md
  • 建议包括服务基本描述、使用方法、部署时的限制与要求、基础环境依赖（最低go版本）
  • 应用服务必须要有接口测试

14.常用工具和其他要求

• gofmt 大部分的格式问题可以通过gofmt解决，gofmt自动格式化代码，保证所有的go代码与官方推荐的格式保持一致，于是所有格式有关的问题，都已gofmt的结果为准
• goimports 在gofmt基础上增加了自动删除和引入包
• go vet vet工具可以帮我们静态分析我们的源码存在的各种问题，例如多余的代码，提前return的逻辑，struct的tag是否符合标准等。编译前先执行代码静态分析
• golint 检测代码中不规范的地方