Children Display

all	true
excerptType	simple

调试模式

为便于开发阶段调试，gdb支持调试模式，可以通过Debug配置文件配置项或者SetDebug配置方式开启调试模式，随后任何的数据库SQL操作语句都将会由内置的日志对象，以DEBUG级别输出到终端或者日志文件中。以下是一个开启了调试模式的配置示例：

Code Block

language	yml

database:
  default:
  - link:  "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    debug: true

输入的日志内容请详见下面章节介绍。

日志输出

日志输出往往是打印一些调试或者SQL语句，日志对象可以通过SetLogger方法来设置，也可以通过配置文件来做简单配置，日志的配置请查看ORM的 ORM使用配置章节。以下是一个开启了日志输出的配置示例：

Code Block

language	yml

database:
  logger:
  - path:   "/var/log/gf-app/sql"
    level:  "all"
    stdout: true
  default:
  - link:  "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    debug: true

ORM组件输出的日志相当详尽，我们来看一个示例：

Code Block

language	xml

2021-05-22 21:12:10.776 [DEBU] [  4 ms] [default] [1] BEGIN
2021-05-22 21:12:10.776 [DEBU] [  0 ms] [default] [1] SAVEPOINT `transaction0`
2021-05-22 21:12:10.789 [DEBU] [ 13 ms] [default] [1] SHOW FULL COLUMNS FROM `user`
2021-05-22 21:12:10.790 [DEBU] [  1 ms] [default] [1] INSERT INTO `user`(`id`,`name`) VALUES(1,'john') 
2021-05-22 21:12:10.791 [DEBU] [  1 ms] [default] [1] ROLLBACK TO SAVEPOINT `transaction0`
2021-05-22 21:12:10.791 [DEBU] [  0 ms] [default] [1] INSERT INTO `user`(`id`,`name`) VALUES(2,'smith') 
2021-05-22 21:12:10.792 [DEBU] [  1 ms] [default] [1] COMMIT

可以看到，日志包含以下几部分信息：

日期及时间，精确到毫秒。
日志级别。因为SQL日志主要用于功能调试/问题排查，生产环境往往需要关闭掉，因此日志级别固定为DEBUG级别。
当前SQL执行耗时。从客户端发起请求到接收到数据的时间，单位为毫秒。当执行时间不足1毫秒时，展示为0毫秒。
当前SQL所处的数据库配置分组，默认为default。关于配置分组的介绍具体请参考章节：ORM使用配置。
当前SQL所属的事务ID。如果当前SQL不属于事务操作时，不存在该字段。关于事务ID的介绍请参考章节：ORM事务处理。
具体执行的SQL语句。需要注意的是，由于底层使用的是SQL预处理，这里的SQL语句是通过组件自动拼接的结果，仅供参考。

空跑特性

ORM空跑可以通过DryRun配置项来启用，默认关闭。当ORM的空跑特性开启时，读取操作将会提交，而写入、更新、删除操作将会被忽略。该特性往往结合调试模式和日志输出一起使用，用于校验当前的程序（特别是脚本）执行的SQL是否符合预期。以下是一个开启了空跑特性的配置示例：

Code Block

language	yml

database:
  default:
  - link:   "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    debug:  true
    dryRun: true

空跑特性也可以通过命令行参数或者环境变量全局修改：

命令行启动参数 - gf.gdb.dryrun=true。
指定的环境变量 - GF_GDB_DRYRUN=true。

例如：

Code Block

language	bash

$ ./app --gf.gdb.dryrun=true

Code Block

language	bash

$ ./app --gf.gdb.dryrun true

字段映射

在对数据进行写入/更新时，使用Fields/Fields/Data方法时，如果给定的参数为map/struct类型，给定参数的键名/属性名称将会自动按照忽略大小写及特殊字符的方式与数据表的字段进行自动识别映射。例如：

Code Block

language	html

