---

前言

Gin是一个很常用的Go语言Web框架，总的来说它是一个轻量级的框架，上手比较简易。
然而，Gin的使用文档实在是有一些简陋，在实际的开发中很多时候不能根据文档得到需要的答案。
在文档的简陋性上，MongoDB的Go语言驱动实在是有过之而无不及，且由于其推出的时间相对较晚，所以教材资源相对不太充足，也不够细致。网上许多的教程都是基于mgo包的，该包作为第三方的资源，虽然与官方驱动在很多地方都很相似，但还是有许多不相同之处。
此前，笔者恰好在写关于Gin+MongoDB的相关内容，因此在这里做一些关于数据结构的总结。
笔者的gin与MondoDB驱动版本分别为1.7.1与1.8.1，其获取方法如下：

go get -u github.com/gin-gonic/gin
go get -u go.mongodb.org/mongo-driver

如果下载被卡，就换一个代理，网上文章已有教程，此处不多赘述。

声明

为什么要特别拿数据结构出来说？这是由于MongoDB的Go驱动封装非常底层，也就是说其使用要严格依赖于bson，所以想要用好这个工具，必须要知道相关数据结构的内容。同时，Gin是一个Web框架，这自然不能避免参数获取与转换等等问题。将两者结合起来就需要对数据结构的了解以及转换方式非常的清晰。
由于笔者对mongo的接触并不深入，本文不包含太多针对mongo的使用与设计，而只是对Gin与MongoDB驱动结合的一些经验与技巧进行分享。
由于笔者是第一次使用上述两者，如果不妥指出，望不吝指出，以助改正。

---

一、关于MongoDB驱动的数据结构问题

接触了mongo自然也无法离开bson的使用。在MongoDB中，常常能见到各种大括号以及嵌套的大括号，笼统来说那就是一种bson结构，如：

{"hello":"world"}

bson的相关内容在mongo-drive/bson与mongo-drive/bson/primitive中有所记录（后者定义了大量的关于MongoDB的数据类型）。下面笔者将分析较为重要的数据结构。

1. bson.M

简单来说，bson.M其实就是常说的“键值对”。查阅源码，可以得知其结构如下：

type M = primitive.M //bson.go
type M map[string]interface{}  //primitive.go

使用go的朋友们一定很熟悉，这就是常用的以字符串为键，任意类型为值的一个hash数组。在bson.go文件中，M被定义成了primitive中的M。这种结构与mongo使用的结构是一致的，假如我要查询某个"name"为"Jack"的人，那么我就可以构造一个filter：

filter := bson.M{"name":"Jack"}

笔者之所以首先提及这个，是因为该结构十分常用且直观，并容易理解。但显然，一种数据结构是不能适用在所有场合的。

2. bson.E

从go的数据结构去讲，bson.E实际上就是结构体。查阅源码，可以得知其结构如下：

type E = primitive.E //bson.go
type E struct { //primitive.go
	Key   string
	Value interface{}
}

看到这个数据结构，相信有读者一定在想“哎呀这不就是变相的键值对吗，为啥要搞得这么复杂”。然而，这个结构的设计确实是有它的作用的，详细的内容见下文。

3. bson.A

bson.A就是空接口组成的数组。查阅源码，可以得知其结构如下：

type A = primitive.A //bson.go
type A []interface{} //primitive.go

这种结构比较简单，但基本只是在特殊情况下有用处，相对其它的还是较少，故不多提。

4. bson.D

bson.D是bson.E的切片。查阅源码，可以得知其结构如下：

type D = primitive.D //bson.go
type D []E //primitive.go

D代表的是document，其实也就是指mongo中的一个文档的结构，而E则是element，即文档中一项的结构。

5.ObjectId

使用过mongo的朋友一定对这个不陌生，ObjectId是插入文档时mongo自生成的一个随机id，可以标识一个文档。这个数据结构自然也囊括在驱动中了，收入在primitive下，使用primitive.ObjectId即可找到（mgo是收入在bson下的，此处结构不同）。查阅源码，其结构如下：

type ObjectID [12]byte

在go中，该数据类型是一个12长度的字节数组。

