Go语言开发规范实践指南

// package [按照类别命名]
package main

// 表示这个是字符串编码的包，即该.go文件应该包含在 strencode 目录下。
// 包命名名称最好不加s复数，即不能strencodes
package strencode

// 打印功能实现文件
print.go
// 单元测试或基准测试文件
print_test.go
// 示例文件
example_print_test.go

// 单一常量声明
const PI = 3.1415926535898

// 批量常量声明
const (
  USER_NAME = "WeiyiGeek"
  USER_ADDR = "ChongQing.China"
)

// 公用 (类型推导)
var Public = "public"

// 私有
var private  = "private"

// 指定变量的类型
var userName string = "weiyigeek"

// 简短变量声明(只能在函数内部)
briefCount := 65535

// 批量变量声明(函数外是全局，函数内是局部)
var (
  userName string
  userAge int8
  user_sex bool
)

// 内部私有函数
func getName(id int)(name string) {}

// 外部公共可调用函数
func GetAge(id int)(age uint8){}

// 结构体方法
func (u *User)Printf(id int)(name string){}

// 匿名函数
func(){fmt.Println("匿名函数无函数名称")}()

// 为了对相关的测试用例进行分组，函数名可能包含下划线，如：
fun TestMyFunction_WhatIsBeingTested(t *test.T){}

// 外部包，多行声明
type User struct{
  Username string
  Email    string
}

// 内部包
type user struct{
  Username string
  Email    string
}

// 多行初始化
u := User{
  Username: "ada"
  Email:    "dsfgsdfg"
}

// 匿名结构体
type anonymousStr struct {
    Username string
    Email    string
}

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

// Package Notes 包: 实现 xxxx  
package notes

// Const XXY 常量: 定义 xxxx
const XYZ = 1 

// Variable xyz 变量：定义 xxxx
var xyz = 1

// Struct Abc 结构体: 描述 xxxx 
type Abc struct {} 

// Function Bcd 函数: 功能 xxxx
func Bcd() {}

// 在无效注释中以 BUG(who) 开头的注释, 将被识别为已知bug, 显示在 bugs 区域,
// 如果 bug注释 和 关键字注释 中间无换行, 那么 混合的注释 将被显示在 bugs 和 godoc列表 两个区域内
// BUG(who): 我是bug说明 

// Interface Abcer 接口: 包含 xxxxx (PKG注释)
type Abcer interface {}

/* 
多行注释 && 嵌套单行注释
示例函数实现godoc自动生成example示例
	此处是预格式化需要缩进。
// 此函数将被展示在OverView区域
*/
func Example_notes(){
    fmt.Println("Hello OverView")
  // Output:
  // Hello OverView
}

// （1）相似的声明放在一组,适用于常量、变量和类型声明：
const (
  a = 1
  b = 2
)
 
var (
  a = 1
  b = 2
)
 
type (
  Area float64
  Volume float64
)

// （2）非常注意: 仅将相关的声明放在一组。不要将不相关的声明放在一组。
type Operation int
const (
  Add Operation = iota + 1
  Subtract
  Multiply
)
const EnvVar = "MY_ENV"  // 没有关联的变量单放

// （3）分组使用的位置没有限制，例如：你可以在函数内部使用它们：
func f() string {
  var (
    red   = color.New(0xff0000)
    green = color.New(0x00ff00)
    blue  = color.New(0x0000ff)
  )
}

import (
  "fmt"
  "os"

  "go.uber.org/atomic"
  "golang.org/x/sync/errgroup"
)

import (
  "fmt"
  "os"
  "runtime/trace"
  "net/http"
// _表示，导入不使用包中的方法，但是会加载init初始化
  _ "net/http/pprof"
    
// 在所有其他情况下，除非导入之间有直接冲突，否则应避免导入别名。
  client "example.com/client-go"
  trace "example.com/trace/v2"
)

// 按照顺序
type something struct{ ... }
 
func newSomething() *something {
    return &something{}
}
 
func (s *something) Cost() {
  return calcCost(s.weights)
}
 
func (s *something) Stop() {...}
 
// 普通工具函数
func calcCost(n []int) int {...}

