go-zero框架基本配置和错误码封装

接上一篇：《go-zero框架快速入门》

加载配置信息

配置 env

在项目根目录下新增 .env 文件，可以配置当前读取哪个环境的配置信息。内容如下：

# 基础环境配置
#开发环境 dev
#测试环境 test
#预发环境 pre
#生产环境 prod
GO_ENV=dev

新增gozero/etc/gozero-api-dev.yaml文件，配置数据库等相关信息：

Name: gozero-api
Host: 0.0.0.0
Port: 8888
MaxConns: 50
Timeout: 20000
Mysql:
  DataSource: root:123456@tcp(127.0.0.01:3306)/go-demo-2025?charset=utf8mb4&parseTime=True&loc=Local
cache_config: &cache_config
  Host: 127.0.0.1:6379
  Pass: ""
  Type: node
Cache:
  - <<: *cache_config

同时可以新增如下配置文件，具体要在当前项目中运行哪个配置文件，修改.env为对应的环境变量即可。

gozero/etc/gozero-api-test.yaml
gozero/etc/gozero-api-pre.yaml
gozero/etc/gozero-api-prod.yaml

加载.env文件

上面只是配置了不同的env，还需要有一个方法来加载当前设定的env。代码路径：gozero/internal/config/config.go

func GetConfigFile() string {
	// 加载 .env 文件
	if err := godotenv.Load(); err != nil {
		logx.Errorf("Error loading .env file: %v", err)
	}
	env := os.Getenv("GO_ENV")
	logx.Infof("env=: %s", env)
	if env == "" {
		env = "dev" // 默认开发环境
	}
	return filepath.Join("etc", fmt.Sprintf("gozero-api-%s.yaml", env))
}

同时，把数据库相关的信息加载到Config中：

type Config struct {
	rest.RestConf
	Mysql struct {
		DataSource string
	}
	Cache cache.CacheConf
}

最后，在入口文件 gozero.go中加载配置项：

func main() {
    flag.Parse()
    var c config.Config
  	//调用自定义的GetConfigFile方法，读取当前配置的env信息
    configFile := config.GetConfigFile()
    conf.MustLoad(configFile, &c)

    //....
}

配置servicecontext

在 Go-zero 中，servicecontext是服务上下文的依赖注入，所有的配置项和数据库连接、以及业务逻辑所需的模型实例，都被集中管理在 servicecontext 中。可以把它理解为一根长长的线，这根线上存储了整个项目所需的各类资源。如此一来，每个层只需依赖这个上下文，而不需要直接处理底层的配置和初始化逻辑。

这里，我们先简单的配置全局Config和数据库model以及日志等上下文信息。代码路径：gozero/internal/svc/servicecontext.go

type ServiceContext struct {
	Config config.Config
	Model  *query.Query
}

func NewServiceContext(c config.Config) *ServiceContext {
	newLogger := logger.New(
		log.New(os.Stdout, "\r\n", log.LstdFlags), // io writer
		logger.Config{
			SlowThreshold: 10 * time.Second, // 慢SQL阈值,默认10秒钟
			LogLevel:      logger.Silent,    // 日志级别 Silent：静默级别,Error：错误级别,Warn：警告级别,Info：信息级别
			Colorful:      true,             // 是否彩色打印
		},
	)
	db, _ := gorm.Open(mysql.Open(c.Mysql.DataSource), &gorm.Config{
		Logger: newLogger,
		NamingStrategy: schema.NamingStrategy{
			TablePrefix: "", // 表名前缀
      SingularTable: true, // 使用单数表名，启用该选项，会区分 user 和 users 表为两个不同的数据表
		},
	})
	return &ServiceContext{
		Config: c,
		Model:  query.Use(db),
	}
}

查询数据

生成model文件

GEN 自动生成 GORM 模型结构体文件及使用示例，新增gozero/script/gorm_generate_db_struct.go 文件：

package main

import (
	"github.com/zeromicro/go-zero/core/conf"
	"go-demo-2025/gozero/internal/config"
	"gorm.io/driver/mysql"
	"gorm.io/gorm"
	"gorm.io/gorm/schema"
	"strings"

	"gorm.io/gen"
)