Map键名     字段名称     是否匹配
nickname   nickname      match
NICKNAME   nickname      match
Nick-Name  nickname      match
nick_name  nickname      match
nick name  nickname      match
NickName   nickname      match
Nick-name  nickname      match
nick_name  nickname      match
nick name  nickname      match

我们来看一个例子，我们实现一个查询用户基本信息的一个接口，这个用户是一个医生。

1、我们有两张表，一张user表，大概有30个字段；一张doctor_user表，大概有80多个字段。

2、user是用户基础表，包含用户的最基础信息；doctor_user是基于user表的业务扩展表，特定用户角色的表，与user表是一对一关系。

3、我们有一个GRPC的接口，接口定义是这样的（为方便演示，这里做了一些简化）：

1）GetDoctorInfoRes

Code Block

language	go

// 查询接口返回数据结构
type GetDoctorInfoRes struct {
	UserInfo             *UserInfo   `protobuf:"bytes,1,opt,name=UserInfo,proto3" json:"UserInfo,omitempty"`
	DoctorInfo           *DoctorInfo `protobuf:"bytes,2,opt,name=DoctorInfo,proto3" json:"DoctorInfo,omitempty"`
	XXX_NoUnkeyedLiteral struct{}    `json:"-"`
	XXX_unrecognized     []byte      `json:"-"`
	XXX_sizecache        int32       `json:"-"`
}

2）UserInfo

Code Block

language	go