// 不推荐的方式
var _s string = F()
func F() string { return "A" }

// 推荐方式,由于 F 已经明确了返回一个字符串类型，因此我们没有必要显式指定_s 的类型, 还是那种类型
var _s = F()
func F() string { return "A" }

type myError struct{}
func (myError) Error() string { return "error" }
func F() myError { return myError{} }
var _e error = F()
// F 返回一个 myError 类型的实例，但是我们要 error 类型

// foo.go
const (
  _defaultPort = 8080
  _defaultUser = "user"
)

func f(list []int) {
  var filtered []int
  for _, v := range list {
    if v > 10 {
      filtered = append(filtered, v)
    }
  }
}

if err := ioutil.WriteFile(name, data, 0644); err != nil {
 return err
}

data, err := ioutil.ReadFile(name)
if err != nil {
   return err
}

if err := cfg.Decode(data); err != nil {
  return err
}
fmt.Println(cfg)
return nil

// sign.go
type signer struct {
  now func() time.Time
}
func newSigner() *signer {
  return &signer{
    now: time.Now,
  }
}
func (s *signer) Sign(msg string) string {
  now := s.now()
  return signWithTime(msg, now)
}


// sign_test.go
func TestSigner(t *testing.T) {
  s := newSigner()
  s.now = func() time.Time {
    return someFixedTime
  }
  assert.Equal(t, want, s.Sign(give))
}

// # 以下关键字是保留的，不能用作标识符。
break        default      func         interface    select
case         defer        go           map          struct
chan         else         goto         package      switch
const        fallthrough  if           range        type
continue     for          import       return       var

// # 预先声明的标识符,以下标识符在宇宙块中隐式声明：
Types:
	bool byte complex64 complex128 error float32 float64
	int int8 int16 int32 int64 rune string
	uint uint8 uint16 uint32 uint64 uintptr

Constants:
	true false iota

Zero value:
	nil

Functions:
	append cap close complex copy delete imag len
	make new panic print println real recover

// 示例1
var errorMessage string  // 不要使用关键字 error 作用域将被隐式覆盖
  // 此时 `errorMessage` 指向内置的非覆盖
// or
func handleErrorMessage(msg string) {
    // 此时 `errorMessage` 指向内置的非覆盖
}

// 示例2
type Foo struct {
    // `error` and `string` 现在是明确的。
    err error  // 不要使用 error 名称作为结构体元素
    str string // 不要使用 string 名称作为结构体元素
}
func (f Foo) Error() error {
    return f.err
}
func (f Foo) String() string {
    return f.str
}

wantError := `unknown error:"test"` // 而非 `"unknown name:\"test\""`

tests := []struct{
  op Operation
  want string
}{
  {Add, "add"},
  {Subtract, "subtract"},
}

user := User{
  FirstName: "John",
  LastName: "Doe",
}

tests := []struct{
  got string // give
  want int
}{
  {got: "0", want: 0},
  // ...
}

sval := T{Name: "foo"}
sptr := &T{Name: "bar"}

type AbstractList struct {}
// 添加将实体添加到列表中。
func (l *AbstractList) Add(e Entity) {
  // ...
}
// 移除从列表中移除实体。
func (l *AbstractList) Remove(e Entity) {
  // ...
}

// ConcreteList 是一个实体列表。
type ConcreteList struct {
  list *AbstractList   // 避免在具体的列表实现中嵌入
}
// 添加将实体添加到列表中。
func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}
// 移除从列表中移除实体。
func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

// ConcreteList 是一个实体列表。
type ConcreteList struct {
  list AbstractList
}
// 添加将实体添加到列表中。
func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}
// 移除从列表中移除实体。
func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

// package db
type Option interface {
  // ...
}

func WithCache(c bool) Option {
  // ...
}
 
func WithLogger(log *zap.Logger) Option {
  // ...
}
 
// Open creates a connection.
func Open(
  addr string,
  opts ...Option,
) (*Connection, error) {
  // ...
}

type options struct {
  cache  bool
  logger *zap.Logger
}
 
type Option interface {
  apply(*options)
}
 
type cacheOption bool
 