二、关于Gin的数据结构问题

gin.Context（以下简称c）提供的各种参数绑定方法确实是非常好用的，也十分常用，但这仍然不可以避免一些遇到一些特殊的、不适合使用绑定的情况，如路径参数的问题。虽然路径参数一般不会很多，可以使用c.Param方法获取，但这样做其实无疑是降低了代码的可扩展性。因此，分析相关的数据结构也是很有必要的。

1.URL参数

遇到url参数，当然首选采用ShouldBind方法进行绑定。如果这个方法不能解决，那一般情况下也是采用c.Query或者c.DefaultQuery等来解决。但使用这两个方法的前提是使用者必须得知参数的名字，一旦出现参数名称有可能会变化又或者是参数内容过多的时候，这种方式就不好使了。
因此，在特殊情况下，c.Request.URL.Query()方法就是一个很好的东西。这个方法的返回值是url.Values，这是个什么东西呢？查阅源码可以得知它的结构：

type Values map[string][]string

显然，这个Values是一个以字符串为键，字符串数组为值的hash数组。也就是说，获取到的参数其实已经还原了json本身的结构。

2.表单参数

虽然这么说很啰嗦，表单参数其实还是首选ShouldBind，次选同样也是c.Form等通过参数名获取。而在特殊情况下，可以采用c.Request.Form获取或c.Request.PostForm获取参数。在使用这两者前，必须输入以下内容：

c.Request.ParseForm()

这个东西到底是干啥的呢？我们不妨看看源码的注释：

// ParseForm populates r.Form and r.PostForm.
//
// For all requests, ParseForm parses the raw query from the URL and updates
// r.Form.
//
// For POST, PUT, and PATCH requests, it also reads the request body, parses it
// as a form and puts the results into both r.PostForm and r.Form. Request body
// parameters take precedence over URL query string values in r.Form.

简单来说，调用该方法就是获取前端传输的参数的。而这些参数是包含了URL参数与表单参数，前者的值会被加入到c.Form里。换而言之，如果只是想获取表单参数，就使用PostForm，否则是Form。这两者的定义如下：

PostForm url.Values
Form url.Values

也就是说，两者的结构都是hash数组，与上一小节的一致。

3.路径参数

Gin的文档里会提到使用c.Param方法根据参数名获取，但细心的朋友们应该会发现，其实还存在一个叫做c.Params的东西。这又是个什么东西呢？其实，仔细翻阅一下文档，就会发现有描述了。在源码里，c.Params是这样的：

type Param struct {
	Key   string
	Value string
}
type Params []Param

也就是说，Param是一个键值对结构体，而Params就是Param的一个切片。

三、Gin与MongoDB驱动的结合

让大家看笔者吹了这么长一段，实在是抱歉。但以上内容都是为此处做铺垫的，所以不提不行。那么，接下来开始讲述两者数据结构的相互转换与使用。

1.bson.D与c.Params

相信大家已经注意到了，这两者在go里其实是使用着一样的数据结构的。那么，假如当前有一个路由r，它拥有路径参数，其结构如下：

r.GET("/:name/:pwd",func (c *gin.Context){})

而发送过来的数据是长这个样子的（此处使用json以便明确地表示结构，下同）：

{
"name":"Jack",
"pwd":"123456"
}

当请求发送到该路径下时，使用c.Params获取到的内容就会是这个样子的：

params := {{"name","Jack"},{"pwd","123456"}}

最外层的括号就是数组，而内层的括号则是结构体。这个参数同样也是bson.D，换言之这是可以直接丢到驱动里使用的。假如我现在想要插入某一条记录，那么，代码就可以是这个样子的：

collection.InsertOne(context.TODO(), params)

这样就可以灵活地使用路径参数进行数据库操作，而避免臃肿的代码了。当然，前面提到的bson这么多的结构中，bson.M也是能使用的，但这就需要将参数转换成map才能用了。如果读者不太喜欢bson.D的结构（例如我自己）又或者有强迫症的（也是我自己）不想看到，那就需要换成bson.M，也就是map，来处理。然而比较可惜的是，这两者之间没有可以直接转换的方法，笔者也只是采用循环的方式来构造。希望对此有了解的朋友能够留言以告知我。

