For-learning-Go-Tutorial

在 Golang中,编程规范对于一个人的认知很重要.因而一开始就希望可以养成好的习惯！

Golang编程标准和规范

1. 行长

  • 一行最长不超过80个字符，超过的使用换行展示，尽量保持格式优雅。

2. 文件名命名规范

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

3. 包

  • 包名应该为小写单词，不要使用下划线或者混合大小写。
  • 每个包都应该有一个包注释，包如果有多个go文件，就只需要在入口文件写包注释.
  • 概况以 Package 开头。
  1. // Copyright 2009 The Go Authors. All rights reserved.
  2. // Use of this source code is Governed by a BSD-style
  3. // license that can be found in the LICENSE file.
  5. // Package strings implements simple functions to manipulate strings.
  6. package strings

4. 命名

  • 包名用小写,使用短命名,尽量和标准库不要冲突.
  • 使用短命名，因为长名字并不会使得事物更易读，文档注释会比格外长的名字更有用.
  • 需要导出的任何类型必须以大写字母开头.

5. 变量

  • 全局变量：驼峰式，可导出的使用大写字母开头.
  • 参数传递：驼峰式，小写字母开头.
  • 局部变量：下划线风格命名.

6. 接口

  • 单个函数的接口名以”er”作为后缀，如Reader,Writer
  • 接口的实现则去掉“er”
    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 Vehicle interface {
    2.   Start([]byte) 
    3.   Stop() error
    4.   Recover()
    5. }

7. 函数和结构体

  • 函数名采用驼峰命名法，尽量不要使用下划线
  • 写概况，并且使用被声明的名字作为开头。 ```go // Compile parses a regular expression and returns, if successful, a Regexp // object that can be used to match against text. func Compile(str string) (regexp *Regexp, err error) {

// Request represents a request to run a command. type Request struct { …}

  2. * 采用命名的多返回值，在godoc生成的文档中，带有返回值的函数声明更利于理解。
  3. ```go
  4. func nextInt(b []byte, pos int) (value, nextPos int, err error) {}

8.import

  • 对标准包，程序内部包，第三方包进行分组。
  1. import (
  2.     "encoding/json"         //标准包
  3.     "strings"
  5.     "spike/models"      //内部包
  6.     "spike/utils"
  8.     "github.com/go-sql-driver/mysql"    //第三方包
  9. )
  • 引用包时不要使用相对路径。 ```go // 错误的做法 import “../net”

// 正确的做法 import “github.com/repo/proj/src/net”

  2. #### 9. 错误处理
  3. * error作为函数的值返回,必须尽快对error进行处理
  4. * 错误描述如果是英文必须为小写，不需要标点结尾
  5. * 采用独立的错误流进行处理
  6. * 不要在逻辑代码中使用panic
  8. 不推荐的方式：
  10. ```go
  11. if err != nil {
  12.     // error handling
  13. } else {
  14.     // normal code
  15. }

推荐的方式:

  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
  5. }
  6. // use x

  • 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. }
  7. func safelyDo(work *Work) {
  8.     defer func() {
  9.         if err := recover(); err != nil {
  10.             log.Println("work failed:", err)
  11.         }
  12.     }()
  13.     // do 函数可能会有不可预期的异常
  14.     do(work)
  15. }
  • Defer

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.
  9.     var result []byte
  10.     buf := make([]byte, 100)
  11.     for {
  12.         n, err := f.Read(buf[0:])
  13.         result = append(result, buf[0:n]...) // append is discussed later.
  14.         if err != nil {
  15.             if err == io.EOF {
  16.                 break
  17.             }
  18.             return "", err  // f will be closed if we return here.
  19.         }
  20.     }
  21.     return string(result), nil // f will be closed if we return here.
  22. }

10. 控制结构

  • if

if接受初始化语句，约定如下方式建立局部变量

  1. if err := file.Chmod(0664); err != nil {
  2.     return err
  3. }
  • for 采用短声明建立局部变量
  2. sum := 0
  3. for i := 0; i < 10; i++ {
  4.     sum += i
  5. }
  • range

如果只需要第一项（key），就丢弃第二个：

  1. for key := range m {
  2.     if key.expired() {
  3.         delete(m, key)
  4.     }
  5. }

如果只需要第二项，则把第一项置为下划线

  1. sum := 0
  2. for _, value := range array {
  3.     sum += value
  4. }
  • switch