func (c cacheOption) apply(opts *options) {
  opts.cache = bool(c)
}
 
func WithCache(c bool) Option {
  return cacheOption(c)
}
 
type loggerOption struct {
  Log *zap.Logger
}
 
func (l loggerOption) apply(opts *options) {
  opts.logger = l.Log
}
 
func WithLogger(log *zap.Logger) Option {
  return loggerOption{Log: log}
}
 
// Open creates a connection.
func Open(
  addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    cache:  defaultCache,
    logger: zap.NewNop(),
  }
 
  for _, o := range opts {
    o.apply(&options)
  }
 
  // ...
}

// func printInfo(name string, isLocal, done bool)
printInfo("foo", true /* isLocal */, true /* done */)

type Region int
const (
  UnknownRegion Region = iota
  Local
)
 
type Status int
const (
  StatusReady Status= iota + 1
  StatusDone
  // Maybe we will have a StatusInProgress in the future.
)
func printInfo(name string, region Region, status Status)

func main() {
  body, err := readFile(path)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(body)
}

func readFile(path string) (string, error) {
  f, err := os.Open(path)
  if err != nil {
    return "", err
  }
  b, err := ioutil.ReadAll(f)
  if err != nil {
    return "", err
  }
  return string(b), nil
}

package main
func main() {
  if err := run(); err != nil {
    log.Fatal(err)
  }
}
func run() error {
  args := os.Args[1:]
  if len(args) != 1 {
    return errors.New("missing file")
  }
  name := args[0]
  f, err := os.Open(name)
  if err != nil {
    return err
  }
  defer f.Close()
  b, err := ioutil.ReadAll(f)
  if err != nil {
    return err
  }
  // ...
}

type F interface {
  f()
}

type S1 struct{}
func (s S1) f() {}

type S2 struct{}
func (s *S2) f() {}

var f1 F = S1{} // f1.f()无法修改底层数据
var f2 F = &S2{} // f2.f() 可以修改底层数据,给接口变量f2赋值时使用的是对象指针

type LogHandler struct {
  h   http.Handler
  log *zap.Logger
}
var _ http.Handler = LogHandler{}  // 关键点 ，看LogHandler 接口是否实现 http.Handler 接口类型。
func (h LogHandler) ServeHTTP(
  w http.ResponseWriter,
  r *http.Request,
) {
  // ...
}

type S struct {
  data string
}

func (s S) Read() string {
  return s.data
}
func (s *S) Write(str string) {
  s.data = str
}

// (1) map 类型实例化S结构体
sVals := map[int]S{1: {"A"}}
// 你只能通过值调用 Read
sVals[1].Read()
// 这不能编译通过：
//  sVals[1].Write("test")

// (2) map 类型实例化S结构体指针
sPtrs := map[int]*S{1: {"A"}}
// 通过指针既可以调用 Read，也可以调用 Write 方法
sPtrs[1].Read()
sPtrs[1].Write("test")

type F interface {
  f()
}

type S1 struct{}
func (s S1) f() {}
type S2 struct{}
func (s *S2) f() {}

s1Val := S1{}
s1Ptr := &S1{}
s2Val := S2{}  // # 关键点
s2Ptr := &S2{}

var i F
i = s1Val
i = s1Ptr
i = s2Ptr
// i = s2Val 代码无法通过编译。因为 s2Val 是一个值，而 S2 的 f 方法中没有使用值接收器

// Bad: 声明和初始化看起来非常相似的。
var (
  // m1 读写安全;
  // m2 在写入时会 panic
  m1 = map[T1]T2{}
  m2 map[T1]T2
)

// Good: 声明和初始化看起来差别非常大。
var (
  // m1 读写安全;
  // m2 在写入时会 panic
  m1 = map[T1]T2{}
  m2 map[T1]T2
)

// Bad
m := make(map[T1]T2, 3)
m[k1] = v1
m[k2] = v2
m[k3] = v3

// Good
m := map[T1]T2{
  k1: v1,
  k2: v2,
  k3: v3,
}

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = make([]Trip, len(trips))  // 关键点
  copy(d.trips, trips)
}
 
trips := ...
d1.SetTrips(trips)
 