2.bson.M与URL参数和表单参数

之所以这里把两种参数混在一起讲，是因为他们在数据结构上没有本质上的区别，都是map，而由于bson.M是一个值为空接口的map，所以在两者的结合中可以变相地认为两者在go中是一样的数据结构。
假如当前有路由r有这样的情况：

r.GET("/",func (c *gin.Context){})
r.POST("/",func (c *gin.Context){})

而传输的数据则继续使用上文的。由于json的本质其实也是键值对，所以传输过来后其实没有什么变化。假如现在还是想插入某一条数据，那么，代码可以是这个样子的：

collection.InsertOne(context.TODO(), params)

大家可以看到，其实这与上一小节bson.D的使用别无二致的，代码的书写就统一起来了，而且非常的简洁。
在这里笔者要多提一句，并不是说不能全部用bson.M做所有的内容，而是说要意识到Params这种结构体数组其实是不需要做额外的转换就可以使用的。

3.MongoDB与结构体

前面笔者也提到过，相信接触过gin的朋友们也知道，ShouldBind这个方法是非常好用的，可以直接将参数绑定到结构体里面，无须过多的操作。但看到笔者在上面讲了这么久都没有说到结构体的使用，是不是认为结构体不能够直接参与到MongoDB的使用里面来呢？
其实并不是这样的。这里要讲一下Go结构体的一些特别之处。结构体是C语言就已经存在的一个东西。本身这两门语言就有着一样的作者，内容也非常的相似（笔者是C的爱好者，所以对与Go也有着亲切感）。但在两门语言中，结构体是有不同之处的，其中最显著的，就是Go语言可以通过指定键来设置值。
下面我们来举个例子，假如有个叫做User的结构体，那么在C里面的定义是这个样子的：

typedef struct User{
	char name[128];
	char pwd[20];
}User;

在Go里面的定义是这个样子的：

type User struct{
	Name string
	Pwd string
}

虽然大家应该知道，但还是提一句，这里大小写的不同是因为C结构体的成员本身就是public的，但是Go是依靠首字母大小写来判断该成员是否公开的。还有一点，就是string和char数组并不等价，应当说byte数组和char数组才是等价的。但这里就不纠结这个问题了，因为并不影响说明。
在C里面，可以采用这样的赋值：

User user={"Jack","123456"}

相信大家很熟悉，就不多说了。在Go里，赋值是这个样子的：

user := User{"Jack","123456"}

在Go里，其实更常用的是这样的赋值方式：

user := User{Name:"Jack", Pwd:"123456"}

从这里开始，C与Go结构体的区别就体现出来了，因为，Go还可以这样写：

user := User{Name:"Jack"}
//或者是
user := User{Pwd:"123456"}

这样做的结果就是只有一个成员被赋值了，而C是不能够支持这样的功能的。（虽然gnu的编译器可以支持.成员名=XXX这样的方式赋值，但这不应该被提及到正常的标准中）
为什么要特意提这个问题？大家有没有留意到，这种结构体的赋值方式，其实与写键值对是无异的。
那么，让我们再来留意一下InsertOne方法的第二个参数，其参数名为document，类型是interface{}。也就是说事实上这个参数是可以接受任意类型的。当然，这是理论上的情况，如果出现了不支持的类型其实就会panic了。
那么我们再次回到开始的话题——结构体是不是不能够在MongoDB的驱动中派上用场？答案自然是“不”。虽然说驱动的一系列方法给出的参数都没有提及允许使用结构体，但其实结构体也是可以充当bson的。也就是说，在使用参数绑定获取参数的时候，结构体其实是可以直接当做document丢到相关的方法里面去的。
此处以上一小节的GET为例，如果采用参数绑定，那么代码应当是这样的：

user := new(User)
c.ShouldBind(user)
collection.InsertOne(context.TODO(), user)

当然如果有的朋友想要把结构体搞成bson再处理也不是不行的。bson提供了Marshal与UnMarshal两个方法，前者可以将结构体改成bson编码文档，后者就将文档改成了bson.M。网上已有其它关于这点的赘述，此处不再重复。

