golang编码最佳实践(持续更新中)

最近在学习go语言，以此记录日常编码中的最佳实践，欢迎大家一起讨论

注释模板

使用Goanno插件：https://github.com/loveinsky100/goanno

设置模板

以goland为例

1. 选择"工具-Goanno设置"

2. 编辑模板

   // ${function_name} ${todo}
   // @receiver ${receiver}
   // @param ${params}
   // @return ${return_types}

案例

// GetNode 获取指定结构，从缓存加载
//
//	@receiver c
//	@param ctx
//	@param countryCode	国家码
//	@return *Node
func (c *Cache) GetNode(ctx context.Context, countryCode string) *Node, error {
	...
	return cacheNode, nil
}

日志打印

建议使用zap的零内存分配api，性能比go标准库的api好：GitHub - uber-go/zap: Blazing fast, structured, leveled logging in Go.

格式处理

• %v: 根据值的类型自动选择合适的格式输出。
• %+v: 类似 %v，但会输出更多的信息，如字段名称。
• %#v: 输出值的完整 Go 语法表示，包括类型信息。
• 不要直接打印byte[]类型等无实际意义的日志，应该转成string打印。

错误处理

go最受争议的部分之一就是错误处理，这里不去讨论其好坏，仍然推荐大家使用官方的处理方式：返回error接口，不建议使用panic + recover，容易导致程序崩溃

func f() error {
    if ... {
        return errors.New("xxx")
    }
    return nil
}

解决error无堆栈

部分goer建议使用panic + recover就是因为其有堆栈而error没有，但我们可以实现新的error接口时增加堆栈记录

type BizError struct {
	code    string
	message string
	cause   error

	stacktrace struct {
		onCreate *stacktrace
		onPanic  *stacktrace
	}
}

// NewBizError create a new BizError
//   - cause can be nil is no underlying error
//   - omitStacks indicates how many frames should be dropped, if <=0 no stacks will be filled
func NewBizError(code api.ResultCode, message string, cause error, omitStacks int, throwInPlace bool) *BizError {
	err := &BizError{
		code:    code.Code(),
		message: message,
		cause:   cause,
	}
	if omitStacks >= 0 {
		err.stacktrace.onCreate = dumpStacktrace(omitStacks + 1)
		if throwInPlace {
			err.stacktrace.onPanic = err.stacktrace.onCreate
		}
	}
	return err
}

func (this *BizError) Error() string {
	if len(this.message) > 0 {
		return this.code + ": " + this.message
	} else {
		return this.code + ": [NO_MESSAGE]"
	}
}

type stacktrace struct {
	header []byte // goroutine header (e.g., "goroutine 3 [running]:")
	frames []byte // the stacktrace details
}

func dumpStacktrace(skip int) *stacktrace {
	skip += 2 // skip debug.Stack and this frame
	skip *= 2 // 2-line each frame
	stack := debug.Stack()
	var header []byte
	for i, b := range stack { // assumes no unicode in stack, iterate on bytes
		if b == '\n' {
			if header == nil {
				// consume first line as goroutine header
				header = stack[:i]
			} else {
				skip--
				if skip == 0 {
					stack = stack[i:]
					break
				}
			}
		}
	}
	if skip > 0 {
		panic("skip overflow")
	}
	return &stacktrace{header, stack}
}

这样使用时即可记录堆栈

类型转换

因为 Golang 语言是强类型，所以经常会使用到类型转换，所以在这里推荐类型转换三方库：GitHub - spf13/cast: safe and easy casting from one type to another in Go

cast.ToString("mayonegg")         // "mayonegg"
cast.ToString(8)                  // "8"
cast.ToString(8.31)               // "8.31"
cast.ToString([]byte("one time")) // "one time"
cast.ToString(nil)                // ""

var foo interface{} = "one more time"
cast.ToString(foo)                // "one more time"

cast.ToInt(8)                  // 8
cast.ToInt(8.31)               // 8
cast.ToInt("8")                // 8
cast.ToInt(true)               // 1
cast.ToInt(false)              // 0

var eight interface{} = 8
cast.ToInt(eight)              // 8
cast.ToInt(nil)                // 0

json工具

golang原生对json已经做了很好的支持，简单易用，但其性能一直为人垢病，因此建议使用字节开源的工具sonic。除了能平替原生的json使用姿势外，在性能上面也是从底层方面做了很多文章进行优化，性能方面遥遥领先：sonic：基于 JIT 技术的开源全场景高性能 JSON 库_原生云_火山引擎开发者社区_InfoQ写作社区

web/rpc服务

单独为某个下游接口设置超时时间

要知道go的超时时间不像java那样每个调用都固定超时时间，而是以总体时间来计算，但有时部分下游就是需要超出原超时时间进行（当然必须是异步调用，否则就自相矛盾了），具体代码如下：

// 注意：必须先cancel再设置，否则只能设置比原来时间更短的时间
func TestTimeout(t *testing.T) {
	ctx := context.Background()
	ctx, _ = context.WithTimeout(ctx, time.Second*3)
	ctx, _ = context.WithTimeout(ctx, time.Second*6)

	deadline, _ := ctx.Deadline()
	fmt.Println(deadline.Sub(time.Now())) // 2.99s, 直接覆盖设置不生效

	ctx, _ = context.WithTimeout(ctx, time.Second*1)
	deadline, _ = ctx.Deadline()
	fmt.Println(deadline.Sub(time.Now())) // 0.99s 设置更短时间, 生效

	ctx = context.WithoutCancel(ctx)                 // 取消
	ctx, _ = context.WithTimeout(ctx, time.Second*6) // 重新设置
	deadline, _ = ctx.Deadline()
	fmt.Println(deadline.Sub(time.Now())) // 5.99s, 取消后再设置, 才生效
}

proto参数校验

建议使用PGV：GitHub - bufbuild/protoc-gen-validate: Protocol Buffer Validation - Being replaced by github.com/bufbuild/protovalidate

这样会再生成一个proto的validate文件

建议consumer在远程调用前先调用validate方法，当参数不合法时提前感知

func remote(ctx context.Context) {
    request := ...
    if err := request.ValidateAll(); err != nil {
		return nil, errors.New(err.Error())
	}
    remoteClient.GetXXX(ctx, request)
}

provider在实现时也必须调用validate，防止参数不合法

func (s *server) Remote(ctx context.Context, request XXX) Response, error {
    if err := request.ValidateAll(); err != nil {
		return nil, errors.New(err.Error())
	}
    // 处理逻辑
}

但每个方法都要加validate重复代码，有没有办法统一处理参数校验呢，当然是有的

type validator interface {
	ValidateAll() error
}

// ValidateAllInterceptor
//
//	@Description: grpc服务注册的参数校验拦截器
//	@return grpc.UnaryServerInterceptor
func ValidateAllInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (reply interface{}, err error) {
		if v, ok := req.(validator); ok {
			if err := v.ValidateAll(); err != nil {
				return nil, err
			}
		}
		return handler(ctx, req)
	}
}