Golang 编码规范

My_Fuzz · · 1013 次点击 · · 开始浏览    
这是一个创建于 的文章,其中的信息可能已经有所发展或是发生改变。

一、项目目录结构规范

文件名命名规范

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 
}

有疑问加站长微信联系(非本文作者)

本文来自:简书

感谢作者:My_Fuzz

查看原文:Golang 编码规范

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

1013 次点击  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传