// GEN 自动生成 GORM 模型结构体文件及使用示例
// 安装: go get -u gorm.io/gen@v0.3.16
// 更多参考: https://gorm.io/zh_CN/gen | https://gorm.io/gen/database_to_structs.html
// 更多参考: https://segmentfault.com/a/1190000042502370
func main() {
	// 初始化go-zero的配置
	var c config.Config
	configFile := config.GetConfigFile() //调用自定义的GetConfigFile方法，读取当前配置的env信息
	conf.MustLoad(configFile, &c)

	// 连接数据库
	db, _ := gorm.Open(mysql.Open(c.Mysql.DataSource), &gorm.Config{
		NamingStrategy: schema.NamingStrategy{
			TablePrefix:   "",   // 表名前缀
			SingularTable: true, // 使用单数表名，启用该选项，会区分 user 和 users 表为两个不同的数据表
		},
	})

	// 生成实例
	g := gen.NewGenerator(gen.Config{
		// 生成的model文件的路径
		OutPath: "./internal/model/dao/query",

		// WithDefaultQuery 生成默认查询结构体(作为全局变量使用), 即`Q`结构体和其字段(各表模型)
		// WithoutContext 生成没有context调用限制的代码供查询
		// WithQueryInterface 生成interface形式的查询代码(可导出), 如`Where()`方法返回的就是一个可导出的接口类型
		Mode: gen.WithDefaultQuery | gen.WithQueryInterface,

		// 表字段可为 null 值时, 对应结体字段使用指针类型
		//FieldNullable: true, // generate pointer when field is nullable

		// 表字段默认值与模型结构体字段零值不一致的字段, 在插入数据时需要赋值该字段值为零值的, 结构体字段须是指针类型才能成功, 即`FieldCoverable:true`配置下生成的结构体字段.
		// 因为在插入时遇到字段为零值的会被GORM赋予默认值. 如字段`age`表默认值为10, 即使你显式设置为0最后也会被GORM设为10提交.
		// 如果该字段没有上面提到的插入时赋零值的特殊需要, 则字段为非指针类型使用起来会比较方便.
		FieldCoverable: false, // generate pointer when field has default value, to fix problem zero value cannot be assign: https://gorm.io/docs/create.html#Default-Values

		// 模型结构体字段的数字类型的符号表示是否与表字段的一致, `false`指示都用有符号类型
		FieldSignable: false, // detect integer field's unsigned type, adjust generated data type
		// 生成 gorm 标签的字段索引属性
		FieldWithIndexTag: false, // generate with gorm index tag
		// 生成 gorm 标签的字段类型属性
		FieldWithTypeTag: true, // generate with gorm column type tag
	})
	// 设置目标 db
	g.UseDB(db)

	// 自定义字段的数据类型
	// 统一数字类型为int64,兼容protobuf
	dataMap := map[string]func(columnType gorm.ColumnType) (dataType string){
		"tinyint":   func(columnType gorm.ColumnType) (dataType string) { return "int64" },
		"smallint":  func(columnType gorm.ColumnType) (dataType string) { return "int64" },
		"mediumint": func(columnType gorm.ColumnType) (dataType string) { return "int64" },
		"bigint":    func(columnType gorm.ColumnType) (dataType string) { return "int64" },
		"int":       func(columnType gorm.ColumnType) (dataType string) { return "int64" },
	}
	// 要先于`ApplyBasic`执行
	g.WithDataTypeMap(dataMap)

  //=================== 生成全部数据表的model ===================//
	// 自定义模型结体字段的标签
	// 将特定字段名的 json 标签加上`string`属性,即 MarshalJSON 时该字段由数字类型转成字符串类型
	jsonField := gen.FieldJSONTagWithNS(func(columnName string) (tagContent string) {
		//toStringField := `balance, `
		toStringField := ``
		if strings.Contains(toStringField, columnName) {
			return columnName + ",string"
		}
		return columnName
	})
	// 将非默认字段名的字段定义为自动时间戳和软删除字段;
	// 自动时间戳默认字段名为:`updated_at`、`created_at, 表字段数据类型为: INT 或 DATETIME
	// 软删除默认字段名为:`deleted_at`, 表字段数据类型为: DATETIME
	//autoUpdateTimeField := gen.FieldGORMTag("update_time", "column:update_time;type:int unsigned;autoUpdateTime")
	//autoCreateTimeField := gen.FieldGORMTag("create_time", "column:create_time;type:int unsigned;autoCreateTime")
	// 模型自定义选项组
	//fieldOpts := []gen.ModelOpt{jsonField, autoCreateTimeField, autoUpdateTimeField}
	fieldOpts := []gen.ModelOpt{jsonField}

	// 创建模型的结构体,生成文件在 model 目录; 先创建的结果会被后面创建的覆盖
	// 创建全部模型文件, 并覆盖前面创建的同名模型
	allModel := g.GenerateAllTable(fieldOpts...)

	// 创建模型的方法,生成文件在 query 目录; 先创建结果不会被后创建的覆盖
	g.ApplyBasic(allModel...)

  //=================== 生成指定数据表的model ===================//
	//有时候其他小伙伴改动了某个表，不能随着当前版本上线，就需要指定部分数据表
	/*
		g.ApplyBasic(
			g.GenerateModel("ms_base_user"),
			g.GenerateModel("ms_user_depart"),
			g.GenerateModel("ms_sys_dict"),
		)
	*/
  
	g.Execute()
}

