• 项目目录结构
  • 命名规范
    • 文件名命名规范
    • 包名
    • 接口名
    • 变量名
    • 常量名
    • 函数名
    • Geter/Seter方法
  • import规范
  • 代码规范
    • 格式
    • 注释
    • 分号
    • 控制结构
    • 空白标识符
  • 错误处理

    项目目录结构

    GOPATH是Go的工作目录,在windows上是C:\user\username\go。模板示例:

    1. GOPATH
    2. |--bin
    3. |--pkg
    4. |--src
    5. |-----github.com
    6. |---c7n 项目名称
    7. |---.git git相关的内容
    8. |---cmd 项目的主要应用程序
    9. |---app
    10. |---kube
    11. ...
    12. |---internal 私有应用程序和库代码,不希望其他人在他们的应用程序或库导入
    13. |---pkg 可以被其他应用引用的库
    14. |---vendor 依赖的go程序包
    15. |---github.com/xxx 第三方库
    16. |---api OpenAPI/Swagger规格, JSON格式文件, protocol定义文件等等
    17. |---web Web应用程序组件:静态资源,服务器端模板等
    18. |---configs 配置文件模板或默认配置
    19. |---init 系统初始化配置
    20. |---scripts 执行各种构建、安装、分析的脚本
    21. |---build 打包和持续集成
    22. |---deployments IaaS,PaaS,系统和集装箱编配部署配置和模板
    23. |---test 外部测试程序和测试数据
    24. |---docs 用户文档,包括godoc生成的文档
    25. |---tools 支持此项目的工具(比如脚本文件等)
    26. |---examples 例子
    27. |---third_party 第三方工具
    28. |---githooks
    29. |---assets 其他资源
    30. ...
    31. |-- google.golang.org ...
    32. ...

    命名规范

    所有的标识符按照Go规定的标志符命名,即数字,字母下划线,应该以字母开头。

    文件名命名规范

    小写,尽量见名思义,看见文件名就可以知道这个文件下的大概内容,对于源代码里的文件,文件名要很好的代表了一个模块实现的功能。

    包名

    包名用小写,使用短命名,尽量和标准库不要冲突。

    接口名

    单个函数的接口名以”er”作为后缀,其函数去掉”er”如Reader,Writer。

    1. type Reader interface {
    2. Read(p []byte) (n int, err error)
    3. }

    两个函数的接口名综合两个函数的名字,比如:

    1. type WriteFlusher interface {
    2. Write([]byte) (int, error)
    3. Flush() error
    4. }

    三个函数及以上的接口名类似于结构体名,比如:

    1. type Car interface {
    2. Start([]byte)
    3. Stop() error
    4. Recover()
    5. }

    变量名

    • 全局变量:采用驼峰命名法

    • 局部变量:驼峰式,小写字母开头

    常量名

    常量:大写,采用下划线

    函数名

    采用驼峰命名法,尽量不要使用下划线,首字母小写为包内可见,首字母大写则可以被包外引用。 函数的返回结果可以给定一个名字,该名字会被初始化,如果函数执行了没有参数的 return 语句,则结果参数的当前值便被作为要返回的值。比如:

    1. func ReadFull(r Reader, buf []byte) (n int, err error) {
    2. for len(buf) > 0 && err == nil {
    3. var nr int
    4. nr, err = r.Read(buf)
    5. n += nr
    6. buf = buf[nr:]
    7. }
    8. return
    9. }

    Geter/Seter方法

    Go不提供对Get方法和Set方法的自动支持,需要自己编写。

    Geter方法名上不允许加上Get,比如:有一个结构体owner(小写,包内可见),则Get方法应该叫做 Owner()(大写,可被包外引用),而不是GetOwner()。而Seter方法可以加上Set前缀,比如:SetOwner()方法。

    import规范

    import在多行的情况下,Goimports会自动帮您格式化,在一个文件里面引入了一个package,建议采用如下格式:

    1. import (
    2. "fmt"
    3. )

    如果本包引入了三种类型的包:标准库包,程序内部包,第三方包,建议采用如下方式进行组织:

    1. import (
    2. "encoding/json" //标准库包
    3. "strings"
    4. "myproject/models" //程序内部包
    5. "myproject/controller"
    6. "git.obc.im/obc/utils" //第三方包
    7. "git.obc.im/dep/beego"
    8. "git.obc.im/dep/mysql"
    9. )

    导包时,应尽量使用绝对路径:

    1. import "xxxx.com/proj/net" // 正确
    2. import "../net" // 错误

    代码规范

    格式

    缩进: 代码对齐应该使用table对齐。

    行长度: Go没有行长度限制。如果感觉一行太长,可以折成几行,并额外使用一个tab进行缩进。

    括号: 控制结构(if/for/switch)的语法不需要括号。

    go fmt :可以使用go fmt工具来处理格式问题,比如: 不需要花费时间对结构体中每个域的注释进行排列

    1. type T struct {
    2. name string // name of the object
    3. value int// its value
    4. }

    go fmt会做如下改动:

    1. type T struct {
    2. name string // name of the object
    3. value int // its value
    4. }

    go fmt默认只对本目录下的.go文件进行格式化,使用go fmt ./…可以递归地对该目录下子文件都进行格式化。

    注释

    Go有两种注释方式,块注释 / / 和 行注释 // 。 Godoc用来处理Go源文件,抽取有关程序包内容的文档。在顶层声明之前出现,若中间没有换行的注释,会随着声明一起被抽取,作为该项的解释性文本。 每个程序包都应该有一个包注释,位于包声明之前,比如:

    1. /*
    2. Package regexp implements a simple library for regular expressions.
    3. The syntax of the regular expressions accepted is:
    4. regexp:
    5. concatenation { '|' concatenation }
    6. concatenation:
    7. { closure }
    8. closure:
    9. term [ '*' | '+' | '?' ]
    10. term:
    11. '^'
    12. '$'
    13. '.'
    14. character
    15. '[' [ '^' ] character-ranges ']'
    16. '(' regexp ')'
    17. */
    18. package regexp

    如果程序包很简单,则包注释可以非常简短:

    1. // Package path implements utility routines for
    2. // manipulating slash-separated filename paths.

    函数的注释,第一条语句应该为一条概括语句,并且使用被声明的名字作为开头。比如:

    1. // Compile parses a regular expression and returns, if successful, a Regexp
    2. // object that can be used to match against text.
    3. func Compile(str string) (regexp *Regexp, err error) {}

    变量的注释,可以对声明进行组合,比如:

    1. // Error codes returned by failures to parse an expression.
    2. var (
    3. ErrInternal = errors.New("regexp: internal error")
    4. ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    5. ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    6. ...
    7. )

    分号

    在Go中,应该尽量只在for/if语句中使用分号,比如:

    1. for i := 0; i < 3 ; i++ {
    2. }
    3. if n, ok = info(); ok {
    4. }

    控制结构

    Go的控制结构包括if/for/switch/select,控制条件可以不用加圆括号(),而且左大括号不能放在下一行,Go不使用分号作为语句终结符,其原因是在编译初期,词法分析器会在它认为是语句结束标志(即换行符)后添加分号,比如:

    1. if i < f() // 错误 词法分析器解析为--> if i < i f();{} 从而报错
    2. {
    3. }
    4. if i < f() { // 正确 词法分析器解析为--> if i < i f(){;} 立面的分号是合法的
    5. }

    Go的if语句应该避免使用else语句,比如:

    1. f, err := os.Open(name)
    2. if err != nil {
    3. return err // 出错则不会往下走
    4. }
    5. d, err := f.Stat() // 这里的err不是重新声明,而是重新赋值
    6. if err != nil {
    7. f.Close()
    8. return err
    9. }
    10. codeUsing(f, d)

    Go的for语句块统一了c的for和while语句:

    1. // Like a C for
    2. for init; condition; post { }
    3. // Like a C while
    4. for condition { }
    5. // Like a C for(;;)
    6. for { }
    Go的自增/自减操作是语句而不是表达式,因此,当i++是正确的,而++i则会编译不通过。

    Go的switch比c更加通用,表达式不需要为常量,甚至不需要为整数,case是按照从上到下的顺序进行求值,直到找到匹配的。如果 switch 没有表达式,则对true进行匹配。可以将大量的if-else-if-else串改写成一个switch,比如:

    1. func unhex(c byte) byte {
    2. switch {
    3. case '0' <= c && c <= '9': // 每个case会自动break
    4. return c - '0'
    5. case 'a' <= c && c <= 'f':
    6. return c - 'a' + 10
    7. case 'A' <= c && c <= 'F':
    8. return c - 'A' + 10
    9. }
    10. return 0
    11. }

    空白标识符

    Go中以_下划线标识来接收空白的内容,相当于Unix系统的一个设备占用符null。当某个函数或者range返回多个值时,若只需要其中一个值,则可以用下划线占位,比如:

    1. if _, err := os.Stat(path); os.IsNotExist(err) {
    2. fmt.Printf("%s does not exist\n", path)
    3. }

    禁止编译器对未使用导入包的错误报告,可以用空白标识符来引用一个被导入包中的符号。同样的,将未使用的变量fd赋值给一个空白标识符也可以禁止编译错误,但是一定要有注释:

    1. package main
    2. import (
    3. "fmt"
    4. "io"
    5. "log"
    6. "os"
    7. )
    8. var _ = fmt.Printf // For debugging; delete when done.
    9. var _ io.Reader // For debugging; delete when done.
    10. func main() {
    11. fd, err := os.Open("test.go")
    12. if err != nil {
    13. log.Fatal(err)
    14. }
    15. // TODO: use fd.
    16. _ = fd
    17. }

    若不需要使用这些API,为了实现仅为副作用而导入包的操作,可以在导入语句中,将包用空白标识符进行重命名:

    1. import _ "net/http/pprof"

    错误处理

    error:error作为函数的值返回,必须尽快对error进行处理,采用独立的错误流进行处理,不要采用下面这种方式:

    1. if err != nil {
    2. // error handling
    3. } else {
    4. // normal code
    5. }

    而是采用这种方式:

    1. if err != nil {
    2. // error handling
    3. return // or continue, etc.
    4. }
    5. // normal code

    如果返回值需要初始化,则采用下面的方式:

    1. x , err := f()
    2. if err != nil {
    3. // error handling
    4. return // or continue, etc.
    5. }
    6. // use x

    Panic:用来创建一个 RuntimeException 并结束当前程序。该函数接受一个任意类型的参数,并在程序挂掉之前打印该参数内容,通常选择一个字符串作为参数。比如:

    1. func init() {
    2. if user == "" {
    3. panic("no value for $USER")
    4. }
    5. }

    应该在逻辑处理中禁用panic。在main包中只有当实在不可运行的情况采用panic,例如文件无法打开,数据库无法连接导致程序无法正常运行,但是对于其他的package对外的接口不能有panic,只能在包内采用。建议在main包中使用log.Fatal来记录错误,这样就可以由log来结束程序。

    Recover:recover用于捕获runtime的异常,禁止滥用recover,在开发测试阶段尽量不要用recover,recover一般放在你认为会有不可预期的异常的地方。比如:

    1. func server(workChan <-chan *Work) {
    2. for work := range workChan {
    3. go safelyDo(work)
    4. }
    5. }
    6. func safelyDo(work *Work) {
    7. defer func() {
    8. if err := recover(); err != nil {
    9. log.Println("work failed:", err)
    10. }
    11. }()
    12. // do 函数可能会有不可预期的异常
    13. do(work)
    14. }

    Defer:该函数会在return前执行,对于一些资源的回收用defer是好的,但也禁止滥用defer,defer是需要消耗性能的,所以频繁调用的函数尽量不要使用defer。

    1. // Contents returns the file's contents as a string.
    2. func Contents(filename string) (string, error) {
    3. f, err := os.Open(filename)
    4. if err != nil {
    5. return "", err
    6. }
    7. defer f.Close() // f.Close will run when we're finished.
    8. var result []byte
    9. buf := make([]byte, 100)
    10. for {
    11. n, err := f.Read(buf[0:])
    12. result = append(result, buf[0:n]...) // append is discussed later.
    13. if err != nil {
    14. if err == io.EOF {
    15. break
    16. }
    17. return "", err // f will be closed if we return here.
    18. }
    19. }
    20. return string(result), nil // f will be closed if we return here.
    21. }