Go的switch比C更普遍.

  1. func unhex(c byte) byte {
  2.     switch {
  3.     case '0' <= c && c <= '9':
  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. }

没有自动转换，但可以用逗号分隔的列表呈现:

  1. func shouldEscape(c byte) bool {
  2.     switch c {
  3.     case ' ', '?', '&', '=', '#', '+', '%':
  4.         return true
  5.     }
  6.     return false
  7. }

虽然它们在Go中几乎不像其他类似C语言那么常见，但可以使用break语句尽早终止切换:

  1. for n := 0; n < len(src); n += size {
  2.     switch {
  3.     case src[n] < sizeOne:
  4.         if validateOnly {
  5.             break
  6.         }
  7.         size = 1
  8.         update(src[n])
  10.     case src[n] < sizeTwo:
  11.         if n+1 >= len(src) {
  12.             err = errShortInput
  13.             break Loop
  14.         }
  15.         if validateOnly {
  16.             break
  17.         }
  18.         size = 2
  19.         update(src[n] + src[n+1]<<shift)
  20.     }
  21. }

这里是使用两个switch语句的字节片的:

  1. // Compare returns an integer comparing the two byte slices,
  2. // lexicographically.
  3. // The result will be 0 if a == b, -1 if a < b, and +1 if a > b
  4. func Compare(a, b []byte) int {
  5.     for i := 0; i < len(a) && i < len(b); i++ {
  6.         switch {
  7.         case a[i] > b[i]:
  8.             return 1
  9.         case a[i] < b[i]:
  10.             return -1
  11.         }
  12.     }
  13.     switch {
  14.     case len(a) > len(b):
  15.         return 1
  16.     case len(a) < len(b):
  17.         return -1
  18.     }
  19.     return 0
  20. }

使用类型断言的语法和关键字类型:

  1. var t interface{}
  2. t = functionOfSomeType()
  3. switch t := t.(type) {
  4. default:
  5.     fmt.Printf("unexpected type %T\n", t)     // %T prints whatever type t has
  6. case bool:
  7.     fmt.Printf("boolean %t\n", t)             // t has type bool
  8. case int:
  9.     fmt.Printf("integer %d\n", t)             // t has type int
  10. case *bool:
  11.     fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool
  12. case *int:
  13.     fmt.Printf("pointer to integer %d\n", *t) // t has type *int
  14. }
  • return

尽早return：一旦有错误发生，马上返回

  1. f, err := os.Open(name)
  2. if err != nil {
  3.     return err
  4. }
  5. d, err := f.Stat()
  6. if err != nil {
  7.     f.Close()
  8.     return err
  9. }
  10. codeUsing(f, d)

11.方法的接收器

  • 名称 一般采用strcut的第一个字母且为小写，而不是this或者其他不符合的命名习惯 ```go type Buffer struct { buf []byte // contents are the bytes buf[off : len(buf)] off int // read at &buf[off], write at &buf[len(buf)] bootstrap [64]byte // memory to hold first slice; helps small buffers avoid allocation. lastRead readOp // last read operation, so that Unread* can work correctly.

    // FIXME: it would be advisable to align Buffer to cachelines to avoid false // sharing. }

func (b *Buffer) Bytes() []byte { return b.buf[b.off:] }

  2. * 如果接收者是map,slice或者chan，不要用指针传递
  3. ```go
  4. //Map
  5. package main
  7. import (
  8.     "fmt"
  9. )
  11. type mp map[string]string
  13. func (m mp) Set(k, v string) {
  14.     m[k] = v
  15. }
  17. func main() {
  18.     m := make(mp)
  19.     m.Set("k", "v")
  20.     fmt.Println(m)
  21. }
  1. //Channel
  2. package main
  4. import (
  5.     "fmt"
  6. )
  8. type ch chan interface{}
  10. func (c ch) Push(i interface{}) {
  11.     c <- i
  12. }
  14. func (c ch) Pop() interface{} {
  15.     return <-c
  16. }
  18. func main() {
  19.     c := make(ch, 1)
  20.     c.Push("i")
  21.     fmt.Println(c.Pop())
  22. }
  • 如果需要对slice进行修改，通过返回值的方式重新赋值
  1. //Slice
  2. package main
  4. import (
  5.     "fmt"
  6. )
  8. type slice []byte
  10. func main() {
  11.     s := make(slice, 0)
  12.     s = s.addOne(42)
  13.     fmt.Println(s)
  14. }
  16. func (s slice) addOne(b byte) []byte {
  17.     return append(s, b)
  18. }
  • 如果接收者是含有sync.Mutex或者类似同步字段的结构体，必须使用指针传递避免复制
  2. package main
  4. import (
  5.     "sync"
  6. )
  8. type T struct {
  9.     m sync.Mutex
  10. }
  12. func (t *T) lock() {
  13.     t.m.Lock()
  14. }
  16. func main() {
  17.     t := new(T)
  18.     t.lock()
  19. }
  • 如果接收者是大的结构体或者数组，使用指针传递会更有效率。
  1. package main
  3. import (
  4.     "fmt"
  5. )
  7. type T struct {
  8.     data [1024]byte
  9. }
  11. func (t *T) Get() byte {
  12.     return t.data[0]
  13. }
  15. func main() {
  16.     t := new(T)
  17.     fmt.Println(t.Get())
  18. }
  • append ```go

var a, b []int b = append(b, a…)

  2. * 使用strings.TrimPrefix 去掉前缀，strings.TrimSuffix去掉后缀
  3. ```go
  4. var s1 = "a value"
  5. var s2 = "a"
  6. var s3 = strings.TrimPrefix(s1, s2)
  1. var s1 = "value"
  2. var s2 = "e"
  3. var s3 = strings.TrimSuffix(s1,s2)

12.使用工具检查你的代码

参考文档

License

This is free software distributed under the terms of the MIT license