# Qmgo `Qmgo` 是一款`Go`语言的`MongoDB` `driver`，它基于[MongoDB 官方 driver](https://github.com/mongodb/mongo-go-driver) 开发实现，同时使用更易用的接口设计，比如参考[mgo](https://github.com/go-mgo/mgo) （比如`mgo`的链式调用）。 - `Qmgo`让您以更优雅的姿势使用`MongoDB`的新特性。 - `Qmgo`是从`mgo`迁移到新`MongoDB driver`的第一选择，对代码的改动影响最小。 ## 要求 - `Go 1.10` 及以上。 - `MongoDB 2.6` 及以上。 ## 功能 - 文档的增删改查, 均支持官方driver支持的所有options - `Sort`、`limit`、`count`、`select`、`distinct` - 事务 - `Hooks` - 自动化更新的默认和定制fields - 预定义操作符 - 聚合`Aggregate`、索引操作、`cursor` - `validation tags` 基于tag的字段验证 - 可自定义插件化编程 ## 安装 推荐方式是使用`go mod`，通过在源码中`import github.com/qiniu/qmgo` 来自动安装依赖。 当然，通过下面方式同样可行： ``` go get github.com/qiniu/qmgo ``` ## Usage - 开始 `import`并新建连接 ```go import( "context" "github.com/qiniu/qmgo" ) ctx := context.Background() client, err := qmgo.NewClient(ctx, &qmgo.Config{Uri: "mongodb://localhost:27017"}) db := client.Database("class") coll := db.Collection("user") ``` 如果你的连接是指向固定的 database 和 collection，我们推荐使用下面的更方便的方法初始化连接，后续操作都基于`cli`而不用再关心 database 和 collection ```go cli, err := qmgo.Open(ctx, &qmgo.Config{Uri: "mongodb://localhost:27017", Database: "class", Coll: "user"}) ``` **_后面都会基于`cli`来举例，如果你使用第一种传统的方式进行初始化，根据上下文，将`cli`替换成`client`、`db` 或 `coll`即可_** 在初始化成功后，请`defer`来关闭连接 ```go defer func() { if err = cli.Close(ctx); err != nil { panic(err) } }() ``` - 创建索引 做操作前，我们先初始化一些数据： ```go type UserInfo struct { Name string `bson:"name"` Age uint16 `bson:"age"` Weight uint32 `bson:"weight"` } var userInfo = UserInfo{ Name: "xm", Age: 7, Weight: 40, } ``` 创建索引 ```go cli.CreateOneIndex(context.Background(), options.IndexModel{Key: []string{"name"}}) cli.CreateIndexes(context.Background(), []options.IndexModel{{Key: []string{"id2", "id3"}}}) ``` - 插入一个文档 ```go // insert one document result, err := cli.InsertOne(ctx, userInfo) ``` - 查找一个文档 ```go // find one document one := UserInfo{} err = cli.Find(ctx, bson.M{"name": userInfo.Name}).One(&one) ``` - 删除文档 ```go err = cli.Remove(ctx, bson.M{"age": 7}) ``` - 插入多条数据 ```go // multiple insert var userInfos = []UserInfo{ UserInfo{Name: "a1", Age: 6, Weight: 20}, UserInfo{Name: "b2", Age: 6, Weight: 25}, UserInfo{Name: "c3", Age: 6, Weight: 30}, UserInfo{Name: "d4", Age: 6, Weight: 35}, UserInfo{Name: "a1", Age: 7, Weight: 40}, UserInfo{Name: "a1", Age: 8, Weight: 45}, } result, err = cli.Collection.InsertMany(ctx, userInfos) ``` - 批量查找、`Sort`和`Limit` ```go // find all 、sort and limit batch := []UserInfo{} cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch) ``` - Count ```go count, err := cli.Find(ctx, bson.M{"age": 6}).Count() ``` - Update ```go // UpdateOne one err := cli.UpdateOne(ctx, bson.M{"name": "d4"}, bson.M{"$set": bson.M{"age": 7}}) // UpdateAll result, err := cli.UpdateAll(ctx, bson.M{"age": 6}, bson.M{"$set": bson.M{"age": 10}}) ``` - Select ```go err := cli.Find(ctx, bson.M{"age": 10}).Select(bson.M{"age": 1}).One(&one) ``` - Aggregate ```go 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) ``` - 建立连接时支持所有 mongoDB 的`Options` ```go poolMonitor := &event.PoolMonitor{ Event: func(evt *event.PoolEvent) { switch evt.Type { case event.GetSucceeded: fmt.Println("GetSucceeded") case event.ConnectionReturned: fmt.Println("ConnectionReturned") } }, } opt := options.Client().SetPoolMonitor(poolMonitor) // more options use the chain options. cli, err := Open(ctx, &Config{Uri: URI, Database: DATABASE, Coll: COLL}, opt) ``` - 事务 有史以来最简单和强大的事务, 同时还有超时和重试等功能: ```go 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) ``` [关于事务的更多内容](https://github.com/qiniu/qmgo/wiki/Transactions) - 预定义操作符 ```go // aggregate matchStage := bson.D{{operator.Match, []bson.E{{"weight", bson.D{{operator.Gt, 30}}}}}} groupStage := bson.D{{operator.Group, bson.D{{"_id", "$name"}, {"total", bson.D{{operator.Sum, "$age"}}}}}} var showsWithInfo []bson.M err = cli.Aggregate(context.Background(), Pipeline{matchStage, groupStage}).All(&showsWithInfo) ``` - Hooks Qmgo 灵活的 hooks: ```go 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) ``` [Hooks 详情介绍]() - 自动化更新fields Qmgo支持2种方式来自动化更新特定的字段 - 默认 fields 在文档结构体里注入 `field.DefaultField`, `Qmgo` 会自动在更新和插入操作时更新 `createAt`、`updateAt` and `_id` field的值. ````go 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) // tag为createAt、updateAt 和 _id 的字段会自动更新插入 ```` - Custom fields 可以自定义field名, `Qmgo` 会自动在更新和插入操作时更新他们. ```go type User struct { Name string `bson:"name"` Age int `bson:"age"` MyId string `bson:"myId"` CreateTimeAt time.Time `bson:"createTimeAt"` UpdateTimeAt int64 `bson:"updateTimeAt"` } // 指定自定义field的field名 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 and MyId 会自动更新并插入DB // 假设Id和ui已经初始化 err = cli.ReplaceOne(context.Background(), bson.M{"_id": Id}, &ui) // UpdateTimeAt 会被自动更新 ``` [例子介绍](https://github.com/qiniu/qmgo/blob/master/field_test.go) [自动化 fields 详情介绍](https://github.com/qiniu/qmgo/wiki/Automatically-update-fields) - `Validation tags` 基于tag的字段验证 功能基于[go-playground/validator](https://github.com/go-playground/validator)实现。 所以`Qmgo`支持所有[go-playground/validator 的struct验证规则](https://github.com/go-playground/validator#usage-and-documentation)，比如： ```go type User struct { FirstName string `bson:"fname"` LastName string `bson:"lname"` Age uint8 `bson:"age" validate:"gte=0,lte=130" ` // Age must in [0,130] Email string `bson:"e-mail" validate:"required,email"` // Email can't be empty string, and must has email format CreateAt time.Time `bson:"createAt" validate:"lte"` // CreateAt must lte than current time Relations map[string]string `bson:"relations" validate:"max=2"` // Relations can't has more than 2 elements } ``` 本功能只对以下API有效： ` InsertOne、InsertyMany、Upsert、UpsertId、ReplaceOne ` - 插件化编程 - 实现以下方法 ```go func Do(ctx context.Context, doc interface{}, opType operator.OpType, opts ...interface{}) error{ // do anything } ``` - 调用middleware包的Register方法，注入`Do` Qmgo会在支持的[操作](operator/operate_type.go)执行前后调用`Do` ```go middleware.Register(Do) ``` [Example](middleware/middleware_test.go) Qmgo的hook、自动更新field和validation tags都基于plugin的方式实现 ## `qmgo` vs `go.mongodb.org/mongo-driver` 下面我们举一个多文件查找、`sort`和`limit`的例子, 说明`qmgo`和`mgo`的相似，以及对`go.mongodb.org/mongo-driver`的改进 官方`Driver`需要这样实现 ```go // go.mongodb.org/mongo-driver // find all 、sort and limit findOptions := options.Find() findOptions.SetLimit(7) // set limit var sorts D sorts = append(sorts, E{Key: "weight", Value: 1}) findOptions.SetSort(sorts) // set sort batch := []UserInfo{} cur, err := coll.Find(ctx, bson.M{"age": 6}, findOptions) cur.All(ctx, &batch) ``` `Qmgo`和`mgo`更简单，而且实现相似： ```go // qmgo // find all 、sort and limit batch := []UserInfo{} cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch) // mgo // find all 、sort and limit coll.Find(bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch) ``` ## `Qmgo` vs `mgo` [Qmgo 和 Mgo 的差异](https://github.com/qiniu/qmgo/wiki/Differences-between-Qmgo-and-Mgo) ## Contributing 非常欢迎您对`Qmgo`的任何贡献，非常感谢您的帮助！ ## 沟通交流: - 加入 [qmgo discussions](https://github.com/qiniu/qmgo/discussions)