連接指南
概覽
在本指南中，您可以了解如何使用 MongoDB Java 驅動程序連接到 MongoDB 實例或副本集部署。
有關使用 MongoDB 實例進行身份驗證的信息，請參閱身份驗證。要了解有關將驅動程序與 Java 命名和目錄接口 (JNDI) 結合使用的更多信息，請參閱 JNDI。要為與 MongoDB 實例的連接配置 TLS/SSL 安全性，請參閱TLS/SSL。
Mongo客戶端
使用該MongoClients.create()方法構造一個 MongoClient. 由於每個都MongoClient代表一個線程安全的數據庫連接池，因此大多數應用程序只需要一個 的實例MongoClient，即使跨多個線程也是如此。所有資源使用限制（例如最大連接數）都適用於單個 MongoClient實例。
MongoClient.close()當不再需要實例時，始終調用以清理資源。
連接URI
該連接URI提供了一組指令，該驅動程序使用連接到MongoDB的部署。它指示驅動程序應該如何連接到 MongoDB 以及在連接時應該如何表現。以下示例解釋了示例連接 URI 的每個部分：
在這個例子中，我們使用標准的連接字符串的格式， mongodb為協議。您還可以使用DNS 種子列表連接格式, mongodb+srv，如果您想要更大的部署靈活性以及無需重新配置客戶端即可輪換更改服務器的能力。
如果您的部署在 MongoDB Atlas 上，請參閱 Atlas 驅動程序連接指南 並從語言下拉列表中選擇 Java 以檢索您的連接字符串。
如果您使用基於密碼的身份驗證機制，則連接 URI 的下一部分包含您的憑據。user 用您的用戶名和pass密碼替換 的值。如果您的身份驗證機制不需要憑據，請省略連接 URI 的這一部分。
連接 URI 的下一部分指定主機名或 IP 地址，然后是 MongoDB 實例的端口。在示例中，我們使用sample.host主機名和27017端口。替換這些值以引用您的 MongoDB 實例。
連接 URI 的最后一部分包含連接選項作為參數。在示例中，我們設置了兩個連接選項：maxPoolSize=20和 w=majority。有關連接選項的更多信息，請跳至本指南的 連接選項部分。
以下代碼顯示了如何使用客戶端中的示例連接 URI 連接到 MongoDB。
package fundamentals;
import org.bson.BsonDocument; import org.bson.BsonInt64; import org.bson.Document; import org.bson.conversions.Bson; import com.mongodb.MongoClientSettings; import com.mongodb.MongoException; import com.mongodb.client.MongoClient; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoDatabase;
public class RunCommand { public static void main(String[] args) { // Replace the uri string with your MongoDB deployment's connection string String uri = "mongodb://user:pass@sample.host:27017/?maxPoolSize=20&w=majority"; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("admin"); try { Bson command = new BsonDocument("ping", new BsonInt64(1)); Document commandResult = database.runCommand(command); System.out.println("Connected successfully to server."); } catch (MongoException me) { System.err.println("An error occurred while attempting to run a command: " + me); } } } }
連接到 MongoDB 的其他方式
如果您要連接到未托管在 Atlas 上的單個 MongoDB 服務器實例或副本集，請參閱以下部分以了解如何連接。
連接到本地機器上的 MongoDB 服務器
如果您需要在本地機器上運行 MongoDB 服務器用於開發目的而不是使用 Atlas 集群，則需要完成以下操作：
始終保護您的 MongoDB 服務器免受惡意攻擊。有關安全建議的列表，請參閱我們的 安全檢查表。
成功啟動 MongoDB 服務器后，請在驅動程序連接代碼中指定連接字符串。
如果您的 MongoDB 服務器在本地運行，您可以使用連接字符串 "mongodb://localhost:<port>"，其中<port>是您配置服務器以偵聽傳入連接的端口號。
如果您需要指定不同的主機名或 IP 地址，請參閱我們的服務器手冊中關於連接字符串的條目。
要測試您是否可以連接到您的服務器，請替換Connect to MongoDB Atlas代碼示例中的連接字符串並運行它。
連接到副本集
MongoDB 副本集部署是一組存儲相同數據集的連接實例。這種實例配置提供了數據冗余和高數據可用性。
要連接到副本集部署，請指定一個或多個副本集成員的主機名（或 IP 地址）和端口號，以逗號分隔。默認情況下，指定單個 MongoDB 實例的主機名和端口號僅連接到副本集的指定成員。但是，您可以通過幾種不同的方式自動發現並連接到副本集的所有成員。創建副本集連接：
- 使用
replicaSet參數指定副本集的名稱 directConnection用值指定參數false- 指定多個主機，而不是單個主機
這些方法中的每一種都會導致驅動程序發現副本集中任何未指定的主機。
以下連接字符串指定集群中的三個主機和名為“myRs”的副本集。
mongodb://host1:27017,host2:27017,host3:27017
以下示例顯示如何MongoClient 使用ConnectionString或MongoClientSettings類為實例指定多個主機。選擇與您要查看的代碼片段對應的選項卡：
ConnectionString connectionString = new ConnectionString("mongodb://host1:27017,host2:27017,host3:27017/"); MongoClient mongoClient = MongoClients.create(connectionString);
ServerAddress seed1 = new ServerAddress("host1", 27017); ServerAddress seed2 = new ServerAddress("host2", 27017); ServerAddress seed3 = new ServerAddress("host3", 27017); MongoClientSettings settings = MongoClientSettings.builder() .applyToClusterSettings(builder -> builder.hosts(Arrays.asList(seed1, seed2, seed3))) .build(); MongoClient mongoClient = MongoClients.create(settings);
提示
盡管可以通過僅提供單個主機來連接到副本集部署，但您應該向驅動程序提供完整列表，以確保即使其中一個主機出現故障，它也能夠連接。
該replicaSet選項 是沒有必要連接到副本集，因為驅動程序會自動檢測並連接字符串的副本集控多台主機。
壓縮
您可以壓縮在 MongoDB 實例和驅動程序之間傳遞的消息。MongoDB 驅動程序最多支持三種不同的算法，具體取決於發布版本：
您可以指定一個或多個壓縮算法，但驅動程序使用連接的 MongoDB 實例支持的列表中的第一個壓縮器。
需要 Snappy 或 Zstandard 壓縮的應用程序必須 為這些算法添加顯式依賴項。
啟用壓縮
您可以通過兩種不同的方式為到 MongoDB 實例的連接啟用壓縮：通過連接字符串中的參數，或使用MongoClientSettings.Builder類中的方法。
compressors 傳遞給 的連接字符串中 的參數MongoClients.create()。您可以指定一種或多種壓縮算法，用逗號分隔多個算法：
ConnectionString connectionString = new ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd"); MongoClient mongoClient = MongoClients.create(connectionString);
要使用ConnectionString啟用壓縮，請使用compressors 傳遞給 的連接字符串中 的參數MongoClients.create()。您可以指定一種或多種壓縮算法，用逗號分隔多個算法：
MongoClientSettings settings = MongoClientSettings.builder()
.compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(),
MongoCompressor.createZlibCompressor(),
MongoCompressor.createZstdCompressor()))
.build();
MongoClient client = MongoClients.create(settings);
使用以下字符串指定壓縮算法：
壓縮算法依賴
JDK本身支持Zlib壓縮，但 Snappy和 Zstandard依賴於開源實現。有關詳細信息，請參閱 snappy -java和 zstd-java。
連接選項
本節介紹驅動程序支持的 MongoDB 連接和身份驗證選項。您可以將連接選項作為連接 URI 的參數傳遞來指定客戶端的行為。
|
選項名稱
|
類型
|
描述
|
|---|---|---|
|
maxPoolSize
|
integer
|
指定連接池的最大大小。
|
|
waitQueueTimeoutMS
|
integer
|
指定線程可以等待連接變為可用的最長時間（以毫秒為單位）。
|
|
serverSelectionTimeoutMS
|
integer
|
指定驅動程序在拋出異常之前等待服務器選擇成功的最長時間（以毫秒為單位）。
|
|
localThresholdMS
|
integer
|
當與副本集中的多個MongoDB實例進行通信時，驅動程序只會將請求發送到響應時間小於或等於響應時間最快的服務器加上本地閾值的服務器，以毫秒為單位。
|
|
heartbeatFrequencyMS
|
integer
|
指定驅動程序在嘗試確定集群中每個服務器的當前狀態之間等待的頻率（以毫秒為單位）。
|
|
replicaSet
|
string
|
|
|
ssl
|
boolean
|
指定與 MongoDB 實例的所有通信都應使用 TLS/SSL。被
tls
選項取代。
|
|
tls
|
boolean
|
指定與 MongoDB 實例的所有通信都應使用 TLS。取代
ssl
選項。
|
|
tlsInsecure
|
boolean
|
指定驅動程序應允許 TLS 連接使用無效主機名。它和設置同樣的效果
tlsAllowInvalidHostnames
來
true
。要以其他方式配置 TLS 安全約束，請使用
自定義 SSLContext
。
|
|
tlsAllowInvalidHostnames
|
boolean
|
指定驅動程序應允許證書中的無效主機名用於 TLS 連接。取代
sslInvalidHostNameAllowed
。
|
|
connectTimeoutMS
|
integer
|
指定 Java 驅動程序在超時前等待連接打開的最長時間（以毫秒為單位）。
|
|
socketTimeoutMS
|
integer
|
指定 Java 驅動程序在超時前等待發送或接收請求的最長時間（以毫秒為單位）。
|
|
maxIdleTimeMS
|
integer
|
指定最長時間（以毫秒為單位），Java 驅動程序將允許池連接在關閉連接之前處於空閑狀態。
|
|
maxLifeTimeMS
|
integer
|
指定 Java 驅動程序在關閉連接之前將繼續使用池連接的最長時間（以毫秒為單位）。
|
|
journal
|
boolean
|
指定驅動程序必須等待連接的 MongoDB 實例對所有寫入的磁盤上的日志文件進行分組提交。
|
|
w
|
string or integer
|
|
|
wtimeoutMS
|
integer
|
|
|
readPreference
|
string
|
|
|
readPreferenceTags
|
string
|
|
|
maxStalenessSeconds
|
integer
|
以秒為單位指定驅動程序停止與輔助節點通信之前輔助節點的陳舊程度。不提供參數或將其顯式設置為
-1
表示不應該對輔助節點進行陳舊檢查。最小值為 90 秒或心跳頻率加 10 秒，以較大者為准。有關更多信息，請參閱
maxStalenessSeconds 選項
的服務器文檔 。
|
|
authMechanism
|
string
|
|
|
authSource
|
string
|
指定應根據其驗證提供的憑據的數據庫。默認為
admin
.
|
|
authMechanismProperties
|
string
|
|
|
appName
|
string
|
指定在連接握手期間提供給 MongoDB 實例的應用程序的名稱。可用於服務器日志和分析。
|
|
compressors
|
string
|
指定驅動程序將嘗試使用的一種或多種壓縮算法來壓縮發送到連接的 MongoDB 實例的請求。可能的值包括：
zlib
，
snappy
，和
zstd
。
|
|
zlibCompressionLevel
|
integer
|
|
|
retryWrites
|
boolean
|
指定如果支持的寫操作由於網絡錯誤而失敗，驅動程序必須重試。默認為
true
.
|
|
retryReads
|
boolean
|
指定如果支持的讀取操作由於網絡錯誤而失敗，驅動程序必須重試。默認為
true
.
|
|
uuidRepresentation
|
string
|
|
|
directConnection
|
boolean
|
指定驅動程序必須直接連接到主機。
|
有關完整的選項列表，請參閱 ConnectionString API 參考頁面。
在連接上啟用 TLS/SSL
概覽
在本指南中，您可以了解如何 使用 JDK 中的底層 TLS/SSL 支持通過TLS/SSL安全協議連接到 MongoDB 實例 。要將您的連接配置為使用 TLS/SSL，請在ConnectionString 或MongoClientSettings 中啟用 TLS/SSL 設置。
如果您在設置 TLS/SSL 連接時遇到問題，您可以使用-Djavax.net.debug=all系統屬性查看其他日志語句。有關 更多信息，請參閱調試 TLS/SSL 連接的 Oracle 指南。
啟用 TLS/SSL
您可以通過兩種不同的方式為與 MongoDB 實例的連接啟用 TLS/SSL：通過連接字符串中的參數，或使用MongoClientSettings.Builder類中的方法。
tls，請true在傳遞 給的連接字符串中為連接字符串參數分配一個值MongoClients.create()：
MongoClient mongoClient = MongoClients.create("mongodb+srv://<user>:<password>@<cluster-url>?tls=true");
要MongoClient使用MongoClientSettings.Builder該類配置您的 TLS/SSL 連接選項 ，請調用 applyToSslSettings() 方法。在 塊中設置enabled屬性以啟用 TLS/SSL：trueSslSettings.Builder
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true)) .build(); MongoClient client = MongoClients.create(settings);
配置證書
發起 TLS/SSL 請求的 Java 應用程序需要訪問加密證書，以證明應用程序本身以及與應用程序交互的其他應用程序的身份。您可以使用以下機制在應用程序中配置對這些證書的訪問：
- JVM 信任存儲和 JVM 密鑰存儲
- 客戶端特定的信任存儲和密鑰存儲
我們基於 Oracle JDK 的文檔編寫了以下部分，因此某些部分可能不適用於您的 JDK 或您使用的自定義 TLS/SSL 實現。
配置 JVM 信任存儲
默認情況下，JRE 包含許多來自Let's Encrypt等簽名機構的常用公共證書。因此，您可以使用 TLS/SSL連接到MongoDB Atlas 的實例（或任何其他服務器，其證書由 JRE 的默認證書存儲中的權威簽名），而無需配置信任存儲。
JVM 信任存儲保存證書，這些證書可以安全地識別與您的 Java 應用程序交互的其他應用程序。使用這些證書，您的應用程序可以證明與另一個應用程序的連接是真實且安全的，不會被第三方篡改。
如果您的 MongoDB 實例使用由 JRE 的默認證書存儲中不存在的機構簽署的證書，則您的應用程序必須配置兩個系統屬性以啟動 SSL/TLS 請求。這些屬性確保您的應用程序能夠驗證連接的 MongoDB 實例提供的 TLS/SSL 證書。
javax.net.ssl.trustStore：包含簽名機構證書的信任庫的路徑javax.net.ssl.trustStorePassword：訪問定義的信任庫的密碼javax.net.ssl.trustStore
您可以使用 作為 JDK 一部分提供的keytool命令行工具創建信任存儲：
keytool -importcert -trustcacerts -file <path to certificate authority file>
-keystore <path to trust store> -storepass <password>
配置 JVM 密鑰庫
默認情況下，MongoDB 實例不執行客戶端證書驗證。如果您顯式配置 MongoDB 實例以驗證客戶端證書，則只需配置密鑰庫。
JVM 密鑰庫保存證書，這些證書可以安全地向其他應用程序標識您的 Java 應用程序。使用這些證書，其他應用程序可以證明與您的應用程序的連接是真實且安全的，不會被第三方篡改。
發起 TLS/SSL 請求的應用程序需要設置兩個 JVM 系統屬性，以確保客戶端向 MongoDB 服務器提供 TLS/SSL 證書：
javax.net.ssl.keyStore：包含客戶端 TLS/SSL 證書的密鑰庫的路徑javax.net.ssl.keyStorePassword：訪問定義的密鑰庫的密碼javax.net.ssl.keyStore
您可以使用keytool 或openssl命令行工具創建密鑰庫。
有關配置 Java 應用程序以使用 TLS/SSL 的更多信息，請參閱JSSE 參考指南。
配置客戶端特定的信任庫和密鑰庫
您可以使用類的init()方法配置特定於客戶端的信任庫和密鑰庫 SSLContext。
您可以SSLContext 在本指南的使用 SSLContext 自定義 TLS/SSL 配置部分中找到展示如何使用實例配置客戶端的示例 。
有關SSLContext該類的更多信息，請參閱SSL Context的 API 文檔。
禁用主機名驗證
默認情況下，驅動程序確保服務器的 TLS/SSL 證書中包含的主機名與構建MongoClient. 如果您需要為您的應用程序禁用主機名驗證，您可以通過在 builder lambdainvalidHostNameAllowed中將構建器的屬性設置為來顯式禁用它 ：trueapplytoSslSettings()
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> { builder.enabled(true); builder.invalidHostNameAllowed(true); }) .build();
禁用主機名驗證會使您的配置 不安全。您應該僅出於測試目的或在沒有其他選擇時禁用主機名驗證。
僅限制與 TLS 1.2 的連接
要將您的應用程序限制為僅使用 TLS 1.2 協議，請將jdk.tls.client.protocols系統屬性設置 為“TLSv1.2”。
Java 8 之前的 Java 運行時環境 (JRE) 僅在更新版本中啟用 TLS 1.2 協議。如果您的 JRE 尚未啟用 TLS 1.2 協議，您可能需要升級到更高版本才能使用 TLS 1.2 進行連接。
使用 SSLContext 自定義 TLS/SSL 配置
如果您的 TLS/SSL 配置需要額外的自定義，您可以通過將SSLContext 對象傳遞給lambda 中的構建器來設置您的sslContext屬性：MongoClientapplyToSslSettings()
SSLContext sslContext = ... MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> { builder.enabled(true); builder.context(sslContext); }) .build(); MongoClient client = MongoClients.create(settings);
在線證書狀態協議 (OCSP)
OCSP 是用於檢查 X.509 證書是否已被撤銷的標准。證書頒發機構可以在到期時間之前將 X.509 證書添加到證書吊銷列表 (CRL) 以使證書無效。當客戶端在 TLS 握手期間發送 X.509 證書時，CA 的吊銷服務器會檢查 CRL 並返回“良好”、“已撤銷”或“未知”狀態。
該驅動程序支持以下 OCSP 變體：
- 客戶端驅動的 OCSP
- OCSP 裝訂
以下部分描述了它們之間的區別以及如何為您的應用程序啟用它們。
Java 驅動程序使用為應用程序配置的 JVM 參數，並且不能被特定MongoClient實例覆蓋。
客戶端驅動的 OCSP
在客戶端驅動的 OCSP 中，客戶端在收到服務器的證書后，將證書在 OCSP 請求中發送給 OCSP 響應者。OCSP 響應器通過證書頒發機構 (CA) 檢查證書的狀態，並在發送給客戶端的響應中報告它是否有效。
要為您的應用程序啟用客戶端驅動的 OCSP，請設置以下 JVM 系統屬性：
|
Property
|
Value
|
|---|---|
com.sun.net.ssl.checkRevocation
|
將此屬性設置
true
為啟用吊銷檢查。
|
ocsp.enable
|
將此屬性設置
true
為啟用客戶端驅動的 OCSP。
|
如果 OCSP 響應程序不可用，則 JDK 提供的 TLS 支持會報告“硬故障”。這與 MongoDB Shell 和其他一些驅動程序的“軟失敗”行為不同。
OCSP 裝訂
OCSP 裝訂是一種機制，在該機制中，服務器必須從證書頒發機構 (CA) 獲取簽名證書，並將其包含在給客戶端的帶有時間戳的 OCSP 響應中。
要為您的應用程序啟用 OCSP 裝訂，請設置以下 JVM 系統屬性：
|
Property
|
Description
|
|---|---|
com.sun.net.ssl.checkRevocation
|
將此屬性設置
true
為啟用吊銷檢查。
|
jdk.tls.client.enableStatusRequestExtension
|
將此屬性設置
true
為啟用 OCSP 裝訂。
如果未設置或設置為
false
，則無論證書吊銷響應是否存在或狀態如何，連接都可以繼續。
|
有關 OCSP 的其他信息，請查看以下資源：
- Oracle JDK 8 關於如何為應用程序啟用 OCSP 的文檔
- OCSP 的官方 IETF 規范 (RFC 6960)
官網地址：https://docs.mongodb.com/drivers/java/sync/current/fundamentals/connection/