Spring Boot 3.5 MongoDB 配置大全

概述

本文档整理了 org.springframework.boot.autoconfigure.mongo.MongoProperties 类的完整配置信息。该类使用 @ConfigurationProperties("spring.data.mongodb") 注解，所有配置项均以 spring.data.mongodb 为前缀。

版本: Spring Boot 3.5.16
依赖: org.springframework.boot:spring-boot-autoconfigure:3.5.16

基础连接配置

配置属性	类型	默认值	说明
`spring.data.mongodb.protocol`	String	`mongodb`	MongoDB 协议类型
`spring.data.mongodb.host`	String	-	MongoDB 主机地址
`spring.data.mongodb.port`	Integer	`27017`	MongoDB 端口号
`spring.data.mongodb.database`	String	-	默认数据库名称
`spring.data.mongodb.uri`	String	`mongodb://localhost/test`	MongoDB 连接 URI（推荐方式）

URI 格式示例

properties

# 基本连接
spring.data.mongodb.uri=mongodb://localhost:27017

# 带认证
spring.data.mongodb.uri=mongodb://username:password@localhost:27017/mydb

# 副本集
spring.data.mongodb.uri=mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=myReplicaSet

# 分片集群
spring.data.mongodb.uri=mongodb://host1:27017,host2:27017,host3:27017/mydb?mongos=true

认证配置

配置属性	类型	默认值	说明
`spring.data.mongodb.authentication-database`	String	-	认证数据库名称（通常是 `admin`）
`spring.data.mongodb.username`	String	-	用户名
`spring.data.mongodb.password`	char[]	-	密码（建议使用 char 数组以保护敏感信息）

认证配置示例

properties

spring.data.mongodb.username=myuser
spring.data.mongodb.password=mypassword
spring.data.mongodb.authentication-database=admin

副本集配置

配置属性	类型	默认值	说明
`spring.data.mongodb.replica-set-name`	String	-	副本集名称

副本集配置示例

properties

spring.data.mongodb.replica-set-name=myReplicaSet

或者在 URI 中指定：

properties

spring.data.mongodb.uri=mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=myReplicaSet

多节点/额外主机配置

配置属性	类型	默认值	说明
`spring.data.mongodb.additional-hosts`	List	-	额外的 MongoDB 主机列表

多主机配置示例

yaml

spring:
  data:
    mongodb:
      additional-hosts:
        - host: mongo1
          port: 27017
        - host: mongo2
          port: 27017

GridFS 配置

GridFS 用于存储大文件，通过 MongoProperties.Gridfs 内部类进行管理。

配置属性	类型	默认值	说明
`spring.data.mongodb.gridfs.database`	String	-	GridFS 专属数据库（如果未指定则使用主数据库）
`spring.data.mongodb.gridfs.bucket`	String	-	Bucket 名称（GridFS 的命名空间）

GridFS 配置示例

yaml

spring:
  data:
    mongodb:
      gridfs:
        database: mygridfsdb
        bucket: myfiles

Bson 字段命名策略

配置属性	类型	默认值	说明
`spring.data.mongodb.field-naming-strategy`	Class	-	自定义 BsonFieldNamingStrategy 实现类

字段命名策略示例

yaml

spring:
  data:
    mongodb:
      field-naming-strategy: com.example.CustomFieldNamingStrategy

UUID 表示形式配置

配置属性	类型	默认值	说明
`spring.data.mongodb.uuid-representation`	UuidRepresentation	`JAVA_LEGACY`	UUID 的 BSON 表示形式

UuidRepresentation 枚举值

java

public enum UuidRepresentation {
    JAVA_LEGACY,      // Java Driver 原始格式（默认）
    STANDARD,         // RFC 4122 标准格式
    JAVA_OLD,         // 旧的 Java Driver 格式
    CSHARP_LEGACY     // .NET/C# 旧版格式
}

UUID 表示形式配置示例

yaml

spring:
  data:
    mongodb:
      uuid-representation: STANDARD

SSL/TLS 配置

SSL 配置通过 MongoProperties.Ssl 内部类进行管理。

配置属性	类型	默认值	说明
`spring.data.mongodb.ssl.enabled`	Boolean	-	是否启用 SSL 连接
`spring.data.mongodb.ssl.bundle`	String	-	SSL bundle 名称（用于配置 TLS）

SSL 配置示例

启用 SSL

properties

spring.data.mongodb.ssl.enabled=true

使用 SSL Bundle

properties

spring.data.mongodb.ssl.bundle=my-ssl-bundle

判断逻辑

SSL 启用的判断条件：enabled != null || bundle != null

自动索引创建配置

配置属性	类型	默认值	说明
`spring.data.mongodb.auto-index-creation`	Boolean	-	是否自动创建索引

