本文最后更新于：2022年10月9日下午

类似于Java开发手册之类的

前言

本文中概述的一些标准都是客观性的评估，是根据场景、上下文、或者主观性的判断；

但是最重要的是，保持一致.

一致性的代码更容易维护、是更合理的、需要更少的学习成本、并且随着新的约定出现或者出现错误后更容易迁移、更新、修复 bug

相反，在一个代码库中包含多个完全不同或冲突的代码风格会导致维护成本开销、不确定性和认知偏差。所有这些都会直接导致速度降低、代码审查痛苦、而且增加 bug 数量

通用

注释

强制

每一个可导出(首字母大写)的函数、名称都应该有文档注释
关键流程和关键算法都应该有注释。
一些魔法数字或者妥协而加的代码都应该有注释说明为什么需要添加

注释不应该写是什么，而应该写为什么。比如说我有一段休眠代码

for i := range arr {
  if i%500 == 0{
    // 睡眠一段时间
    time.Sleep(500)
  }
}

写 “睡眠一段时间” 这个注释是无效的，后续看代码的同学还是不清楚为什么要休眠，

但是应该写 “为了缓解服务器压力，这里等待一段时间再做逻辑” 就很清晰了

Bad

1	`func Complie(str string) (regexp *Regexp,err error)`

Good

1 2	`// Complie 用于解析正则表达式并返回，如果成功，则 Regexp 对象就可用于匹配所针对的文本。 func Complie(str string) (regexp *Regexp,err error)`

内存管理

强制

切片长度校验

对slice进行操作时，必须判断长度是否合法，防止程序Panic

Bad

1
2
3

func foo(data []int) bool {
  return data[0] == 0
}

Good

func foo(data []int) bool {
  if data == nil || len(data) == 0{
    return false
	}
  return data[0] == 0
}

nil指针判空

进行指针操作时，需要判断该指针是否为空，防止程序Panic，在Get函数中时如果时指针引用也必须判断指针是否为空，尤其是在结构体进行Unmarshal之后

Bad

func foo(src []byte) error {
  var dest = new(Data)
  err := json.Unmarshal(src)
  if err!=nil{
    return err
  }
  use(dest.Member.UserName) // panic
  return 
}

Good

func foo(src []byte) error {
  if src == nil || len(src) == 0{
    return ErrSliceIsEmpty
  }
  var dest = new(Data)
  err := json.Unmarshal(src)
  if err!=nil{
    return err
  }
  if dest.Member == nil{
    return Err
  }
  use(dest.Member.UserName)
  return 
}

Get函数中也必须判空

Bad

1
2
3

func (m *Member) UserName() string{
  return m.UserName
}

Good

func (m *Member) UserName() string{
  if m == nil{
    return ""
  }
  return m.UserName
}

make预分配长度

在进行make内存分配时，尽可能指定容器容量，以便为容器预先分配内存

Bad

func foo(list []int) []int {
  var res = make([]int, 0)
  for _, item:=range list{
    if item == 0{
      continue
    }
    res = append(res, item) // append 函数会存在大量的内存拷贝
  }
  return res
}

Good

func foo(list []int) []int {
  var res = make([]int, 0 ,len(list))
  for _, item:=range list{
    if item == 0{
      continue
    }
    res = append(res, item)
  }
  return res
}

禁止重复释放channel

重复释放一般存在于异常流程判断中，如果恶意攻击者构造出异常条件使程序重复释放channel，则会触发运行时panic，从而造成DoS攻击。

Bad

func foo(c chan int) {
	defer close(c)
	err := processBusiness()
	if err != nil {
		c <- 0
		close(c) // 重复释放channel
		return
	}
	c <- 1
}

Good

func foo(c chan int) {
	defer close(c) // 使用defer延迟关闭channel
	err := processBusiness()
	if err != nil {
		c <- 0
		return
	}
	c <- 1
}

确保每个协程都能退出

启动一个协程就会做一个入栈操作，在系统不退出的情况下，协程也没有设置退出条件，则相当于协程失去了控制，它占用的资源无法回收，可能会导致内存泄露。

// bad: 协程没有设置退出条件
func doWaiter(name string, second int) {
	for {
		time.Sleep(time.Duration(second) * time.Second)
		fmt.Println(name, " is ready!")
	}
}

字符串

强制

字符串拼接

禁止使用+号进行字符串拼接操作，如果需要使用请使用 strings.Builder

Bad

for foo(){
  var str1 = "str1"
  var str2 = "str2"
  fmt.Println(str1+str2)
}

Good

for foo(){
  var str1 = "str1"
  var str2 = "str2"
  var str3 strings.Builder
  str3.Grow(len(str1)+len(str2))
  str3.WriteString(str1)
  str3.WriteString(str2)
  fmt.Println(str3.String())
}