// 用户基础信息
type UserInfo struct {
	Id                   uint32   `protobuf:"varint,1,opt,name=id,proto3" json:"id,omitempty"`
	Avatar               string   `protobuf:"bytes,2,opt,name=avatar,proto3" json:"avatar,omitempty"`
	Name                 string   `protobuf:"bytes,3,opt,name=name,proto3" json:"name,omitempty"`
	Sex                  int32    `protobuf:"varint,4,opt,name=sex,proto3" json:"sex,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

3）DoctorInfo

Code Block

language	go

// 医生信息
type DoctorInfo struct {
	Id                   uint32   `protobuf:"varint,1,opt,name=id,proto3" json:"id,omitempty"`
	Name                 string   `protobuf:"bytes,3,opt,name=name,proto3" json:"name,omitempty"`
	Hospital             string   `protobuf:"bytes,4,opt,name=hospital,proto3" json:"hospital,omitempty"`
	Section              string   `protobuf:"bytes,6,opt,name=section,proto3" json:"section,omitempty"`
	Title                string   `protobuf:"bytes,8,opt,name=title,proto3" json:"title,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

4、查询接口实现代码

Code Block

language	go

// 查询医生信息
func (s *Service) GetDoctorInfo(ctx context.Context, req *pb.GetDoctorInfoReq) (res *pb.GetDoctorInfoRes, err error) {
    // Protobuf返回数据结构
	res = &pb.GetDoctorInfoRes{}
	// 查询医生信息
    // SELECT `id`,`avatar`,`name`,`sex` FROM `user` WHERE `user_id`=xxx
	err = dao.PrimaryDoctorUser.
		Ctx(ctx).
		Fields(res.DoctorInfo).
		Where(dao.PrimaryDoctorUser.Columns.UserId, req.Id).
		Scan(&res.DoctorInfo)
	if err != nil {
		return
	}
	// 查询基础用户信息
    // SELECT `id`,`name`,`hospital`,`section`,`title` FROM `doctor_user` WHERE `id`=xxx
	err = dao.PrimaryUser.
		Ctx(ctx).
		Fields(res.DoctorInfo).
		Where(dao.PrimaryUser.Columns.Id, req.Id).
		Scan(&res.UserInfo)
	return res, err
}

当我们调用GetDoctorInfo执行查询时，将会向数据库发起两条SQL查询，例如：

Code Block

language	sql

SELECT `id`,`avatar`,`name`,`sex` FROM `user` WHERE `user_id`=1
SELECT `id`,`name`,`hospital`,`section`,`title` FROM `doctor_user` WHERE `id`=1

可以看到：

使用Fields方法时，参数类型为struct或者*struct，ORM将会自动将struct的属性名称与数据表的字段名称做自动映射匹配，当映射匹配成功时只会查询特定字段数据，而不存在的属性字段将会被自动过滤。
使用Scan方法时（也可以用Struct/Structs），参数类型为*struct或者**struct，查询结果将会自动与struct的属性做自动映射匹配，当映射匹配成功时会自动做转换赋值，否则不会对参数的属性做任何处理。

类型识别

使用gdb查询数据时，返回的数据类型将会被自动识别映射到Go变量类型。例如: 当字段类型为int(xx)时，查询到的字段值类型将会被识别会int类型；当字段类型为varchar(xxx)/char(xxx)/text等类型时将会被自动识别为string类型。以下以mysql类型为例，介绍数据库类型与Go变量类型的自动识别映射关系:

Tip
版本可能随时迭代更新，具体可查看源码 https://github.com/gogf/gf/v2/blob/master/database/gdb/gdb_core_structure.go

数据库类型Go变量类型*charstring*textstring*binarybytes*blobbytes*intint*moneyfloat64bitintbig_intint64floatfloat64doublefloat64decimalfloat64boolbooldatetime.Timedatetimetime.Timetimestamptime.Time其他string

这一特性对于需要将查询结果进行编码，并通过例如JSON方式直接返回给客户端来说将会非常友好。

类型转换

gdb的数据记录结果（Value）支持非常灵活的类型转换，并内置支持常用的数十种数据类型的转换。Result/Record的类型转换请查看后续 ORM高级特性章节。

Value类型是*gvar.Var类型的别名，因此可以使用gvar.Var数据类型的所有转换方法，具体请查看通用动态变量章节

使用示例：

首先，数据表定义如下：

Code Block

language	sql

# 商品表
CREATE TABLE `goods` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `title` varchar(300) NOT NULL COMMENT '商品名称',
  `price` decimal(10,2) NOT NULL COMMENT '商品价格',
  ...
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

其次，数据表中的数据如下：

Code Block

language	html

id   title     price
1    IPhoneX   5999.99

最后，示例代码如下：

Code Block

language	go

if r, err := db.Model("goods").FindOne(1); err == nil {
    fmt.Printf("goods    id: %d\n",   r["id"].Int())
    fmt.Printf("goods title: %s\n",   r["title"].String())
    fmt.Printf("goods proce: %.2f\n", r["price"].Float32())
} else {
    g.Log().Error(gctx.New(), err)
}

执行后，输出结果为：

Code Block

language	shell

goods    id: 1
goods title: IPhoneX
goods proce: 5999.99

内嵌结构支持

gdb模块针对于struct内嵌结构提供了良好的支持，包括参数传递、结果处理。例如：

Code Block

language	go

type Base struct {
    Uid        int         `orm:"uid"`
    CreateAt   *gtime.Time `orm:"create_at"`
    UpdateAt   *gtime.Time `orm:"update_at"`
    DeleteAt   *gtime.Time `orm:"delete_at"`
}
type User struct {
    Base
    Passport   string `orm:"passport"`
    Password   string `orm:"password"`
    Nickname   string `orm:"nickname"`
}

并且，无论多少层级的struct嵌套，gdb的参数传递和结果处理都支持。

自定义类型转换

当我们需要将查询的结果转换到自定义的类型中，无论是作为直接转换的类型还是作为struct的属性，都可以通过实现特定的接口来实现。详细介绍请参考类型转换-UnmarshalValue 章节。

Panel

title	Content Menu

toc

Space shortcuts

Page tree

Versions Compared

Old Version 23

New Version Current

Key

调试模式

日志输出

空跑特性

字段映射

类型识别

类型转换

内嵌结构支持

自定义类型转换

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 23

New Version Current

Key

调试模式

日志输出

空跑特性

字段映射

类型识别

类型转换

内嵌结构支持

自定义类型转换