自动索引配置示例

yaml

spring:
  data:
    mongodb:
      auto-index-creation: true

YAML 配置示例

完整配置示例

yaml

spring:
  data:
    mongodb:
      # 连接 URI（推荐方式）
      uri: mongodb://username:password@localhost:27017/mydatabase?authSource=admin
      
      # 或分开配置
      protocol: mongodb
      host: localhost
      port: 27017
      database: mydatabase
      
      # 认证配置
      username: myuser
      password: mypassword
      authentication-database: admin
      
      # 副本集配置
      replica-set-name: myReplicaSet
      
      # GridFS 配置
      gridfs:
        database: gridfsdb
        bucket: uploads
      
      # UUID 表示形式
      uuid-representation: STANDARD
      
      # SSL 配置
      ssl:
        enabled: true
      
      # 自动索引创建
      auto-index-creation: true

开发环境配置示例

yaml

spring:
  profiles:
    active: dev
  
  data:
    mongodb:
      uri: mongodb://localhost:27017/myapp-dev
      auto-index-creation: true

生产环境配置示例

yaml

spring:
  profiles:
    active: prod
  
  data:
    mongodb:
      uri: mongodb://mongo1:27017,mongo2:27017,mongo3:27017/myapp-prod?replicaSet=rs0&authSource=admin&ssl=true
      gridfs:
        bucket: files
      uuid-representation: STANDARD
      auto-index-creation: false

properties 配置示例

properties

# 基本连接
spring.data.mongodb.uri=mongodb://localhost:27017/mydb

# 或分别配置
spring.data.mongodb.host=localhost
spring.data.mongodb.port=27017
spring.data.mongodb.database=mydb
spring.data.mongodb.username=myuser
spring.data.mongodb.password=mypassword
spring.data.mongodb.authentication-database=admin

# 高级配置
spring.data.mongodb.replica-set-name=rs0
spring.data.mongodb.uuid-representation=STANDARD
spring.data.mongodb.auto-index-creation=true

# SSL 配置
spring.data.mongodb.ssl.enabled=true

# GridFS 配置
spring.data.mongodb.gridfs.database=gridfsdb
spring.data.mongodb.gridfs.bucket=uploads

Java Config 配置示例

java

@Configuration
public class MongoConfig {
    
    @Bean
    public MongoClientSettings mongoClientSettings() {
        MongoCredential credential = MongoCredential.createCredential(
            "myuser", 
            "admin", 
            "mypassword".toCharArray()
        );
        
        return MongoClientSettings.builder()
            .applyConnectionString(new ConnectionString(
                "mongodb://localhost:27017/mydb"
            ))
            .credential(credential)
            .applyToClusterSettings(builder -> 
                builder.hosts(List.of(new ServerAddress("localhost", 27017)))
            )
            .build();
    }
    
    @Bean
    public MongoDatabaseFactory mongoDatabaseFactory() throws Exception {
        SimpleMongoClientDatabaseFactory factory = new SimpleMongoClientDatabaseFactory(
            mongoClientSettings(), 
            "mydb"
        );
        return factory;
    }
}

核心常量

常量	值	说明
`DEFAULT_PORT`	`27017`	默认 MongoDB 端口
`DEFAULT_URI`	`"mongodb://localhost/test"`	默认连接 URI

注意事项

URI vs 单独配置: 推荐使用 uri 方式进行配置，如果同时使用了 uri 和单独的 host/port/database 配置，URI 优先级更高。
密码安全: 密码使用 char[] 类型而非 String，以便在使用后及时清除内存中的敏感信息。
SSL 启用判断: SSL 会在以下任一条件满足时启用：
- ssl.enabled = true
- ssl.bundle 有值
UUID 表示: 不同应用平台可能需要不同的 UUID 表示形式，确保与现有数据兼容。
GridFS 数据库: 如果 GridFS 未指定数据库，将使用主数据库。
自动索引: 生产环境建议关闭自动索引创建，通过迁移脚本管理索引。

Spring Boot 3.5 MongoDB 配置大全

概述

基础连接配置

URI 格式示例

认证配置

认证配置示例

副本集配置

副本集配置示例

多节点/额外主机配置

多主机配置示例

GridFS 配置

GridFS 配置示例

Bson 字段命名策略

字段命名策略示例

UUID 表示形式配置

UuidRepresentation 枚举值

UUID 表示形式配置示例

SSL/TLS 配置

SSL 配置示例

启用 SSL

使用 SSL Bundle

判断逻辑

自动索引创建配置

自动索引配置示例

YAML 配置示例

完整配置示例

开发环境配置示例

生产环境配置示例

properties 配置示例

Java Config 配置示例

核心常量

注意事项

相关类