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 的模式标识符。
• 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:[email protected]:5555/userdata?tls=true&connectionTimeout=5000
 ^          ^         ^               ^           ^     ^          ^
 |- schema  |         |- password     |- host     |     |          |- parameter list
            |                                     |     |
            |- username                           |     |- default authentication database
                                                  |
                                                  |- port

指定 URI 类型

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

MongoDB 项目只接受 mongodb 作为有效的 URI 模式指示符。因此，您应该始终以这种方式开始您的连接 URI

mongodb://

模式标识符将确保后续信息在正确的上下文中被解释。

指定用户名和密码

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

要包含用户凭据，请在模式标识符后提供用户名，后跟冒号 (:)，密码，最后是“@”符号 (@)

mongodb://username:password@

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

指定服务器正在监听的位置

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

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

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

mongodb://127.0.0.1

如果您需要包含用户名和密码，该信息将首先出现，并由“@”符号分隔

mongodb://username:password@localhost

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

mongodb://username:[email protected]:3333

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

mongodb://username:[email protected]:3333,198.51.100.33:5555

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

提供默认身份验证数据库

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

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

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

mongodb://username:[email protected]:3333/sales

指定其他参数

连接 URI 的最后一部分用于为连接提供其他参数。参数列表以引导问号 (?) 开头，并一直延续到行尾。如果没有提供默认身份验证数据库，则指示主机规范结束的尾随斜杠必须直接位于问号之前 (/?)。

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

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

mongodb://username:[email protected]:3333/sales?connectTimeoutMS=10000

如果您想提供其他参数，您可以在每个对之间使用与号 (&) 将它们添加到后面。例如，我们可以额外指定我们需要 SSL，并且指定的服务器是我们要连接到的副本集的成员

mongodb://username:[email protected]:3333,198.51.100.33:5555/sales?connectTimeoutMS=10000&tls=true&replicaSet=someReplicaSet

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

结论

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