引言
一、相关联的声明放到一起
1、导包规范
2、常量、变量、类型声明
二、Go错误处理
1、失败的原因只有一个时，不使用 error
2、没有失败时，不使用 error
3、错误值统一定义
三、代码规范与实践
1、良好的命名与注释
2、美化SQL语句，避免 Select
3、避免阶梯缩进与代码紧凑
4、避免循环IO、上下文无关联的耗时动作采用Go协程
引言编写代码应该要有极客追求，不要一味的只为了完成功能不加思索而噼里啪啦一顿操作，我认为应该要像一位设计者一样去设计代码完成功能，因为好的代码设计清晰可读易扩展、好修复、更少的学习成本。
因此我们应该学习并制定一些代码规范，如下是我学习Go语言中实战总结的一些经验，仅代表个人观点，大家可以互相讨论一下
一、相关联的声明放到一起 1、导包规范// Bad
import "logics/user_logic"
import "logics/admin_logic"
import "logics/goods_logic"
// good
import (
"logics/user_logic"
"logics/admin_logic"
"logics/goods_logic"
)
分组导包
内置库
其他库
相关联库放在一起
// Bad
import (
"fmt"
"logics/user_logic"
"logics/admin_logic"
"strings"
)
// Good
import (
"fmt"
"strings"
// 逻辑处理
"logics/user_logic"
"logics/admin_logic"
// 数据库相关操作
"db/managers"
"db/models"
)
2、常量、变量、类型声明
在定义一些常量、变量与类型声明的时候，也是一样可以把相关联放到一起
常量
// Bad
const YearMonthDay = "2006-01-02"
const YearMonthDayHourMinSec = "2006-01-02 15:04:05"
const DefaultTimeFmt = YearMonthDayHourMinSec
// Good
// TimeFormat 时间格式化
type TimeFormat string
const (
YearMonthDay TimeFormat = "2006-01-02" // 年月日 yyyy-mm-dd
YearMonthDayHourMinSec TimeFormat = "2006-01-02 15:04:05" // 年月年时分秒 yyyy-mm-dd HH:MM:SS
DefaultTimeFmt TimeFormat = YearMonthDayHourMinSec // 默认时间格式化
)
变量
// Bad
var querySQL string
var queryParams []interface{}
// Good
var (
querySQL string
queryParams []interface{}
)
类型声明
// Bad
type Area float64
type Volume float64
type Perimeter float64
// Good
type (
Area float64 // 面积
Volume float64 // 体积
Perimeter float64 // 周长
)
枚举常量
// TaskAuditState 任务审核状态
type TaskAuditState int8
// Bad
const TaskWaitHandle TaskAuditState = 0 // 待审核
const TaskSecondReview TaskAuditState = 1 // 复审
const TaskPass TaskAuditState = 2 // 通过
const TaskRefuse TaskAuditState = 3 // 拒绝
// Good
const (
TaskWaitHandle TaskAuditState = iota // 待审核
TaskSecondReview // 复审
TaskPass // 通过
TaskRefuse // 拒绝
)
在进行Go开发时，指定一些非必选的入参时，不好区别空值是否有意义
如下 AuditState 是非必选参数，而 AuditState 在后端定义是 0 审核中、1复审、2通过、3拒绝，这都没什么问题，但框架解析参数时会把入参模型结构没有传值的参数设置成默认值，字符串类型是空串、数字类型是0等， 这样就会有问题如果前端传递参数的值是0、空值或者没有传递时，则无法判断是前端传递过来的还是框架默认设置的，导致后续逻辑不好写。
// QueryAuditTaskIn 查询任务入参
type QueryAuditTaskIn struct {
TeamCode string `query:"team_code" validate:"required"` // 团队编码
TaskType enums.RiskType `query:"task_type" validate:"required"` // 任务类型
TagId int `query:"tag_id" validate:"required"` // 标签id
AuditState constants.TaskAuditState `query:"audit_state"` // 审核状态
}
解决办法就是设计时让前端不要传递一些空值，整型枚举常量设置成 从1开始，这样更好的处理后续逻辑。
// TaskAuditState 定义审核状态类型
type TaskAuditState int8
const (
TaskWaitHandle TaskAuditState = iota + 1 // 待审核
TaskSecondReview // 复审
TaskPass // 通过
TaskRefuse // 拒绝
)
在Go开发中会出现好多if err != nil 的判断
尤其我在使用 manager 操作数据库时一调用方法就要处理错误，还要向上层依次传递
manager（数据库操作层） -> logic（逻辑层） -> api（接口层），每一层都要处理错误从而导致
一大堆的 if err != nil
// DelSensitive 删除内部敏感词
func (sl SensitiveLogic) DelSensitive(banWordId uint32) error {
banWordManager, err := managers.NewBanWordsManager()
if err != nil {
return err
}
banWords, err := banWordManager.GetById(banWordId)
if err != nil{
return err
}
if banWords == nil {
return exceptions.NewBizError("屏蔽词不存在")
}
_, err = banWordManager.DeleteById(banWordId)
if err != nil {
return err
}
// 删除对应的敏感词前缀树，下一次文本审核任务进来的时候会重新构造敏感词前缀树
banWordsModel := banWords.(*models.BanWordsModel)
sensitive.DelTrie(banWordsModel.Scene, banWordsModel.TeamCode)
return nil
}
这样代码太不美观了如果改成如下看看
// DelSensitive 删除内部敏感词
func (sl SensitiveLogic) DelSensitive(banWordId uint32) {
banWordManager := managers.NewBanWordsManager()
banWords := banWordManager.GetById(banWordId)
if banWords == nil {
return
}
banWordManager.DeleteById(banWordId)
// 删除对应的敏感词前缀树，下一次文本审核任务进来的时候会重新构造敏感词前缀树
banWordsModel := banWords.(*models.BanWordsModel)
sensitive.DelTrie(banWordsModel.Scene, banWordsModel.TeamCode)
}
是不是美观多了，但这样出现出错误不能很好的定位到错误的位置以及日志记录，还会 panic 抛错误出来，导致协程终止执行，要等到 recover 恢复协程来中止 panic 造成的程序崩溃，从而影响性能。处理与不处理各有好处，我个人认为错误应该要处理但不要无脑的 if err != nil ， 从而
可以在设计与规范上面来解决，对于一些严重的一定会导致程序奔溃的错误，可以自己统一设计错误类型，例如 数据库error 和 网络error 等，这种是很难避免的，即是避免了，系统也不能正常处理逻辑，因此对于这些 严重的错误可以手动 panic 然后在全局错误处理中记录日志信息，从而减少代码中的 if err != nil 的次数。如下
这样就不用一层一层传递 error ，但缺乏日志信息，虽然可以在上面的代码中打印日志信息，这样不太好，因此可以到全局错误那统一处理
这里是之前的想法可以考虑下，但像一些业务异常太多了就会频繁 panic，导致性能不佳以及后续的一些协程问题，所以我上文提到自己设计错误以及规范，什么错误、异常可以 panic 什么不可以，从而来减少 if err != nil。
其次就是在设计函数的来避免错误的出现
1、失败的原因只有一个时，不使用 error我们看一个案例：
func (self *AgentContext) CheckHostType(host_type string) error {
switch host_type {
case "virtual_machine":
return nil
case "bare_metal":
return nil
}
return errors.New("CheckHostType ERROR:" + host_type)
}
我们可以看出，该函数失败的原因只有一个，所以返回值的类型应该为 bool，而不是 error，重构一下代码：
func (self *AgentContext) IsValidHostType(hostType string) bool {
return hostType == "virtual_machine" || hostType == "bare_metal"
}
说明：大多数情况，导致失败的原因不止一种，尤其是对 I/O 操作而言，用户需要了解更多的错误信息，这时的返回值类型不再是简单的 bool，而是 error。
2、没有失败时，不使用 errorerror 在 Golang 中是如此的流行，以至于很多人设计函数时不管三七二十一都使用 error，即使没有一个失败原因。我们看一下示例代码：
func (self *CniParam) setTenantId() error {
self.TenantId = self.PodNs
return nil
}
对于上面的函数设计，就会有下面的调用代码：
err := self.setTenantId()
if err != nil {
// log
// free resource return errors.New(...)
}
根据我们的正确姿势，重构一下代码：
func (self *CniParam) setTenantId() {
self.TenantId = self.PodNs
}
于是调用代码变为：
self.setTenantId()
3、错误值统一定义
很多人写代码时，到处 return errors.New(value)，而错误 value 在表达同一个含义时也可能形式不同，比如“记录不存在”的错误 value 可能为：
errors.New("record is not existed.")
errors.New("record is not exist!")
errors.New("订单不存在")
这使得相同的错误 value 撒在一大片代码里，当上层函数要对特定错误 value 进行统一处理时，需要漫游所有下层代码，以保证错误 value 统一，不幸的是有时会有漏网之鱼，而且这种方式严重阻碍了错误 value 的重构。
在每个业务系统中维护一个错误对象定义文件，一些公用的错误则封装到Go的公用库中
业务系统错误封装：
package exceptions
// err_struct.go
// OrderBizError 订单系统业务错误结构体
type OrderBizError struct {
message string // 错误信息
code ErrorCode // 响应码
sysName string // 系统名称
}
func NewOrderBizError(message string, errorCode ...ErrorCode) *OrderBizError {
code := FailCode
if len(errorCode) > 0 {
code = errorCode[0]
}
return &OrderBizError{
code: code,
message: message,
sysName: "HuiYiMall—OrderSystem", // 可抽到微服务公用库中
}
}
// Code 状态码
func (b OrderBizError) Code() ErrorCode {
return b.code
}
// Message 错误信息
func (b OrderBizError) Message() string {
return b.message
}
// err_const.go
// ErrorCode 定义错误code类型
type ErrorCode string
const (
OrderTimeoutErrCode ErrorCode = "4000" // 订单超时
OrderPayFailErrCode ErrorCode = "4001" // 订单支付失败
)
var (
OrderTimeoutErr = NewOrderBizError("order timeout", OrderTimeoutErrCode)
OrderPayFailErr = NewOrderBizError("order pay fail", OrderPayFailErrCode)
)
返回错误信息给前端则返回状态码和信息，日志则记录全部的错误信息
Go公用库错误封装：
// err_struct.go
// BizError 业务错误结构体
type BizError struct {
message string // 错误信息
code ErrorCode // 响应码
}
// Code 状态码
func (b BizError) Code() ErrorCode {
return b.code
}
// Message 错误信息
func (b BizError) Message() string {
return b.message
}
func NewBizError(message string, errorCode ...ErrorCode) *BizError {
code := FailCode
if len(errorCode) > 0 {
code = errorCode[0]
}
return &BizError{
code: code,
message: message,
}
}
// err_const.go
const (
SuccessCode ErrorCode = "0000" // 成功
FailCode ErrorCode = "0403" // 失败
AuthorizationCode ErrorCode = "0403" // 认证错误
// ...
)
var (
Success = NewOrderBizError("Success", SuccessCode)
FailErr = NewOrderBizError("Fail", FailCode)
AuthorizationErr = NewOrderBizError("Authorization Error", AuthorizationCode)
// ...
)
其实每个业务系统的结构体可以继承公用的
// BizError 业务错误结构体
type BizError struct {
message string // 错误信息
code ErrorCode // 响应码
}
// OrderBizError 订单系统业务错误结构体
type OrderBizError struct {
BizError
sysName string // 系统名称
}
然后使用的时候就可以不要每次都自己单独的定义错误码和信息
三、代码规范与实践 1、良好的命名与注释生成Swaager接口文档注释尽量对齐
// QueryAuditTask 查询已领取的审核任务
// @Summary 查询已领取的审核任务
// @Tags 审核管理接口
// @Accept json
// @Produce json
// @Param team_code query string true "团队编码"
// @Param task_type query string true "风控类型"
// @Param tag_id query string true "审核任务类型标签ID"
// @Param audit_state query int false "任务审核状态 1待审核 2复审 3通过 4拒绝"
// @Success 200 {object} rsp.ResponseData
// @Router /task.audit.list_get [get]
func QueryAuditTask(ctx *fiber.Ctx) error {
路由注释少不
入参出参结构体注释少不了
// QueryAuditTaskIn 领取任务入参
type QueryAuditTaskIn struct {
TeamCode string `query:"team_code" validate:"required"` // 团队编码
TaskType enums.RiskType `query:"task_type" validate:"required"` // 任务类型
TagId int `query:"tag_id" validate:"required"` // 标签id
AuditState constants.TaskResultType `query:"audit_state"` // 审核状态
}
// TaskListItem 任务列表项
type TaskListItem struct {
Id uint32 `json:"id"` // 主键id
TeamCode string `json:"team_code"` // 团队编码
ObjectType enums.ObjectType `json:"object_type"` // 对象类型
ObjectId string `json:"object_id"` // 对象ID
TaskType enums.RiskType `json:"task_type"` // 任务类型
Content datatypes.JSON `json:"content"` // 任务内容
TagId uint32 `json:"tag_id"` // 标签ID
TaskResult constants.TaskResultType `json:"task_result"` // 任务审核结果
ReviewerId uint32 `json:"reviewer_id"` // 领取任务人ID
AuditReason string `json:"audit_reason"` // 审核理由
SourceList []interface{} `json:"source_list"` // 溯源列表
CreateTs int64 `json:"create_ts"` // 任务创建的时间戳
}
一些复杂的嵌套结构最好写上样例
// 获取全部的团队列表
teamSlice := rmc.getAllTeam()
// 统计各审核任务未领取数量
tagTaskCountMap := rmc.getTagTaskCount()
// 获取所有task_group标签与其二级标签
tagMenuSlice := rmc.getTagMenu()
// 将风控审核菜单信息组装到各个团队中并填充统计数量
// eg: [
// {
// "team_code": "lihua",
// "team_name": "梨花"
// "task_count": 1
// "tag_menus": [{"tag_id": 1, "tag_name": "文本", "tag_type": "task_group", "task_count":1, "child_tags": []}, ...]
// },
// ...
//]
riskMenuSlice := make([]*TeamMenuItem, 0)
for _, team := range *teamSlice {
// 填充各审核类型未领取任务数量
newTagMenuSlice := rmc.FillTagTaskCount(tagTaskCountMap, team, tagMenuSlice)
// 填充各团队未领取任务总数
teamTaskCount := uint32(0)
if tagCountMap, ok := tagTaskCountMap[team.TeamCode]; ok {
for _, tagTaskCount := range tagCountMap {
teamTaskCount += tagTaskCount
}
}
teamMenuItem := TeamMenuItem{
TeamCode: team.TeamCode,
TeamName: team.TeamName,
TaskCount: teamTaskCount,
TagMenus: newTagMenuSlice,
}
riskMenuSlice = append(riskMenuSlice, &teamMenuItem)
}
riskMenuMap := map[string]interface{}{
"work_menu": riskMenuSlice,
}
2、美化SQL语句，避免 Select
一些长的SQL语句不要写到一行里面去，可以使用 `` 原生字符串 达到在字符串中换行的效果从而美化SQL语句，然后就是尽量需要什么业务数据就查什么，避免Select * 后再逻辑处理去筛选
queryField := `
task.id AS task_id,
tag_name,
staff.real_name AS staff_real_name,
staff_tar.audit_reason AS staff_audit_reason,
staff_tar.review_result AS staff_review_result,
staff_tar.review_ts AS staff_review_ts,
chief.real_name AS chief_real_name,
chief_tar.audit_reason AS chief_audit_reason,
chief_tar.review_result AS chief_review_result,
chief_tar.review_ts AS chief_review_ts,
task.content AS task_content,
task.json_extend AS task_json_ext,
tar.json_extend AS audit_record_json_ext`
querySQL := `
SELECT
%s
FROM
task_audit_log AS tar
JOIN task ON tar.task_id = task.id
JOIN tag ON task.tag_id = tag.id
LEFT JOIN task_audit_log AS staff_tar ON task.id = staff_tar.task_id AND staff_tar.reviewer_role = "staff"
LEFT JOIN reviewer AS staff ON staff.account_id = staff_tar.reviewer_id
LEFT JOIN task_audit_log AS chief_tar ON task.id = chief_tar.task_id AND chief_tar.reviewer_role = "chief"
LEFT JOIN reviewer AS chief ON chief.account_id = chief_tar.reviewer_id
WHERE
team_code = ?`
queryParams := []interface{}{taskAuditLogIn.TeamCode}
3、避免阶梯缩进与代码紧凑
阶梯缩进、代码紧凑会导致代码不易阅读，理解更难，可以通过一些反向判断来拒绝一些操作，从而减少阶梯缩进，代码紧凑则可以把一些相关的逻辑放到一起，不同的处理步骤适当换行。
// Bad
// 校验参数
VerifyParams(requestIn)
// 获取信息
orderSlice := GetDBInfo(params)
// 逻辑处理
// ...
// 组织返参
for _, order := range(orderSlice){
...
}
// Good
// 校验参数
VerifyParams(requestIn)
// 获取信息
orderSlice := GetDBInfo(params)
// 逻辑处理
// ...
// 组织返参
for _, order := range(orderSlice){
...
}
同一步骤的逻辑太长可以封装成函数、方法。
// Bad
for _, v := range data {
if v.F1 == 1 {
v = process(v)
if err := v.Call(); err == nil {
v.Send()
} else {
return err
}
} else {
log.Printf("Invalid v: %v", v)
}
}
// Good
for _, v := range data {
if v.F1 != 1 {
log.Printf("Invalid v: %v", v)
continue
}
v = process(v)
if err := v.Call(); err != nil {
return err
}
v.Send()
}
不必要的else
// Bad
var a int
if b {
a = 100
} else {
a = 10
}
// Good
a := 10
if b {
a = 100
}
4、避免循环IO、上下文无关联的耗时动作采用Go协程
避免循环IO，可以用批量就改用批量。
func (itm InspectionTaskManager) BatchCreateInspectionTask(taskIdList []uint32) error {
inspectionTaskList := make([]models.InspectionTaskModel, 0)
// 组装好批量创建的抽查任务
for _, id := range taskIdList {
inspectionTaskList = append(inspectionTaskList, models.InspectionTaskModel{
TaskId: id,
})
}
// 批量创建
_, err := itm.BulkCreate(inspectionTaskList)
return err
}
有些数据库表结构可以使用自关联的方式简化查询从而避免循环IO、减少查询次数。
// GetTagMenu 获取所有task_group标签与其二级标签
func (tm *TagManager) GetTagMenu() []*TagMenuResult {
querySql := `
SELECT
t1.id, t1.tag_name, t1.tag_type,
t2.id as two_tag_id, t2.tag_name as two_tag_name,
t2.tag_type as two_tag_type,
t2.pid
FROM
tag AS t1
INNER JOIN tag AS t2 ON t2.pid = t1.id
WHERE
t1.tag_type = "task_group"`
tagMenuSlice := make([]*TagMenuResult, 0)
tm.Conn.Raw(querySql).Scan(&tagMenuSlice)
return tagMenuSlice
}
然后就是上下文无关联的可以并行执行，提高性能。
// GetPageWithTotal 获取分页并返回总数
func (bm BaseManager) GetPageWithTotal(condition *Condition) (*PageResult, error) {
errChan := make(chan error)
resultChan := make(chan PageResult)
defer close(errChan)
defer close(resultChan)
var pageResult PageResult
pageResult.Total = -1 // 设置默认值为-1, 用于判断没有获取到数据的时候
go func() {
// 获取总数
total, err := bm.GetCount(condition)
if err != nil {
errChan <- err
return
}
pageResult.Total = total
resultChan <- pageResult
}()
go func() {
// 获取分页数据
result, err := bm.GetPage(condition)
if err != nil {
errChan <- err
return
}
pageResult.ResultList = result
resultChan <- pageResult
}()
for {
select {
case err := <-errChan:
return nil, err
case result := <-resultChan:
if result.Total != -1 && result.ResultList != nil {
return &result, nil
}
case <-time.After(time.Second * 5):
return nil, exceptions.NewInterError(fmt.Sprintf("超时,分页查询失败"))
}
}
}
以上是借鉴网上一些处理方法和自己的一些想法与实践经验，可以互相探讨与学习，更多关于Go 代码规范错误处理的资料请关注易知道(ezd.cc)其它相关文章！
