---
url: /mongo/Mongo-config.md
---
# 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 |

***

## 注意事项

1. **URI vs 单独配置**: 推荐使用 `uri` 方式进行配置，如果同时使用了 `uri` 和单独的 `host/port/database` 配置，URI 优先级更高。

2. **密码安全**: 密码使用 `char[]` 类型而非 `String`，以便在使用后及时清除内存中的敏感信息。

3. **SSL 启用判断**: SSL 会在以下任一条件满足时启用：
   * `ssl.enabled = true`
   * `ssl.bundle` 有值

4. **UUID 表示**: 不同应用平台可能需要不同的 UUID 表示形式，确保与现有数据兼容。

5. **GridFS 数据库**: 如果 GridFS 未指定数据库，将使用主数据库。

6. **自动索引**: 生产环境建议关闭自动索引创建，通过迁移脚本管理索引。

***

## 相关类

* `org.springframework.boot.autoconfigure.mongo.MongoTemplate`
* `org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration`
* `org.springframework.boot.autoconfigure.mongo.ReactiveMongoAutoConfiguration`
* `com.mongodb.ConnectionString`
* `org.bson.UuidRepresentation`

***

*文档生成时间：2026-07-21*\
*Spring Boot 版本：3.5.16*