一、项目目录结构规范
文件名命名规范
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
}
网友评论