// 这里我们修改 trips[0]，但不会影响到 d1.trips
trips[0] = ...

type Stats struct {
  mu sync.Mutex            // 同步锁
  counters map[string]int  // 字典
}

func (s *Stats) Snapshot() map[string]int {
  s.mu.Lock()
  defer s.mu.Unlock()

  result := make(map[string]int, len(s.counters)) // 内存申请
  for k, v := range s.counters {  // 遍历 counters
    result[k] = v   // 将 counters 字典值分贝赋予 k,v => result 字典变量
  }
  return result
}

// snapshot 现在是一个拷贝
snapshot := stats.Snapshot()

for n := 0; n < b.N; n++ {
  data := make([]int, 0, size)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}
// BenchmarkGood-4   100000000    0.21s

if x == "" {
// return []int{}  // 不推荐方式
  return nil  // 推荐方式
}

func isEmpty(s []string) bool {
// return s == nil
  return len(s) == 0
}

var nums []int
if add1 {nums = append(nums, 1)}
if add2 {nums = append(nums, 2)}

p.Lock()
defer p.Unlock()

if p.count < 10 {
  return p.count
}

p.count++
return p.count

// 更可读

// 推荐方式
var mu sync.Mutex
mu.Lock()

// 1.为私有类型或需要实现互斥接口的类型嵌入。
// 最好的方式是直接嵌入到结构体中
type smap struct {
  sync.Mutex   // only for unexported types（仅适用于非导出类型）
  data map[string]string
}

func newSMap() *smap {
  return &smap{
    data: make(map[string]string),
  }
}

func (m *smap) Get(k string) string {
  m.Lock()
  defer m.Unlock()
  return m.data[k]
}


// 2.对于导出的 (公共的方式) 类型，请使用专用字段。
type SMap struct {
  mu sync.Mutex // 对于导出类型，请使用私有锁
  data map[string]string
}

func NewSMap() *SMap {
  return &SMap{
    data: make(map[string]string),
  }
}

func (m *SMap) Get(k string) string {
  m.mu.Lock()  			// 读写锁
  defer m.mu.Unlock()   // 程序结束后接锁
  return m.data[k]
}

// package foo (包)
var ErrCouldNotOpen = errors.New("could not open")
func Open() error {
  return ErrCouldNotOpen
}

// package bar (调用)，返回错误的对象。
if err := foo.Open(); err != nil {
    // 判断 错误，是否是 ErrCouldNotOpen
  if errors.Is(err, foo.ErrCouldNotOpen) {
    // 输出 error handle
  } else {
    panic("unknown error")
  }
}

// 自定义错误结构体
type errNotFound struct {
  file string
}
// 错误方法
func (e errNotFound) Error() string {
  return fmt.Sprintf("file %q not found", e.file)
}
// 返回错误结构体对象
func open(file string) error {
  return errNotFound{file: file}
}

func use() {
  // 指定在open函数输入信息。
  if err := open("testfile.txt"); err != nil {
    // 返回指定的错误信息
    if _, ok := err.(errNotFound); ok {
      // handle
    } else {
      panic("unknown error")
    }
  }
}

// package foo
type errNotFound struct {
  file string
}
func (e errNotFound) Error() string {
  return fmt.Sprintf("file %q not found", e.file)
}

// 判断是否找到错误
func IsNotFoundError(err error) bool {
  _, ok := err.(errNotFound)
  return ok
}
func Open(file string) error {
  return errNotFound{file: file}
}

// package bar ：指定在open函数输入信息
if err := foo.Open("foo"); err != nil {
  if foo.IsNotFoundError(err) {
    // 输出指定错误信息 handle
  } else {
    panic("unknown error")
  }
}

s, err := store.New()
if err != nil {
    return fmt.Errorf(
        "new store: %v", err)
}

x: y: new store: the error

t, ok := i.(string)
if !ok {
  // 优雅地处理错误
}

func run(args []string) error {
  if len(args) == 0 {
    return errors.New("an argument is required")
  }
  // ...
  return nil
}
 
func main() {
  if err := run(os.Args[1:]); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)  // 如果错误就退出程序
  }
}

var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML"))

// func TestFoo(t *testing.T)
 
