连接指南

一个连接 URI 的组成部分

以下的例子解释了示例连接 URI 的各个组成部分：

在此示例中，我们使用 mongodb 作为协议，它指定了标准连接字符串格式。如果想要获得更高的部署灵活性，并且能够在不重新配置客户端的情况下更改轮换的服务器，也可以使用 DNS 种子列表连接格式。

连接字符串的下一部分包含您的数据库用户名，如果使用基于密码的身份验证，则还包含您的密码。将 user 的值替换为您的数据库用户名，将 pass 替换为您的密码。如果您使用的是不需要用户名和密码的身份验证机制，请省略连接 URI 中的这一部分。

连接字符串的下一部分用来指定您 MongoDB 实例的主机名或 IP 地址和端口。在前面的例子中，我们使用 sample.host 作为主机名，27017 作为端口。请将这些值替换为指向您 MongoDB 实例的值。

连接字符串的最后一部分指定了连接和身份验证选项。在此示例中，设置了两个连接选项：maxPoolSize=20 和 w=majority。要了解有关连接选项的更多信息，请阅读本指南的连接选项部分。

连接示例

要连接到 MongoDB，必须创建一个客户端。客户端可管理您的连接并运行数据库命令。

您可以通过将 ClientOptions 对象传递给 Connect() 方法，创建使用连接字符串和其他客户端选项的客户端。

要指定您的连接 URI，请将其传递给 ApplyURI() 方法，该方法会返回一个新的 ClientOptions 实例。要设置任何其他选项，请从 options 包中调用相关辅助方法。

要了解有关连接选项的更多信息，请参阅“连接选项”部分。要了解有关创建客户端的更多信息，请参阅客户端和 Connect() 的 API 文档。

您可以将 Stable API 版本作为一个选项设置，以避免升级到新的服务器版本时出现破坏性变更 (breaking change)。要了解有关 Stable API 功能的更多信息，请参阅 Stable API 页面。

以下代码展示了如何创建使用 Atlas 连接字符串和 Stable API 版本的客户端、如何连接到 MongoDB 以及如何验证连接是否成功：

// Connects to MongoDB and sets a Stable API version
package main
import (
	"context"
	"fmt"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)
// Replace the placeholder with your Atlas connection string
const uri = "<connection string>"
func main() {
	// Use the SetServerAPIOptions() method to set the Stable API version to 1
	serverAPI := options.ServerAPI(options.ServerAPIVersion1)
	opts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI)
	// Create a new client and connect to the server
	client, err := mongo.Connect(context.TODO(), opts)
	if err != nil {
		panic(err)
	}
	defer func() {
		if err = client.Disconnect(context.TODO()); err != nil {
			panic(err)
		}
	}()
	// Send a ping to confirm a successful connection
	var result bson.M
	if err := client.Database("admin").RunCommand(context.TODO(), bson.D{{"ping", 1}}).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Println("Pinged your deployment. You successfully connected to MongoDB!")
}

连接到本地计算机上的 MongoDB Server

如果出于开发目的必须在本地计算机上运行 MongoDB Server，请完成以下步骤：

1. 下载 MongoDB Server Community 或 Enterprise 版本。

2. 安装并配置 MongoDB Server。

3. 启动该服务器。

在成功启动 MongoDB 服务器后，在驱动程序连接代码中指定连接字符串。

如果 MongoDB Server 在本地运行，您可以使用连接字符串 "mongodb://localhost:<port>"，其中 <port> 是您配置服务器以侦听传入连接的端口号。

如果想要指定其他主机名或 IP 地址，请参阅服务器手册中关于连接字符串的条目。

要测试能否连接到服务器，请在前面的代码示例中将连接字符串替换为 localhost 连接字符串。

连接到副本集

MongoDB 副本集部署是一组用于存储相同数据集的连接实例。这种配置提供了数据冗余和高数据可用性。

要连接到副本集部署，请指定每个实例的主机名和端口号（以逗号分隔），并将副本集名称指定为连接字符串中 replicaSet 参数的值。在以下示例中，主机名为 host1、host2 和 host3，端口号均为 27017 。副本集名称为 myRS 。

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS

连接到副本集时，驱动程序默认执行以下操作：

• 在给定任一节点的地址时发现所有副本集节点。

• 将操作分派给相应节点，例如，对主节点进行写入的指令。

单一超时设置

您可以通过 SetTimeout() 方法或在连接 URI 字符串中指定 timeoutMS 选项，在 Client 上设置一个单独的 Timeout 选项，以控制执行单个操作所需的时间。如果您没有为针对同一实体的操作设置上下文，则代码中其他位置的 Database、Collection、Session、ChangeStream 和 Bucket 实例将继承 Client 中的 Timeout 选项。

如果您在操作中传递了一个具有截止时间的上下文，驱动程序将使用该上下文的截止时间执行操作。如果上下文没有截止时间，则驱动程序会使用 Client 上设置的 Timeout 选项基于给定上下文派生出新的上下文。

以下代码展示了如何使用 SetTimeout 选项在 Client 上设置 Timeout 选项：

opts := options.Client().SetTimeout(5 * time.Second)

以下示例展示了如何使用 URI 选项设置单个超时并执行继承此设置的操作：

uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000"
client := mongo.Connect(context.TODO(), uri)
coll := client.Database("<db>").Collection("<collection>")
...
coll.InsertOne(context.Background(), doc)