Golang 常见规范

一、代码规范

1.1 包引入(import package)

// 建议使用标准库包、 项目内部包、第三方包的顺序引入包
import (
	// 标准库包
	"io"
	"net"
	"net/http"
	
	// 项目内部包
	conf "xxxxxx/Conf"
	udp  "xxxxxx/Udp"
	
	// github 第三方包
	"github.com/gin-gonic/gin"
)

1.2 变量、函数

// 全局变量， 变量名以驼峰命名法定义。如有其他包调用，首字母大写。包内调用，首字母避免大写
// 常量，驼峰命名法，首字母大写
var (
	boolValue []bool
	intValue []int

	uint32Value []uint32
	float32Value []float32
 	float64Value []float64
)

const(
	Length = 1
	Name = "a"
)

// 函数，函数名以驼峰命名法定义。如有其他包调用，首字母大写。包内调用，首字母避免大写
// 函数形参，相同类型使的形参 用同一个类型声明
// 函数输出，避免给类型赋名
func TestInit(a, b bool) error {
	// 如无全局变量纠缠（局部变量），使用 := 方式定义变量。首字母小写、驼峰
	boolValue := true
	BoolValue = make([]bool, 0, 10)
	BoolValue = append(BoolValue, []bool{a, b, boolValue, testBool()}...)
	return nil
}

func testBool() bool {
	return true
}

1.3 结构体定义 struct

// 结构体的申明和初始化采用多行
// 建议按照数据类型的大小，从小到大排序
// 结构体，驼峰命名，如有其他包调用，结构体名称首字母大写。包内调用，首字母避免大写
// 结构体成员， 驼峰命名，如有其他包调用，成员名称首字母大写，包内调用，避免首字母大写
type ClientTest struct {
	mu             	sync.Mutex		// 互斥锁
	ConnRemotePort 	int         	// 远端（服务端）端口号
	ConnType 		string      	// 链接类型 VCI PMM OHP
	HeartbeatCtr 	int64       	// 心跳计数
	Interval       	uint32      	// 数据间隔时长
	Conn    		*net.UDPConn 	// UDP链接
	Timer 			*time.Timer  	// 定时计数器
	WsMessageChan  	chan []byte 	// websocket 消息管道
	RegisterMessageChan  map[uint]*RegisterMessageChan  // 注册消息管道
}

1.4 文件名

// 文件名称可以用下划线区分，尽量避免
// 如果采用下划线命名，注意避免和下面特定用法冲突
1. 测试单元命名 _test.go
client_test.go
2. 系统相关文件
_386.go、_amd64.go、_arm.go、_arm64.go、_android.go、_darwin.go、
_dragonfly.go、_freebsd.go、_linux.go、_nacl.go、_netbsd.go、
_openbsd.go、_plan9.go、_solaris.go、_windows.go、_android_386.go、
_android_amd64.go、_android_arm.go、_android_arm64.go、_darwin_386.go、
_darwin_amd64.go、_darwin_arm.go、_darwin_arm64.go、_dragonfly_amd64.go、
_freebsd_386.go、_freebsd_amd64.go、_freebsd_arm.go、_linux_386.go、
_linux_amd64.go、_linux_arm.go、_linux_arm64.go、_linux_mips64.go、
_linux_mips64le.go、_linux_ppc64.go、_linux_ppc64le.go、_linux_s390x.go、
_nacl_386.go、_nacl_amd64p32.go、_nacl_arm.go、_netbsd_386.go、
_netbsd_amd64.go、_netbsd_arm.go、_openbsd_386.go、_openbsd_amd64.go、
_openbsd_arm.go、_plan9_386.go、_plan9_amd64.go、_plan9_arm.go、
_solaris_amd64.go、_windows_386.go、_windows_amd64.go

二、注释规范

2.1 包注释

// @Title  io.go
// @Description  定义io接口
// @Author  Go Team (2006/01/02 15:04:05)
// @Update  Gongsr-cn (2021/09/26 19:00:00)
package io

2.2 结构体注释（同 接口注释）

// ClientTest
// @Name 客户端测试
// @Description 把 udp 链接以及该链接的配置封装成一个ClientTest结构体对象
type ClientTest struct {
	Mu             	sync.Mutex		// 互斥锁
	ConnRemotePort 	int         	// 远端（服务端）端口号
	ConnType 		string      	// 链接类型 VCI PMM OHP
	HeartbeatCtr 	int64       	// 心跳计数
	Interval       	uint32      	// 数据间隔时长
	Conn    		*net.UDPConn 	// UDP链接
	Timer 			*time.Timer  	// 定时计数器
	WsMessageChan  	chan []byte 	// websocket 消息管道
	RegisterMessageChan  map[uint]*RegisterMessageChan  // 注册消息管道
}

2.3 函数注释

// DeCodeByProto
// @Description 字节流数据按照proto解码成proto.Message
// @Parameter port int 端口号
// @Parameter bytes []byte 字节流数据
// @Return proto.Message protoc.Message 数据 
// @Return error 错误信息
func DeCodeByProto(port int, bytes []byte) (proto.Message, error) {
	/*函数内部以功能分块*/

	// 数据帧头四字节信息
	header := bytes[:4]
	length := bytesToUint16(header[1:3])
	msgTypeCode := bytesToUint8(header[3:4])

	// 通过端口号区分数据解码流向
	msgBody := bytes[4:length+4]
	switch(port) {
	case 9000, 9010, 9020:
		return byteToProtoMsgWithVCI(conf.VCIMessage[msgTypeCode], msgBody)
	case 9030, 9040:
		return byteToProtoMsgWithPMM(conf.VCIMessage[msgTypeCode], msgBody)
	case 9030, 9050:
		return byteToProtoMsgWithOHP(conf.VCIMessage[msgTypeCode], msgBody)
	}
	
	return nil, errors.New("don't use bed prot")
}