# MongoDB Go Driver
MongoDB 官方支持的 Go driver。
请参阅以下资源，了解有关从 1.x 版本升级到 2.0 版本的更多信息：
- [v2.0 迁移指南](docs/migration-2.0.md)
- [v2.0 新特性](https://www.mongodb.com/docs/drivers/go/upcoming/whats-new/#what-s-new-in-2.0)
MongoDB Go Driver 的发布遵循[语义化版本控制](https://semver.org/)。
## 要求
## 安装
开始使用 MongoDB Go Driver 的推荐方法是使用 Go modules 在您的项目中安装依赖。
这可以通过从 `go.mongodb.org/mongo-driver` 导入 package 并在构建步骤中安装依赖来完成，
或者通过显式运行以下命令：
```
go get go.mongodb.org/mongo-driver/v2/mongo
```
```
dep ensure -add "go.mongodb.org/mongo-driver/v2/mongo"
```
## 用法
要开始使用该 driver，请导入 `mongo` package 并使用 `Connect` 函数创建一个 `mongo.Client`：
```
import (
"context"
"time"
"go.mongodb.org/mongo-driver/v2/mongo"
"go.mongodb.org/mongo-driver/v2/mongo/options"
"go.mongodb.org/mongo-driver/v2/mongo/readpref"
)
client, _ := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017"))
```
请确保在实例化 client 后，使用 defer 调用 `Disconnect`：
```
defer func() {
if err := client.Disconnect(ctx); err != nil {
panic(err)
}
}()
```
有关更高级的配置和身份验证，请参阅 [mongo.Connect 的文档](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/mongo#Connect)。
调用 `Connect` 不会阻塞以进行 server discovery。如果您想知道是否已找到并连接到 MongoDB server，请使用 `Ping` 方法：
```
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
_ = client.Ping(ctx, readpref.Primary())
```
要向 collection 中插入文档，首先需要从 `Client` 获取一个 `Database`，然后获取 `Collection` 实例：
```
collection := client.Database("testing").Collection("numbers")
```
然后可以使用 `Collection` 实例来插入文档：
```
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
res, _ := collection.InsertOne(ctx, bson.D{{"name", "pi"}, {"value", 3.14159}})
id := res.InsertedID
```
要使用 `bson.D`，您需要将 `"go.mongodb.org/mongo-driver/v2/bson"` 添加到您的 import 中。
您的 import 语句现在应该如下所示：
```
import (
"context"
"log"
"time"
"go.mongodb.org/mongo-driver/v2/bson"
"go.mongodb.org/mongo-driver/v2/mongo"
"go.mongodb.org/mongo-driver/v2/mongo/options"
"go.mongodb.org/mongo-driver/v2/mongo/readpref"
)
```
一些查询方法会返回一个 cursor，可以像这样使用：
```
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
cur, err := collection.Find(ctx, bson.D{})
if err != nil {
log.Fatal(err)
}
defer cur.Close(ctx)
for cur.Next(ctx) {
var result bson.D
if err := cur.Decode(&result); err != nil {
log.Fatal(err)
}
// do something with result....
}
if err := cur.Err(); err != nil {
log.Fatal(err)
}
```
对于返回单个 item 的方法，会返回一个 `SingleResult` 实例：
```
var result struct {
Value float64
}
filter := bson.D{{"name", "pi"}}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err := collection.FindOne(ctx, filter).Decode(&result)
if errors.Is(err, mongo.ErrNoDocuments) {
// Do something when no record was found
} else if err != nil {
log.Fatal(err)
}
// Do something with result...
```
更多示例和文档可以在 examples 目录和 [MongoDB 文档网站](https://www.mongodb.com/docs/drivers/go/current/)上找到。
### 网络压缩
网络压缩将减少 MongoDB 和应用程序之间的带宽需求。
Go Driver 支持以下压缩算法：
1. [Snappy](https://google.github.io/snappy/) (`snappy`)：在 MongoDB 3.4 及更高版本中可用。
2. [Zlib](https://zlib.net/) (`zlib`)：在 MongoDB 3.6 及更高版本中可用。
3. [Zstandard](https://github.com/facebook/zstd/) (`zstd`)：在 MongoDB 4.2 及更高版本中可用。
#### 指定压缩算法
可以通过连接字符串上的 `compressors` 参数或使用 [`ClientOptions.SetCompressors`](https://pkg.go.dev/go.mongodb.org/mongo-driver/mongo/options#ClientOptions.SetCompressors) 来启用压缩：
```
opts := options.Client().ApplyURI("mongodb://localhost:27017/?compressors=snappy,zlib,zstd")
client, _ := mongo.Connect(opts)
```
```
opts := options.Client().SetCompressors([]string{"snappy", "zlib", "zstd"})
client, _ := mongo.Connect(opts)
```
如果设置了压缩器，Go Driver 会与 server 协商以选择第一个双方都支持的压缩器。有关 server 配置和默认值，请参阅 [`networkMessageCompressors`](https://www.mongodb.com/docs/manual/reference/program/mongod/#std-option-mongod.--networkMessageCompressors)。
只有当双方都启用了网络压缩时，消息才会被压缩；否则，消息将保持未压缩状态
## 贡献
## 持续集成
提交到 master 分支的代码会自动在 [evergreen](https://evergreen.mongodb.com/waterfall/mongo-go-driver) 上运行。
## 常见问题
请参阅我们的[常见问题](docs/common-issues.md)文档，以排查经常遇到的问题。
## 致谢
- Go Gopher 插图由 [@ashleymcnamara](https://github.com/ashleymcnamara) 创作
- 原始的 Go Gopher 由 [Renee French](http://reneefrench.blogspot.com/) 设计
## 许可证
MongoDB Go Driver 采用 [Apache License](LICENSE) 授权。