使用 MongoDB Java 驱动程序连接到 Amazon DocumentDB

本节提供使用 Java 驱动程序连接到 Amazon DocumentDB 的分步指南。这将使您开始将 DocumentDB 集成到 Java 应用程序中。

步骤 1：设置您的项目

步骤 2：创建连接字符串

Amazon DocumentDB 连接字符串对于在您的应用程序与 DocumentDB 集群之间建立连接至关重要。此字符串封装了重要信息，例如集群端点、端口、身份验证详细信息以及各种连接选项。要构建 DocumentDB 连接字符串，通常需从基本格式开始：

"mongodb://username:password@cluster-endpoint:port/?[connection options]"

您需要将“用户名”和“密码”替换为您的实际凭证。您可以在 AWS 管理控制台 中以及通过 AWS CLI 查找集群的端点和端口号。要查找集群的集群端点，请参阅 查找集群的端点。DocumentDB 的默认端口为 27017。

连接字符串示例

可用于连接字符串的不同选项如下：

TLS 证书

tls=true|false – 此选项将启用或禁用传输层安全性协议（TLS）。默认情况下，在 Amazon DocumentDB 集群上启用传输中加密，因此，除非在集群级别禁用 TLS，否则此选项的值应为 true。

如果使用 TLS，在创建到 DocumentDB 集群的连接时，代码需要提供 SSL 证书。下载建立到集群的安全连接时所需要的证书：global-bundle.pem。可通过两种方式使用 global-bundle.pem 文件。

从只读副本读取

replicaSet=rs0&readPreference=secondaryPreferred – 指定这两个选项会将所有读取请求路由到只读副本，将写入请求路由到主实例。在连接字符串中使用 replicaSet=rs0 可使 MongoDB 驱动程序维护自动更新的集群拓扑视图，从而允许应用程序在添加或移除实例时维护当前节点配置的可见性。未提供这些选项或指定 readPreference=primary 则会将所有读取和写入请求发送到主实例。有关 readPreference 的更多选项，请参阅 读取首选项选项。

写入关注和日志

写入关注决定了针对写入操作从数据库请求的确认级别。MongoDB 驱动程序提供了调整写入关注和日志文件的选项。Amazon DocumentDB 不希望您设置写入关注和日志，并且会忽略为 w 和 j（writeConcern 和 journal）发送的值。DocumentDB 始终使用 writeConcern：majority 和 journal：true 写入数据，因此在向客户端发送确认之前，写入会持久记录在大多数节点上。

RetryWrites

retryWrites=false – DocumentDB 不支持可重试写入，因此应始终将该属性设置为 false。

IAM 身份验证

authSource=%24external 和 authMechanism=MONGODB-AWS – 这两个参数用于使用 AWS Identity and Access Management 进行身份验证。IAM 身份验证目前仅在基于实例的集群版本 5.0 中可用。有关更多信息，请参阅 使用 IAM 身份进行身份验证。

连接池

以下选项可用于连接池：

连接超时参数

超时是一种机制，用于限制操作或连接尝试在被认为失败之前所花费的时间量。以下超时参数可用于防止无限期等待及管理资源分配：

步骤 3：编写连接代码

以下代码示例显示了如何建立到 Amazon DocumentDB 的 TLS 连接：

public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
    String DbClusterEndPoint, String keyStorePass) throws Exception {
    MongoClient connectedClient;
    String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
    String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
        dbName + connectionOptions;

    try {
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
            trustStore.load(fis, keyStorePass.toCharArray());
            TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(trustStore);

            SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
            ConnectionString connectionString = new ConnectionString(connectionUrl);
            MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .applyToSslSettings(builder - > {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
                .build();
            connectedClient = MongoClients.create(settings);
        }
        return connectedClient;
    } catch (MongoException e5) {
        throw new RuntimeException(e5);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

步骤 4：处理连接异常

在 Java 应用程序中使用 DocumentDB 时，处理连接异常对于保持稳健可靠的数据库操作而言至关重要。如果管理得当，这些异常不仅有助于快速诊断问题，还可以确保您的应用程序能够妥善处理临时网络中断或服务器不可用情况，从而提升稳定性和用户体验。与建立连接相关的一些关键异常包括：

步骤 5：运行代码

以下代码示例将创建 Amazon DocumentDB 连接并打印所有数据库：

public static void TestConnection() {
    try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
        List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
        System.out.println("Databases: " + databases);
    } catch (MongoException e) {
        System.err.println("MongoDB error: " + e.getMessage());
        throw new RuntimeException(e);
    }
}

连接最佳实践

以下是使用 MongoDB Java 驱动程序连接到 Amazon DocumentDB 时应考虑的最佳实践：