MongoDB 连接 URI 简介

导言

连接到数据库服务器通常是你在设计和配置数据库支持的应用程序时需要完成的首要任务之一。虽然有许多方法可以向应用程序提供地址、监听端口、凭据和其他详细信息，但连接 URI（有时称为连接字符串或连接 URL）是一种以紧凑格式指定复杂配置的最强大和最灵活的方式之一。

在本指南中，我们将讨论如何使用你的 MongoDB 数据库信息和认证详细信息来格式化连接 URI。连接 URI 分为多个部分，我们将逐步介绍每个部分。

百分比编码值

在我们开始之前，我们应该提到 MongoDB 连接 URI 期望使用百分比编码值。这意味着 URL 中任何具有特殊含义的字符都必须转换为其百分比编码的对应字符，以确保库和应用程序能够正确解释它们。

应进行百分比编码的字符包括

• :： %3A
• /： %2F
• ?： %3F
• #: %23
• [： %5B
• ]： %5D
• @: %40

这些在连接 URI 中具有特殊含义。

因此，如果你的密码是...

pe@ce&lo\/3

...你需要在连接 URI 中将其指定为

pe%40ce&lo\%2F3

如果你不确定某个字符是否应进行百分比编码，通常最好还是将其编码。例如，如果你不确定字符 \ 是否为保留字符，为了安全起见，可以使用其百分比编码等效项 %5C。

pe%40ce%26lo%5C%2F3

在构建连接 URI 时，请牢记这一点。

快速概览

在我们深入细节之前，我们可以先了解一下 MongoDB 连接 URI 的规范

mongodb://[username:password@]host[:port][,...hostN[:port]][/[database][?parameter_list]]

\________/\__________________/\___________________________/\__________/\________________/
     |             |                        |                    |             |
     |- schema     |- auth credentials      |                    |             |- parameter list
                                            |                    |
                                            |                    |- default authentication database
                                            |
                                            |- host specifier

方括号中的部分表示可选部分。你可能已经注意到 URI 的大部分部分都是可选的。可能也很明显，你可以在 URI 中编码许多信息。

各个组件的快速描述

• mongodb://：用于将字符串标识为 MongoDB 连接 URI 的 Schema 标识符。
• auth credentials：URI 的一个可选组件，可用于指定连接时使用的用户和密码。
  • username：可选的用户名。如果包含，它应在第二个斜杠 (/) 之后开始，并持续到冒号 (:)。如果包含，则必须附带 password。
  • password：可选的密码。如果包含，它在冒号 (:) 之后开始，并持续到 at 符号 (@)。如果包含，则必须附带 username。
• host specifier：一个必需组件，用于指定一个或多个要连接的主机名和端口。
  • host：要连接的服务器的 IP 地址、DNS 名称或本地可解析名称。主机名持续到冒号 (:)（如果包含端口）、逗号 (,)（如果指定了多个主机），或者斜杠 (/)。必须至少提供一个主机。
  • port：可选的端口规范，用于指示 MongoDB 在主机上监听的端口。端口以冒号 (:) 开头，并持续到逗号 (,)（如果提供了另一个主机）或斜杠 (/)（如果未提供）。
• default authentication database：如果参数列表中未提供更具体的 authSource，则用于认证的数据库名称。如果此处或使用 authSource 未指定数据库，MongoDB 将尝试对标准 admin 数据库进行认证。
• parameter list：一个可选的额外参数列表，可以影响连接行为。参数列表以问号 (?) 开头。如果未提供默认认证数据库，则必须在最后一个主机定义后使用斜杠和问号 (/?) 开始参数列表。
  • parameter pairs：参数列表由键值对组成。每对中的键和值由等号 (=) 分隔，每对之间由和号 (&) 分隔。

以下是一个包含所有这些组件的 MongoDB 连接 URI 示例

mongodb://sally:sallyspassword@dbserver.example:5555/userdata?tls=true&connectionTimeout=5000
 ^          ^         ^               ^           ^     ^          ^
 |- schema  |         |- password     |- host     |     |          |- parameter list
            |                                     |     |
            |- username                           |     |- default authentication database
                                                  |
                                                  |- port

指定 URI 类型

