Golang简化MongoDB数据库操作的插件库qmgo的使用

Qmgo简介

Qmgo是一个Go语言的MongoDB驱动库，基于MongoDB官方驱动开发，但提供了更简单易用的API（如链式调用）。

• Qmgo允许用户以更优雅的方式使用MongoDB的新功能
• Qmgo是从mgo迁移到新MongoDB驱动的首选方案，只需最小代码改动

要求

• Go 1.10及以上版本
• MongoDB 2.6及以上版本

特性

• 文档的CRUD操作，支持所有官方选项
• 排序、限制、计数、选择、去重
• 事务支持
• 钩子函数
• 自动默认和自定义字段
• 预定义操作符
• 聚合、索引操作、游标
• 验证标签
• 插件系统

安装

使用go mod自动安装依赖：

import "github.com/qiniu/qmgo"

或使用go get：

go get github.com/qiniu/qmgo

使用示例

1. 初始化连接

import (
    "context"
    "github.com/qiniu/qmgo"
)

ctx := context.Background()
// 方式1：创建客户端
client, err := qmgo.NewClient(ctx, &qmgo.Config{Uri: "mongodb://localhost:27017"})
db := client.Database("class")
coll := db.Collection("user")

// 方式2：直接连接到指定数据库和集合（推荐）
cli, err := qmgo.Open(ctx, &qmgo.Config{
    Uri: "mongodb://localhost:27017", 
    Database: "class", 
    Coll: "user",
})

// 确保关闭连接
defer func() {
    if err = cli.Close(ctx); err != nil {
        panic(err)
    }
}()

2. 定义数据结构

type UserInfo struct {
    Name   string `bson:"name"`
    Age    uint16 `bson:"age"`
    Weight uint32 `bson:"weight"`
}

var userInfo = UserInfo{
    Name: "xm",
    Age: 7,
    Weight: 40,
}

3. 创建索引

// 创建单个索引
cli.CreateOneIndex(context.Background(), options.IndexModel{Key: []string{"name"}})

// 创建多个索引
cli.CreateIndexes(context.Background(), []options.IndexModel{{Key: []string{"id2", "id3"}}})

4. 插入文档

// 插入单个文档
result, err := cli.InsertOne(ctx, userInfo)

// 插入多个文档
var userInfos = []UserInfo{
    {Name: "a1", Age: 6, Weight: 20},
    {Name: "b2", Age: 6, Weight: 25},
    {Name: "c3", Age: 6, Weight: 30},
    {Name: "d4", Age: 6, Weight: 35},
    {Name: "a1", Age: 7, Weight: 40},
    {Name: "a1", Age: 8, Weight: 45},
}
result, err = cli.InsertMany(ctx, userInfos)

5. 查询文档

// 查询单个文档
one := UserInfo{}
err = cli.Find(ctx, bson.M{"name": userInfo.Name}).One(&one)

// 查询所有文档，排序和限制
batch := []UserInfo{}
cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch)

// 计数
count, err := cli.Find(ctx, bson.M{"age": 6}).Count()

6. 更新文档

// 更新单个文档
err := cli.UpdateOne(ctx, bson.M{"name": "d4"}, bson.M{"$set": bson.M{"age": 7}})

// 更新多个文档
result, err := cli.UpdateAll(ctx, bson.M{"age": 6}, bson.M{"$set": bson.M{"age": 10}})

7. 删除文档

err = cli.Remove(ctx, bson.M{"age": 7})

8. 选择字段

err := cli.Find(ctx, bson.M{"age": 10}).Select(bson.M{"age": 1}).One(&one)

9. 聚合操作

matchStage := bson.D{{"$match", []bson.E{{"weight", bson.D{{"$gt", 30}}}}}
groupStage := bson.D{{"$group", bson.D{{"_id", "$name"}, {"total", bson.D{{"$sum", "$age"}}}}}
var showsWithInfo []bson.M
err = cli.Aggregate(context.Background(), Pipeline{matchStage, groupStage}).All(&showsWithInfo)

10. 事务支持

callback := func(sessCtx context.Context) (interface{}, error) {
    // 重要：确保在整个事务中使用sessCtx
    if _, err := cli.InsertOne(sessCtx, bson.D{{"abc", int32(1)}}); err != nil {
        return nil, err
    }
    if _, err := cli.InsertOne(sessCtx, bson.D{{"xyz", int32(999)}}); err != nil {
        return nil, err
    }
    return nil, nil
}
result, err = cli.DoTransaction(ctx, callback)

11. 钩子函数

type User struct {
    Name string `bson:"name"`
    Age  int    `bson:"age"`
}

func (u *User) BeforeInsert(ctx context.Context) error {
    fmt.Println("before insert called")
    return nil
}

func (u *User) AfterInsert(ctx context.Context) error {
    fmt.Println("after insert called")
    return nil
}

u := &User{Name: "Alice", Age: 7}
_, err := cli.InsertOne(context.Background(), u)

12. 自动字段

// 默认字段
type User struct {
    field.DefaultField `bson:",inline"`
    Name string `bson:"name"`
    Age  int    `bson:"age"`
}

u := &User{Name: "Lucas", Age: 7}
_, err := cli.InsertOne(context.Background(), u)
// 自动生成createAt、updateAt和_id字段

// 自定义字段
type User struct {
    Name         string    `bson:"name"`
    Age          int       `bson:"age"`
    MyId         string    `bson:"myId"`
    CreateTimeAt time.Time `bson:"createTimeAt"`
    UpdateTimeAt int64     `bson:"updateTimeAt"`
}

func (u *User) CustomFields() field.CustomFieldsBuilder {
    return field.NewCustom().SetCreateAt("CreateTimeAt").SetUpdateAt("UpdateTimeAt").SetId("MyId")
}

u := &User{Name: "Lucas", Age: 7}
_, err := cli.InsertOne(context.Background(), u)
// 自动生成CreateTimeAt、UpdateTimeAt和MyId字段

13. 验证标签

type User struct {
    FirstName string            `bson:"fname"`
    LastName  string            `bson:"lname"`
    Age       uint8             `bson:"age" validate:"gte=0,lte=130"`    // 年龄必须在[0,130]之间
    Email     string            `bson:"e-mail" validate:"required,email"` // 邮箱不能为空且必须是邮箱格式
    CreateAt  time.Time         `bson:"createAt" validate:"lte"`          // 创建时间必须小于等于当前时间
    Relations map[string]string `bson:"relations" validate:"max=2"`       // 关系不能超过2个元素
}

14. 插件系统

func Do(ctx context.Context, doc interface{}, opType operator.OpType, opts ...interface{}) error{
  // 执行任何操作
}

// 注册插件
middleware.Register(Do)

Qmgo与其他驱动的比较

Qmgo vs go.mongodb.org/mongo-driver

Qmgo提供了更简洁的链式调用API，例如：

// qmgo方式
batch := []UserInfo{}
cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch)

// mongo-driver方式
findOptions := options.Find()
findOptions.SetLimit(7)
var sorts D
sorts = append(sorts, E{Key: "weight", Value: 1})
findOptions.SetSort(sorts)

batch := []UserInfo{}
cur, err := coll.Find(ctx, bson.M{"age": 6}, findOptions)
cur.All(ctx, &batch)

Qmgo vs mgo

Qmgo与mgo的API风格相似，但基于新的MongoDB驱动开发，支持更多新特性。

贡献

Qmgo项目欢迎所有贡献者，我们感谢您的帮助！

交流

• 加入qmgo讨论