云数据库 MongoDB SDK 连接配置

正确的 SDK 连接配置是保障 MongoDB 服务稳定运行的基础。连接串中的参数直接决定了鉴权方式、故障切换行为、连接池效率和读写可靠性——任何一项配置缺失或不当，都可能在生产环境引发连接失败、性能下降或数据一致性问题。本文提供 Python、Java、Node.js、Go 四种主流 SDK 的连接配置示例，所有示例均已内置连接池、超时、重试、写关注（w=majority）和读偏好（secondaryPreferred）等生产环境推荐配置，可直接用于生产环境，也可根据实际业务需求调整参数值。连接串中的用户名、密码和地址请替换为实际实例信息（可在腾讯云控制台 > MongoDB > 实例详情页获取）。
Python（pymongo）
Python 生态中，`pymongo` 是 MongoDB 官方维护的驱动库，提供同步连接模式，适用于 Web 后端（如 Flask、Django）和数据处理脚本等场景。以下示例展示了四种连接方式的完整配置，包含连接池、超时、重试和读写策略等生产环境推荐参数。`pymongo` 的连接池由驱动内部自动管理，通过 `maxPoolSize` 和 `minPoolSize` 控制连接数量，无需手动创建或释放连接。
from pymongo import MongoClient
from pymongo.read_preferences import ReadPreference
﻿
# 分片集群：SRV 连接（自动发现 Mongos，扩缩容无需改连接串）
client = MongoClient(
    "mongodb+srv://mongouser:password@xxx.tencentcdb.com/admin",
    authSource="admin",
    
    # 连接池配置
    maxPoolSize=150,
    minPoolSize=10,
    maxIdleTimeMS=120000,
    waitQueueTimeoutMS=5000,
    
    # 超时配置
    connectTimeoutMS=10000,
    serverSelectionTimeoutMS=5000,
    
    # 可靠性配置
    retryWrites=True,
    retryReads=True,
    w="majority",
    
    # 读偏好
    readPreference=ReadPreference.SECONDARY_PREFERRED
)
﻿
# 副本集：使用控制台默认连接串（包含所有节点地址）
client = MongoClient(
    "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.101:27017,10.0.0.102:27017/admin",
    authSource="admin",
    replicaSet="cmgo-xxxxxxxx",
    maxPoolSize=150,
    retryWrites=True,
    w="majority",
    readPreference=ReadPreference.SECONDARY_PREFERRED
)
﻿
# 分片集群：LB 地址连接（默认方式，绝大多数场景适用）
client = MongoClient(
    "mongodb://mongouser:password@10.0.0.100:27017/admin",
    authSource="admin",
    maxPoolSize=150,
    retryWrites=True,
    w="majority",
    readPreference=ReadPreference.SECONDARY_PREFERRED
)
﻿
# 分片集群：连接所有 Mongos（需先开通 Mongos 访问地址）
client = MongoClient(
    "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.100:27018,10.0.0.100:27019/admin",
    authSource="admin",
    maxPoolSize=150,
    retryWrites=True,
    w="majority",
    readPreference=ReadPreference.SECONDARY_PREFERRED
)
﻿
# 连接健康检查
def check_connection():
    try:
        client.admin.command('ping')
        print("MongoDB 连接正常")
        return True
    except Exception as e:
        print(f"MongoDB 连接失败: {e}")
        return False
Java（MongoDB Driver）
Java 生态中，mongodb-driver-sync 是 MongoDB 官方提供的同步驱动，广泛应用于 Spring Boot、微服务等企业级项目。Java 驱动通过 MongoClientSettings 构建器模式配置连接参数，将连接池、超时、写关注和读偏好等配置统一管理。以下示例将四种连接方式封装为独立方法，共享同一套 MongoClientSettings 配置，便于在不同架构间切换。连接池由驱动内部维护，应用只需调用对应方法获取 MongoClient 实例即可，无需手动管理连接生命周期。
import com.mongodb.ConnectionString;
import com.mongodb.MongoClientSettings;
import com.mongodb.ReadPreference;
import com.mongodb.WriteConcern;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import java.util.concurrent.TimeUnit;
﻿
public class MongoDBConfig {
    
