一、项目目录结构规范
文件名命名规范
AudioMarkGo/
├── AudioMarkGo 编译后文件
├── conf 配置文件目录
│ ├── app.conf 主配置文件,开发环境以及测试环境引入dev;生产环境则开启prod。
│ ├── dev.conf
│ └── prod.conf
├── controller 项目代码,项目主题逻辑请按照规范命名。
│ └── userCenter
│ ├── resume.go
│ └── taskList.go
├── fun 项目中需要的共用方法
│ ├── audioMark.go 项目中共用方法
│ ├──userCenter.go 项目中用中心共用方法
│ ├── common.go 整个项目的共用方法
│ └── libfunc.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
)
//平行赋值
var ProjectName,ProjectNumber = "test",1
局部变量:采用小驼峰命名方式,注意声明局部变量尽量使用 :=
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文件中(一般是和包同名的文件)即可。 包注释应该包含下面基本信息(请严格按照这个顺序,简介,创建人,创建时间):
//包的基本简介(包名,简介)
//创建者,格式: 创建人: rtx 名
//创建时间,格式:创建时间: yyyyMMdd
结构(接口)注释
每个自定义的结构体或者接口都应该有注释说明,该注释对结构进行简要介绍,放在结构体定义的前一行,格式为: 结构体名, 结构体说明。同时结构体内的每个成员变量都要有说明,该说明放在成员变量的后面(注意对齐),实例如下:
// User , 用户对象,定义了用户的基础信息
type User struct{
Username string // 用户名
Email string // 邮箱
}
函数(方法)注释
@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
}
有疑问加站长微信联系(非本文作者)