取字符串的某个字符

如果需要取字符串的某个字符，除非非常确定字符串中只含有ANSCII的字符，否则都必须将string转为[]rune类型

Bad

1 2	`var str string = "你好" var firstChar = str[0]`

Good

1 2	`var str string = "你好" var firstChar = []rune(str)[0]`

禁止使用fmt进行类型转化

如果要将 int64、float等数字类型转化为string的话，禁止使用fmt.Sprintf进行类型转化，它的内部使用反射判断类型，性能相对较差

Bad

1
2
3

var str string
var num  =10
str = fmt.Sprintf("%v",num)

Good

1
2
3

var str string
var num  =10
str = strconv.Itoa(num)

异常处理

强制

协程中一定要recover

在协程中处理一定要recover掉panic，否则会导致整个进程都退出，并且要尽可能的打印全崩溃信息

// good
func foo(f func()){
  go func() {
		defer func() {
			if err := recover(); err != nil {
        buf := debug.Stack()
				logrus.Errorf("SafeGo.recover :%v stack:%v", err, string(buf))
			}
		}()
		f()
	}()
}

// bad 
func foo(f func()){
  go f()
}

合理使用panic

如果问题可以被屏蔽或者被解决，那么最好让程序继续运行，比如说在某个接口中因为客户端传入了某种特殊值导致崩溃的话最好使用 recover 兜住，但是针对于某些库不能正常工作并且程序就无法继续运行的情况下，最好就Panic出去。比如说数据库连接不上、某些重要配置未配置

var stage = os.Getenv("STAGE")

func init(){
  if stage == ""{
    panic("no value for $STAGE")
  }
}

时间日期

强制

不要在程序中写死一年为365天，一个月为30天，避免在闰年等情况下出现逻辑错误
禁止使用 time.Now() 来获取当前时间，获取的时间为系统默认时区，在Format时间时会出现异常
不要给前端、客户端返回字符串形式的时间类型，也不要接受它们的字符串形式的时间类型，在进行时间类型传输时一律使用秒级时间戳进行通信
必须使用 time.Duration代表某个时间段，禁止直接采用魔法数字来代表时间段。

控制语句

强制

在高并发场景时，避免使用 “等于” 判断作为中断或者退出的条件。这是因为如果并发处理没有控制好的情况下，可能值会出现值被“击穿”的情况，最好使用大于、小于的区间判断来代替

Bad	Good
`if condition { return err } else { // 这里写else的代码 }`	`if condition { return err } // 这里写else的代码`

SQL操作

强制

SQL语句默认使用预编译并绑定变量
禁止拼接SQL语句，对于传入的参数用于order by或者表名等必须通过校验

程序结构

强制

代码的每一层结构都必须有一个地方接受Context，可以放在函数中也可以放在结构体中，但是放在结构体中时务必保证每次使用结构体都初始化。
在引入一个新的代码库依赖时必须保证它的子依赖对现有的的仓库不会有影响。
禁止引入非稳定、未经过测试的代码库。
核心代码、公共common库应该做到测试全复盖

日志

强制

禁止使用 fmt、自行书写的logger库来打印日志。日志打印一定要使用 logurs 库。同时在生成logrus.Entry结构时需要携带上ctx参数。
对于敏感操作必须要打印一条日志代表玩家操作过。比如说玩家修改自己的密码。
强制使用日志分级。分为四个等级：debug、info、warn、error
正式环境禁止打印debug日志
logrus强制使用 JSON Format

服务

强制

用户请求传入的任何参数必须做有效性验证
用户输入的SQL参数严格使用参数绑定。防止sql注入、拼接sql字符串访问数据库。对于string类型的参数应该格外注意
对于暴露在外部的接口严格使用${serverName}/${type}/${version}/* 。其中${serverName} 为项目名。${type} 限定三个类型：app代表暴露在app端的接口， rpc代表rpc接口，backend代表后台接口。${version} 代表接口版本。
暴露在外的接口要做玩家token验证。
隶属于用户个人的页面或者功能必须进行权限控制校验
用户敏感数据禁止直接展示，必须对数据进行脱敏

Go书写建议

前言

通用

注释

强制

推荐

内存管理

强制

切片长度校验

nil指针判空

make预分配长度

禁止重复释放channel

确保每个协程都能退出

推荐

不使用unsafe包

字符串

强制

字符串拼接

取字符串的某个字符

禁止使用fmt进行类型转化

推荐

cast包

避免反复类型转化

zero copy

异常处理

强制

协程中一定要recover

合理使用panic

推荐

崩溃信息统计

error处理

时间日期

强制

推荐

控制语句

强制

推荐

SQL操作

强制

推荐

程序结构

强制

推荐

日志

强制

推荐

服务

强制

推荐