Golang 编码规范

一、项目目录结构规范

文件名命名规范

AudioMarkGo/
├── AudioMarkGo 编译后文件
├── conf   配置文件目录
│   ├── app.conf  主配置文件,开发环境以及测试环境引入dev;生产环境则开启prod。
│   ├── dev.conf
│   └── prod.conf
├── controller 项目代码，项目主题逻辑请按照规范命名。
│   └── userCenter
│       ├── resume.go
│       └── taskList.go
├── fun  项目中需要的共用方法
│   ├── audioMarkGo.go  项目中共用方法
│   ├──userCenter.go  项目中用中心共用方法
│   ├── common.go  整个项目的共用方法 
├── lang 平台语言切换配置
│   └── zh.ini 
├── main.go 项目主函数
├── models 项目的数据库操作
│   ├── amProjectMember.go  数据库映射表
│   ├── mongodb.go   mongoDB 数据库连接操作
│   ├── mysql.go  mysql数据库连接操作
│   ├── redis.go redis 数据库连接操作
├── routers 项目路由
│   └── router.go 项目路由信息
├── swagger 自动化Api文档
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── index.html
│   ├── oauth2-redirect.html
│   ├── swagger-ui-bundle.js
│   ├── swagger-ui-bundle.js.map
│   ├── swagger-ui-standalone-preset.js
│   ├── swagger-ui-standalone-preset.js.map
│   ├── swagger-ui.css
│   ├── swagger-ui.css.map
│   ├── swagger-ui.js
│   ├── swagger-ui.js.map
│   ├── swagger.json
│   └── swagger.yml
└── tests 项目测试文件

文件名命名规范

小驼峰命名方式，看见文件名就可以知道这个文件下的大概内容。例如:audioMark

二、命名规范

包名

包名用小写,与外层文件夹名称尽量相同，尽量和标准库不要冲突

接口名

接口名以”er”作为后缀，如Reader,Writer

//接口的实现则去掉“er”
type Reader interface {
        Read(p []byte) (n int, err error)
}

变量

全局变量:采用驼峰命名方式,仅限在包内的全局变量；

  var ProjectName string 
  //如多组变量则使用,组和声明或者平行赋值
  var(
      ProjectName string 
   )

局部变量:采用小驼峰命名方式,注意声明局部变量尽量使用 :=

    projectName := "name"

常量

全部大写可以使用采用下划线

const DIR_NAME = "test"
//如多组常量则使用
const(
    DIR_NAME= "test"
    PROJECT_NAME = "test"
)

函数

使用驼峰命名方式，需要包外使用则开头使用大写，否则使用小驼峰。

三、import 规范

引入多个包文件

//标准库包，程序内部包，第三方包,在项目中不要使用相对路径引入包
import (
    "encoding/json"
    "strings"

    "myproject/models"
    "myproject/controller"
    "git.obc.im/obc/utils"

    "git.obc.im/dep/beego"
    "git.obc.im/dep/mysql"
)  

四、注释规范

注释可以帮我们很好的完成文档的工作，写得好的注释可以方便我们以后的维护。和其他语言类似，go 语言也提供了 /**/ 的块注释和 // 的单行注释两种注释风格， 在我们的项目中为了风格的统一，全部使用单行注释。go 语言自带的 godoc 工具可以根据注释生成文档，生成可以自动生成对应的网站（ golang.org 就是使用 godoc 工具直接生成的），注释的质量决定了生成的文档的质量。下面从包注释、结构体（接口）注释、函数（方法）注释、代码逻辑注释以及注释规范方面进行说明。

包注释

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

// @Title 
// @Description 
// @Author 创建人 创建时间
// @Update  创建人 修改时间

结构（接口）注释

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

// User ， 用户对象，定义了用户的基础信息
type User struct{
    UserName  string `description:"用户名称"`
    Email     string `description:"邮箱"`
}

函数 注释

// @Title 标题
// @Description 详细信息
// @Auth 创建时间 创建人
// @Param 参数类型 参数介绍
// @Return 返回类型 "错误信息"

方法 注释

@Title
这个 API 所表达的含义，是一个文本，空格之后的内容全部解析为 title
@Description
这个 API 详细的描述，是一个文本，空格之后的内容全部解析为 Description
@Param
参数，表示需要传递到服务器端的参数，有五列参数，使用空格或者 tab 分割，五个分别表示的含义如下
参数名
参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
参数类型
是否必须
注释
@Success
成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。
三个参数必须通过空格分隔
@Failure
失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息
@router
路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。
如何自动化生成文档

// @Title Get Product list
// @Description 开发时间 编写人 Get Product list by some info
// @Success 200 {object} models.ZDTProduct.ProductList
// @Param   category_id     query   int false       "category id"
// @Param   brand_id    query   int false       "brand id"
// @Param   query   query   string  false       "query of search"
// @Param   segment query   string  false       "segment"
// @Param   sort    query   string  false       "sort option"
// @Param   dir     query   string  false       "direction asc or desc"
// @Param   offset  query   int     false       "offset"
// @Param   limit   query   int     false       "count limit"
// @Param   price           query   float       false       "price"
// @Param   special_price   query   bool        false       "whether this is special price"
// @Param   size            query   string      false       "size filter"
// @Param   color           query   string      false       "color filter"
// @Param   format          query   bool        false       "choose return format"
// @Failure 400 no enough input
// @Failure 500 get products common error
// @router /products [get]

注释风格

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

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

代码风格

编写代码中使用tab键对其代码。

错误处理

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

// 错误写法
 if err != nil {

} else {
    
}

// 正确写法
if err != nil {
    return 
}