连接 URI 中的项目通常是协议规范或应用程序类型。由于 URI 将用于连接和认证到 MongoDB 数据库，我们需要使用一个标识符来向我们正在使用的应用程序和库表明这一点。

MongoDB 项目仅接受 mongodb 作为有效的 URI Schema 指定符。因此，你应该始终这样开始你的连接 URI

mongodb://

Schema 指定符将确保后续信息在正确的上下文中被解释。

指定用户名和密码

URI 的下一部分是用户凭据。用户凭据是可选的，但如果你不想依赖应用程序或数据库配置的默认值，通常是必需的。

要包含用户凭据，请在 Schema 标识符后提供用户名，接着是冒号 (:)、密码，最后是 at 符号 (@)

mongodb://username:password@

用户凭据是可选的，但如果包含，你必须同时提供用户名和密码组件。

指定服务器监听位置

用户凭据之后是主机指定符，它定义了服务器的监听位置。可以在主机指定符中定义一个或多个主机，但由于主机指定符是必需的，因此必须至少提供一个主机。

每个主机定义都包含一个 host 和一个可选的 port。host 可以是本地可解析的主机名、由 DNS 等外部名称系统解析的名称，或者是 IP 地址或其他直接地址。端口表示 MongoDB 在主机上监听的端口号。

要指定应用程序应尝试连接到本地计算机上默认的 MongoDB 端口 (27017)，你可以使用

mongodb://localhost

如果你需要包含用户名和密码，这些信息将首先出现并由 at 符号分隔

mongodb://username:password@localhost

要指定在非标准端口上运行的远程服务器，请用冒号分隔这些详细信息。例如，要连接到 198.51.100.22 主机上的 3333 端口，你可以使用

mongodb://username:password@198.51.100.22:3333

要定义多个主机和端口对，请用逗号 (,) 分隔这些集合，以告诉应用程序如果第一个服务器无法访问，则尝试后面的服务器。例如，要扩展上一个示例以包含一个在 198.51.100.33 的 5555 端口上监听的备用服务器，你可以使用

mongodb://username:password@198.51.100.22:3333,198.51.100.33:5555

符合规范的客户端和应用程序将首先尝试连接到在 198.51.100.22:3333 监听的服务器。如果失败，它们将尝试连接到在 198.51.100.33:5555 监听的 MongoDB 数据库。

提供默认认证数据库

在主机指定符之后，下一部分数据是默认认证数据库。虽然并非所有数据库管理系统都如此，但在 MongoDB 中，在建立连接时，你必须对特定的数据库进行认证。

数据库名称以正斜杠 (/) 开头，并持续到行尾或问号 (?)。如果参数列表中未提供 authSource 选项，将使用默认认证数据库。如果两者都未提供，客户端将对 admin 数据库进行认证。

要连接到在 198.51.100.22:3333 监听的 MongoDB 服务器上托管的名为 sales 的数据库，你可以输入

mongodb://username:password@198.51.100.22:3333/sales

指定额外参数

连接 URI 的最后一部分用于提供连接的额外参数。参数列表由一个前导问号 (?) 引入，并持续到行尾。如果未提供默认认证数据库，则表示主机规范结束的尾部斜杠必须直接位于问号之前 (/?)。

列出的每个参数都定义为由等号 (=) 连接的键值对。在第一个参数对之后，每个额外的键值对都由一个和号 (&) 分隔。

例如，要指定客户端应对我们之前定义的连接应用 10 秒超时，你可以使用

mongodb://username:password@198.51.100.22:3333/sales?connectTimeoutMS=10000

如果你想提供额外的参数，可以在后面用和号 (&) 将每个键值对分隔开。例如，我们还可以指定需要 SSL，并且指定的主机是我们希望连接的副本集成员

mongodb://username:password@198.51.100.22:3333,198.51.100.33:5555/sales?connectTimeoutMS=10000&tls=true&replicaSet=someReplicaSet

MongoDB 文档中有一个完整的参数列表，你可以阅读以了解更多信息。

总结

在本指南中，我们讨论了 MongoDB 连接 URI 是什么，如何解释各个组件，以及如何根据一组连接信息构建自己的 URI。连接 URI 将连接到给定数据库所需的所有信息编码在一个字符串中。由于这种灵活性及其广泛采用，理解如何解析和构建这些字符串非常有帮助。