f, err := ioutil.TempFile("", "test")
if err != nil {
  t.Fatal("failed to set up test")
}

type foo struct {
  running atomic.Bool
}
 
func (f *foo) start() {
  if f.running.Swap(true) {
     // already running…
     return
  }
  // start the Foo
}
 
func (f *foo) isRunning() bool {
  return f.running.Load()
}

// 示例代码
// 大小：1
c := make(chan int, 1)

// 无缓冲 channel，大小为 0
c := make(chan int)

// 声明 int 类型别名
type Operation int
const (
  Add Operation = iota + 1 // 0 + 1
  Subtract
  Multiply
)
// Add=1, Subtract=2, Multiply=3

// 声明 int 类型别名
type LogOutput int
const (
  LogToStdout LogOutput = iota  // 0
  LogToFile
  LogToRemote
)
// LogToStdout=0, LogToFile=1, LogToRemote=2

// 单元测试
func TestSplitStr(t *testing.T){...code...}
func Test_SplitStr(t *testing.T){...code...}

// 基准测试
func TestSplitStr(b *testing.B){...code...}
func Test_SplitStr(b *testing.B){...code...}

// 示例函数
func ExampleSplitStr(){...code...}
func Example_SplitStr(){...code...}

// func TestSplitHostPort(t *testing.T)

tests := []struct{
  give     string
  wantHost string
  wantPort string
}{  // 此种初始值得学习
  {
    give:     "192.0.2.0:8000",
    wantHost: "192.0.2.0",
    wantPort: "8000",
  },
  {
    give:     "192.0.2.0:http",
    wantHost: "192.0.2.0",
    wantPort: "http",
  },
  {
    give:     ":8000",
    wantHost: "",
    wantPort: "8000",
  },
  {
    give:     "1:8",
    wantHost: "1",
    wantPort: "8",
  },
}
 
for _, tt := range tests {
  t.Run(tt.give, func(t *testing.T) {
    host, port, err := net.SplitHostPort(tt.give)
    require.NoError(t, err)
    assert.Equal(t, tt.wantHost, host)
    assert.Equal(t, tt.wantPort, port)
  })
}

for i := 0; i < b.N; i++ {
  // s := fmt.Sprint(rand.Int()) // 不推荐类型转换
  s := strconv.Itoa(rand.Int()) // 推荐
}

data := []byte("Hello world") // 推荐
for i := 0; i < b.N; i++ {
  w.Write(data) // 推荐
  //  w.Write([]byte("Hello world"))  // 不推荐类型转换
}

// m 是在没有大小提示的情况下创建的； 在运行时可能会有更多分配。
m := make(map[string]os.FileInfo)
files, _ := ioutil.ReadDir("./files")
for _, f := range files {
    m[f.Name()] = f
}

// m 是有大小提示创建的；在运行时可能会有更少的分配。
files, _ := ioutil.ReadDir("./files")
m := make(map[string]os.FileInfo, len(files)) // 关键点
for _, f := range files {
    m[f.Name()] = f
}

for n := 0; n < b.N; n++ {
  data := make([]int, 0, size)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}

// 推荐方法 , 内置的时间比较方法 相比于比较运算符更精确。
func isActive(now, start, stop time.Time) bool {
//   return start <= now && now < stop // 不推荐
  return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}

// Bad
func poll(delay int) {
  for {
    // ...
    time.Sleep(time.Duration(delay) * time.Millisecond)
  }
}
poll(10) // 是几秒钟还是几毫秒?

// Good
func poll(delay time.Duration) {
  for {
    // ...
    time.Sleep(delay)
  }
}
poll(10*time.Second) // 更加直观，让使用者自定义设定是妙或者毫秒

newDay := t.AddDate(0 /* years */, 0 /* months */, 1 /* days */)
maybeNewDay := t.Add(24 * time.Hour)

// {"intervalMillis": 2000}

type Config struct {
  IntervalMillis int `json:"intervalMillis"`
}

// Bad
msg := "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)

// Good
const msg = "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)

$ go vet -printfuncs=wrapf,statusf
// “go.vetFlags”: [“printfuncs=wrapf”]