然后运行次文件：go run gorm_generate_db_struct.go ，会在 ./internal/model/dao 目录下生成如下的model文件：

执行查询操作

在 gozero/internal/logic/admin/userdetaillogic.go 文件中编写查询model层数据的代码：

func (l *UserDetailLogic) UserDetail(req *types.UserDetailRequest) (resp *types.UserDetailResponse, err error) {
	//根据ID查询用户表信息,返回用户详情信息
	userModel := l.svcCtx.Model.User
	user, err := userModel.WithContext(l.ctx).Debug().Where(userModel.ID.Eq(int64(req.Id))).First()
	if err != nil {
		logx.Error("根据ID查询用户表信息失败:" + err.Error())
		return nil, err
	}
	//成功返回
	return &types.UserDetailResponse{
		Code: 200,
		Msg:  "获取用户详情成功",
		Data: types.UserDetailData{
			Id:   int32(user.ID),
			Name: user.Name,
		},
	}, nil
}

然后，在postman中使用POST请求调用一下看看：

错误码封装

配置拦截器

上面我们通过直接在logic层写死了返回码:200 和 message:获取用户详情成功，如果出现异常，则不会返回json结构：

下一步，来配置一下go-zero中的拦截器(SetErrorHandler)。

在入口文件 gozero.go 中，添加如下代码：

// 使用拦截器
httpx.SetErrorHandler(func(err error) (int, any) {
  switch e := err.(type) {
  case *utils.MyError:
    return http.StatusOK, utils.Fail(e)
  default:
    return http.StatusOK, utils.ErrorResponse(constants.CodeServerError.Code, err.Error())
  }
})

另外新增gozero/internal/utils/response.go 文件：

package utils

// 自定义错误结构体
type MyError struct {
	Code    int64  `json:"code"`
	Message string `json:"message"`
}

// 实现 Error() 方法
func (e *MyError) Error() string {
	return e.Message
}

// 创建自定义错误
func NewMyError(code int64, msg string) *MyError {
	return &MyError{
		Code:    code,
		Message: msg,
	}
}

type Response struct {
	Code    int64       `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"result"`
}

func SuccessResponse(data interface{}) *Response {
	return &Response{
		Code:    200000,
		Message: "请求成功",
		Data:    data,
	}
}
func ErrorResponse(code int64, msg string) *Response {
	return &Response{
		Code:    code,
		Message: msg,
		Data:    nil,
	}
}

func Fail(err *MyError) *Response {
	return &Response{
		Code:    err.Code,
		Message: err.Message,
		Data:    nil,
	}
}

再次运行：

错误码封装

接下来封装一个统一的错误码配置信息。新增gozero/internal/constants/errorCode.go:

package constants

var (
	//系统基本错误码
	CodeSuccess     = utils.NewMyError(200000, "请求成功")
	CodeServerError = utils.NewMyError(500000, "服务器异常")
	CodeParamsEmpty = utils.NewMyError(400000, "参数为空")
	CodeParamsError = utils.NewMyError(400001, "参数错误")
	CodeUnknown     = utils.NewMyError(400100, "未知错误")
)

在gozero/internal/logic/admin/userdetaillogic.go中添加一个自定义的判断条件：

func (l *UserDetailLogic) UserDetail(req *types.UserDetailRequest) (resp *types.UserDetailResponse, err error) {
	//校验参数,假设这里要求Id必须大于0
	if req.Id <= 0 {
		return nil, constants.CodeParamsError
	}
}

再次运行：

注意：上面定义的MyError 结构体一定要实现 Error()方法，否则，就不能算是一个error类型！

接下来，我们把成功返回部分也优化一下，把原有的logic的成功返回部分改为统一封装的*Response类型。

修改：gozero/internal/logic/admin/userdetaillogic.go

func (l *UserDetailLogic) UserDetail(req *types.UserDetailRequest) (resp *utils.Response, err error) {
	//前置判断条件和查询数据...

	//成功返回
	return utils.SuccessResponse(types.UserDetailData{
		Id:   int32(user.ID),
		Name: user.Name,
	}), nil
}

源代码：https://gitee.com/rxbook/go-demo-2025