4.bson.A与数组参数

bson.A这个结构看上去就比较的鸡肋，总感觉这种空接口的切片好像没啥可以用到的地方。如果前端传入的参数是数组，事实上那也是非常少数的情况，开发者完全是可以特殊处理，使用参数名与c.FormArray或者c.QueryArray这样的方法来获取。那么，下面笔者就来举一个例子。
假如前端需要传来的参数是这个样子的：

{
"ids":[1,2,3]
}

在go中，开发者写了一个结构体用来获取，是这个样子的：

type ID struct {
	Ids []int `json:"ids" form:"ids" bson:"ids"`
}

使用常规的ShouldBind方法自然是可以把数据给绑定进去的，但如果有特殊情况——没有传这个参数呢?对于结构体来说，其实就是Ids成为了一个空的切片。将这个结构体的内容写入数据库的时候，ids一项对应的值就会变成null。
总的来说这其实是一个不太美观的情况，所以遇到这种情况可以采用tag加入omitempty的方法，即：

type ID struct {
	Ids []int `json:"ids,omitempty" form:"ids,omitempty" bson:"ids"`
}

这样如果该项是空，那么就不会有键被加入到数据库里。
那么，如果我有特殊要求，数据库里面要写入一个空的数组呢？这时候，bson.A的用处就出现了。如果没有获取到参数，那么写入的内容就设置为bson.A，就可以完成填入空数组的功能了。

5.关于ObjectId的一些事

ObjectId是一个比较神奇的数据结构，它没有蕴含有隐式转换（指的是string到ObjectId）。前端交付过来的id是字符串形式的，如果用于参数绑定的结构体中id一项是string，那可以正常获取，但如果是ObjectId类型，就会变成一个全0的字节数组。同样的，如果结构体里面id是ObjectId，前端传入的id就无法被绑定到结构体上。
但从MongoDB中获取内容并绑定到结构体里的时候，这一点却不成问题了。这是由于本身字节数组（假设叫做b）就可以通过string(b)直接转换到string，所以ObjectId类型就被直接装载到了string之中。
这实在是一个难办的地方。primitive提供了方法叫做ObjectIdFromHex，这个方法的参数是一个字符串，返回值是一个ObjectId以及error，如果转换失败（失败的理由可能是长度不对、结构不同等）error就会有内容。这个错误在开发中是一定要处理的，因为如果不处理ObjectId就会成为全0值。
这种特殊的情况意味着这个属性是无法在参数绑定中很好的使用。因此，如果出现要通过ObjectId来查数据的时候，前端传入的id只能够通过上述方法转换了。即：

id,_ := primitive.ObjectIdFromHex(c.Query("id")) //这里没有写错误处理，不要学我
filter := bson.M{"_id":id}

但这样的代码实在是不美观。

此外，还有一种特别的情况，则是采用参数绑定时出现的问题。如果开发者有意将ObjectId作为主键，希望其能够随机生成的，就要注意了。这个时候，前端传来的数据一般是没有id的。
假如，用于绑定的结构体是长这个样子的：

type User struct {
	Id string `json:"id" form:"id" bson:"id"`
	XXXXX
	XXXXX
}

这里可能有人会好奇既然不传入id，为什么结构体还要有。这是因为User不仅仅是用于前端参数传入和绑定的，从数据库读取数据并返回的时候，也是需要用到这个结构体的。所以这个属性在某些情况下是不可或缺的。
那么，言归正传，如果前端没有传入id，那么答案就显而易见了——一个空字符串会被写入数据库里。这显然是不被希望的。因此，要避免这个问题，就要在tag里写上omitempty。

总结

本文主要是基于Gin与MongoDB的数据结构做出了一些分析。内容较浅，还没有过多地涉及到使用的部分。
其实，在两者结合的使用上，笔者踩了许多的坑。如果有机会，日后再和大家分享一些相关的经验。希望笔者的文章能够抛砖引玉，通过数据结构的分析给予相关的开发者一些使用的思路。