    // 分片集群：SRV 连接
    public static MongoClient createClientWithSRV() {
        String uri = "mongodb+srv://mongouser:password@xxx.tencentcdb.com/admin"
                   + "?authSource=admin";
        return createClientFromUri(uri);
    }
    
    // 副本集：控制台默认连接串（包含所有节点地址）
    public static MongoClient createClientWithReplicaSet() {
        String uri = "mongodb://mongouser:password"
                   + "@10.0.0.100:27017,10.0.0.101:27017,10.0.0.102:27017/admin"
                   + "?authSource=admin&replicaSet=cmgo-xxxxxxxx";
        return createClientFromUri(uri);
    }
    
    // 分片集群：LB 地址连接（绝大多数场景适用）
    public static MongoClient createClientWithLB() {
        String uri = "mongodb://mongouser:password@10.0.0.100:27017/admin"
                   + "?authSource=admin";
        return createClientFromUri(uri);
    }
    
    // 分片集群：连接所有 Mongos
    public static MongoClient createClientWithAllMongos() {
        String uri = "mongodb://mongouser:password"
                   + "@10.0.0.100:27017,10.0.0.100:27018,10.0.0.100:27019/admin"
                   + "?authSource=admin";
        return createClientFromUri(uri);
    }
﻿
    private static MongoClient createClientFromUri(String uri) {
        MongoClientSettings settings = MongoClientSettings.builder()
            .applyConnectionString(new ConnectionString(uri))
            
            // 连接池配置
            .applyToConnectionPoolSettings(builder -> builder
                .maxSize(150)
                .minSize(10)
                .maxConnectionIdleTime(120, TimeUnit.SECONDS)
                .maxWaitTime(5, TimeUnit.SECONDS))
            
            // 超时配置
            .applyToSocketSettings(builder -> builder
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(30, TimeUnit.SECONDS))
            
            .applyToClusterSettings(builder -> builder
                .serverSelectionTimeout(5, TimeUnit.SECONDS))
            
            // 可靠性配置
            .retryWrites(true)
            .retryReads(true)
            .writeConcern(WriteConcern.MAJORITY)
            .readPreference(ReadPreference.secondaryPreferred())
            
            .build();
        
        return MongoClients.create(settings);
    }
}
Node.js（MongoDB Driver）
Node.js 生态中，mongodb 是官方驱动包，基于异步 I/O 模型，适合高并发的 Web 服务（如 Express、Koa、NestJS）和 Serverless 函数等场景。以下示例将连接池、超时、重试和读写策略等通用参数提取为 commonOptions 对象，四种连接方式共享同一套配置，切换连接方式时只需修改 URI 即可。Node.js 驱动的连接池同样由驱动自动管理，每次调用 client.connect() 后即可复用连接池中的连接，无需手动创建或关闭单个连接。
const { MongoClient, ReadPreference } = require('mongodb');
﻿
// 通用连接配置
const commonOptions = {
    maxPoolSize: 150,
    minPoolSize: 10,
    maxIdleTimeMS: 120000,
    waitQueueTimeoutMS: 5000,
    connectTimeoutMS: 10000,
    serverSelectionTimeoutMS: 5000,
    retryWrites: true,
    retryReads: true,
    w: 'majority',
    readPreference: ReadPreference.SECONDARY_PREFERRED
};
﻿
// 分片集群：SRV 连接
async function connectWithSRV() {
    const uri = "mongodb+srv://mongouser:password@xxx.tencentcdb.com/admin?authSource=admin";
    const client = new MongoClient(uri, commonOptions);
    await client.connect();
    await client.db('admin').command({ ping: 1 });
    console.log('SRV 连接成功');
    return client;
}
﻿
// 副本集：控制台默认连接串
async function connectReplicaSet() {
    const uri = "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.101:27017,10.0.0.102:27017/admin?authSource=admin&replicaSet=cmgo-xxxxxxxx";
    const client = new MongoClient(uri, commonOptions);
    await client.connect();
    console.log('副本集连接成功');
    return client;
}
﻿
// 分片集群：LB 地址连接（绝大多数场景适用）
async function connectWithLB() {
    const uri = "mongodb://mongouser:password@10.0.0.100:27017/admin?authSource=admin";
    const client = new MongoClient(uri, commonOptions);
    await client.connect();
    console.log('LB 连接成功');
    return client;
}
﻿
// 分片集群：连接所有 Mongos
async function connectWithAllMongos() {
    const uri = "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.100:27018,10.0.0.100:27019/admin?authSource=admin";
    const client = new MongoClient(uri, commonOptions);
    await client.connect();
    console.log('全 Mongos 连接成功');
    return client;
}
Go（mongo-driver）
Go 生态中，mongo-driver 是 MongoDB 官方维护的驱动库，适用于高性能后端服务和微服务架构。Go 驱动通过 options.Client() 链式调用配置连接参数，支持连接池、超时、重试和读写策略等完整配置项。以下示例将通用配置封装在 createClient 函数中，四种连接方式只需传入不同的 URI 即可复用同一套配置逻辑。Go 驱动要求在连接时传入 context.Context 以控制超时，建议在应用启动时创建一次 mongo.Client 实例并在整个生命周期中复用，避免重复建立连接。
package main
﻿
import (
    "context"
    "log"
    "time"
﻿
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
    "go.mongodb.org/mongo-driver/mongo/writeconcern"
)
﻿
// 片集群：SRV 连接
func createClientWithSRV() (*mongo.Client, error) {
    uri := "mongodb+srv://mongouser:password@xxx.tencentcdb.com/admin?authSource=admin"
    return createClient(uri)
}
﻿
// 副本集：控制台默认连接串（包含所有节点地址）
func createClientWithReplicaSet() (*mongo.Client, error) {
    uri := "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.101:27017,10.0.0.102:27017/admin" +
           "?authSource=admin&replicaSet=cmgo-xxxxxxxx"
    return createClient(uri)
}
﻿
// 分片集群：LB 地址连接（绝大多数场景适用）
func createClientWithLB() (*mongo.Client, error) {
    uri := "mongodb://mongouser:password@10.0.0.100:27017/admin?authSource=admin"
    return createClient(uri)
}
﻿
// 分片集群：连接所有 Mongos
func createClientWithAllMongos() (*mongo.Client, error) {
    uri := "mongodb://mongouser:password@10.0.0.100:27017,10.0.0.100:27018,10.0.0.100:27019/admin" +
           "?authSource=admin"
    return createClient(uri)
}
﻿
func createClient(uri string) (*mongo.Client, error) {
    clientOpts := options.Client().ApplyURI(uri).
        // 连接池配置
        SetMaxPoolSize(150).
        SetMinPoolSize(10).
        SetMaxConnIdleTime(120 * time.Second).
        
        // 超时配置
        SetConnectTimeout(10 * time.Second).
        SetServerSelectionTimeout(5 * time.Second).
        
        // 可靠性配置
        SetRetryWrites(true).
        SetRetryReads(true).
        SetWriteConcern(writeconcern.Majority()).
        SetReadPreference(readpref.SecondaryPreferred())
﻿
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
﻿
    client, err := mongo.Connect(ctx, clientOpts)
    if err != nil {
        return nil, err
    }
﻿
    // 连接健康检查
    if err := client.Ping(ctx, readpref.Primary()); err != nil {
        return nil, err
    }
    log.Println("MongoDB 连接正常")
﻿
    return client, nil
}
SDK 连接配置

本页目录：

Python（pymongo）

Java（MongoDB Driver）

Node.js（MongoDB Driver）

Go（mongo-driver）
