最近在搞一个内部数据采集项目，消息数据增长很快，MySQL单表已经有点扛不住了。团队里有人提议引入MongoDB，理由很直接：数据模型灵活、写入快、水平扩展方便。于是我开始调研怎么把MongoDB和手头的Spring Boot服务整合起来。整个流程走下来，踩了不少坑，从安装环境到依赖配置到运行调优，都有值得记一笔的地方。这篇文章就针对“MongoDB安装+Spring Boot整合”这个主题，把完整链路和实战细节写清楚，给正在选型或准备落地的同学一个参考。文中涉及的操作步骤和配置均来自我个人的实际测试环境，不同操作系统和版本会有细微差异，大家动手时注意对照一下。
1. 为什么在Spring Boot项目里选MongoDB：场景与选型思考
1.1 关系型数据库在部分业务场景下的不适感
先说个最直白的感受。现在的业务需求变化特别快，尤其是数据采集类、日志类、用户行为类项目，字段永远在变。今天记一个用户浏览记录，明天可能就要加设备指纹、网络环境、地理位置、扩展属性。用MySQL做这事，除非一开始就把预留字段设计好，不然每次都要改表结构，开发效率非常低。就算用了ALTER TABLE，一张千万级数据的大表频繁加字段，性能也会受影响。
MongoDB的文档模型天然就是为这种场景设计的。一条记录就是一个BSON文档，不同记录的字段可以不一致，同一个集合里既能存简单的键值对，也能存嵌套数组和子文档。新增字段只要在代码实体类里加属性就行，线上不需要执行任何DDL操作。这个“无模式”的好处，项目迭代越频繁体会越深。
但我也要泼一盆冷水：MongoDB并不是万能的。如果你的业务强依赖事务、需要复杂的多表关联查询，或者数据一致性要求极高，那还是老老实实用MySQL。MongoDB从4.0版本开始支持多文档事务，但事务性能远没有关系型数据库那么成熟，生产环境中多副本集事务依然需要谨慎使用。选型的关键不是看哪个数据库更流行，而是看你的数据模型和访问模式更匹配谁。
1.2 MongoDB在项目中的典型定位
我这次的项目里，MongoDB主要承接了三个职责：埋点日志的实时写入、用户扩展属性的存储、以及一些半结构化业务数据的查询。这三个场景有几个共同点——数据量大、字段结构不稳定、写入并发高、查询模式相对简单。放在过去，这类数据可能要拆成好几张表再加JSON字段，写起来别扭，查起来也麻烦。用MongoDB之后，整个数据模型就跟业务描述一一对应了，代码写起来很自然。
还有一个实际原因：Spring Boot对MongoDB的集成做得非常成熟。spring-boot-starter-data-mongodb封装了大部分底层连接管理和配置，实体映射、Repository接口、MongoTemplate这些工具开箱即用。对于已经熟悉Spring Data JPA的人来说，迁移成本很低，基本是换一套注解和接口就能上手。
1.3 选型前的环境评估
动手之前，建议先把下面的问题理清楚，不然装好了连不上，或者连上了跑不动，非常浪费时间：
- 服务部署在什么操作系统上，是Windows开发机还是Linux生产环境
- MongoDB版本选哪个，社区版还是企业版
- 需要单机部署还是副本集架构
- 是否有安全认证需求，是否允许内网其他机器访问
- Java和Spring Boot版本是多少，JDK是否满足要求
我这次开发机用的是Windows，生产环境是某Linux发行版，所以两个环境的安装步骤都重新跑了一遍。下面分别记录实际操作过程。
2. MongoDB安装实录：Windows和Linux两个环境的完整操作
2.1 Windows开发机的安装与目录规划
先在Windows上装一遍。MongoDB官方有两个安装通道：MSI安装包和ZIP压缩包。我个人的建议是优先用ZIP压缩包，不用MSI安装器。原因有两个：一是ZIP包可以精确控制安装目录，不会在系统盘C盘里乱塞东西；二是方便维护多版本，比如项目A用7.0，项目B用6.0，解压两份目录就行。
安装步骤如下：
- 从MongoDB官方下载页获取Windows ZIP包，选择7.0.x版本。
- 解压到自定义目录，比如
D:\mongodb。 - 在
D:\mongodb下新建两个目录：data\db用于存放数据文件，log用于存放日志。 - 打开命令行，进入解压后的bin目录，执行启动命令。
启动命令我建议先手写一个基础版本：
D:\mongodb\bin\mongod.exe --dbpath D:\mongodb\data\db --logpath D:\mongodb\log\mongod.log --logappend --bind_ip 127.0.0.1 --port 27017这条命令把数据目录、日志目录、绑定IP和端口都指定好了，前台运行模式，能直接在控制台看到启动日志。如果启动成功，控制台会输出Waiting for connections，然后就可以另开一个窗口连接测试了。
连接测试在7.0版本之后建议用mongosh，老版的mongoshell语法已经不够用了：
D:\mongodb\bin\mongosh.exe --host 127.0.0.1 --port 27017在shell里执行db.runCommand({ ping: 1 })，如果返回ok: 1，说明服务已经正常启动。
2.2 Windows服务注册与开机自启动
上面的前台启动方式只适合临时验证，关掉控制台MongoDB就停了。开发机如果每天都要开机启动数据库，建议注册成Windows服务。在MongoDB的bin目录下执行：
D:\mongodb\bin\mongod.exe --config D:\mongodb\mongod.conf --install这里需要先准备一个mongod.conf配置文件。我的配置是这样的：
storage: dbPath: D:\mongodb\data\db systemLog: destination: file path: D:\mongodb\log\mongod.log logAppend: true net: bindIp: 127.0.0.1 port: 27017注册好之后用net start MongoDB启动服务，以后开机就会自动运行。
2.3 Linux服务器上的安装与systemd托管
生产环境的Linux服务器安装就比Windows上更强调服务托管了。以RHEL系发行版为例，常规安装方式是通过包管理工具拉取官方仓库的RPM包：
- 先把MongoDB官方仓库添加进系统仓库列表。这一步需要的仓库内容，官方文档首页就能找到，注意选择和自己系统版本匹配的仓库配置。
- 添加完成后更新缓存，然后安装
mongodb-org这个元包，它会一并把服务端、Shell和相关工具都装上。 - 安装完成后不要急着启动，先检查配置文件
/etc/mongod.conf。
首轮启动前我一般会修改两个地方：bindIp从默认的127.0.0.1改成内网IP（如果生产环境需要被其他机器访问），以及确认dbPath指向的空间足够大的磁盘分区，默认目录是/var/lib/mongo。
然后启动服务并设置开机自启：
sudo systemctl daemon-reload sudo systemctl enable mongod sudo systemctl start mongod sudo systemctl status mongod看到active (running)状态后，再跑一遍连接测试：
mongosh --host 127.0.0.1 --port 27017 --eval "db.runCommand({ ping: 1 })"2.4 安装阶段最容易忽略的三件事
第一个是防火墙。Linux环境安装完MongoDB连不上，百分之八十是防火墙拦截了27017端口。开发机测没什么问题，生产环境一定要确认安全组和防火墙都放行了对应端口的入站规则。注意绑定IP如果是127.0.0.1，外部机器是无论如何都连不进来的。
第二个是data目录权限。用systemctl启动mongod时，服务默认以mongod用户运行。如果dbPath目录的所有者不对，服务会直接启动失败。在查看日志之前先确认目录权限，很多时候问题就出在这。用ls -ld /var/lib/mongo看看所有者是不是mongod用户，不是就调整一下。
第三个是SELinux。在有些强化过的Linux发行版上，如果启用了SELinux，mongod的端口监听可能被拦截。日志里会出现权限相关的报错，排错时别忽略这一层。
3. Spring Boot整合MongoDB：从依赖到第一条数据的完整链路
3.1 引入依赖并确认版本兼容关系
Spring Boot整合MongoDB共用的核心依赖是spring-boot-starter-data-mongodb。在pom.xml里加上：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-mongodb</artifactId> </dependency>这里有个版本兼容问题要提醒一下：Spring Boot 3.x版本要求JDK 17及以上，同时Spring Data MongoDB的版本也是跟Boot走的。我一开始没注意本机JDK还停留在8，结果项目直接启动失败，报了一堆模块相关的错误。建议在动手前先把JDK升级到17或21，然后确认MongoDB驱动的版本随Boot的BOM管理即可，不需要单独引入mongodb-driver-sync。
3.2 配置连接信息：推荐用URI方式
Spring Boot连接MongoDB有好几种写法，application.yml里可以用单独字段，也可以用连接串。我推荐用URI方式，尤其是以后要加用户名密码和连接参数时，一条字符串全搞定。
spring: data: mongodb: uri: mongodb://127.0.0.1:27017/mydb如果数据库开启了认证，URI需要带上账号信息：
spring: data: mongodb: uri: mongodb://admin:password@127.0.0.1:27017/mydb?authSource=admin注意authSource=admin这个参数。MongoDB的用户是建立在某个库下面的，认证时默认去当前库里找用户；如果账号是建在admin库里的，而连接的是mydb，就必须通过authSource指明认证库，不然会一直报认证失败。
用spring.data.mongodb.host和spring.data.mongodb.port这种配置方式也不是不行，但遇到连接串需要加额外参数（比如副本集名称、连接池大小、读写超时）时，可以组合成这套：想省事就直接用URI，可维护性高很多。
3.3 定义实体类和文档映射
配置好连接之后，先创建一个简单的实体类，测试核心链路是否通畅。以用户埋点数据为例：
@Data @Document("user_trace") public class UserTrace { @Id private String id; private String userId; private String eventType; private Integer eventValue; private LocalDateTime createTime; private Map<String, Object> extendInfo; }@Document注解指定集合名，等价于MySQL里的表名。@Id表示主键，Spring Data MongoDB会自动完成ObjectId和字符串之间的转换。这里特别说明一下：主键字段类型用String开发体验最好，序列化到前端时不会出现奇怪的ObjectId对象体。
extendInfo字段直接用一个Map接收，这在MongoDB里非常自然。任何未来的扩展字段都可以塞进这个Map，不用提前建表加列，数据模型就保持了灵活性，代码也不需要改结构。这就是文档型数据库最招人喜欢的地方。
3.4 编写Repository接口并落地一次查询
Spring Data MongoDB的Repository写法和Spring Data JPA几乎一样，定义接口继承MongoRepository，然后直接写方法名就能自动实现查询：
public interface UserTraceRepository extends MongoRepository<UserTrace, String> { List<UserTrace> findByUserId(String userId); List<UserTrace> findByEventTypeAndCreateTimeAfter(String eventType, LocalDateTime time); long countByEventType(String eventType); }服务层注入这个接口，调用save方法就能插入数据。第一次启动项目后插入一条记录，再到MongoDB shell里查一下，确认数据真的落库了。我实际跑通这条链路时，接下来许多复杂查询都基于这两个注解方法做增量，开发速度确实快。
3.5 用单元测试验证基础CRUD
整合是否成功不能只靠启动日志，最好写一个简单的测试用例来验证。项目里引入spring-boot-starter-test之后，写一个测试方法：
@SpringBootTest class UserTraceRepositoryTest { @Autowired private UserTraceRepository repository; @Test void testInsertAndQuery() { UserTrace trace = new UserTrace(); trace.setUserId("U10001"); trace.setEventType("click"); trace.setEventValue(2); trace.setCreateTime(LocalDateTime.now()); repository.save(trace); List<UserTrace> list = repository.findByUserId("U10001"); System.out.println(list.size()); } }跑通这个测试，说明从代码到数据库的完整链路都已经没问题了，可以进入实际业务开发。
4. Repository与MongoTemplate：常规CRUD的两种写法和适用边界
4.1 为什么还需要MongoTemplate
很多人最开始只用了Repository，觉得findByXXXX方法已经够用了。确实，单表简单查询完全没问题，但一旦遇到动态查询条件、聚合管道、分组统计这些场景，Repository就力不从心了。这个时候要用MongoTemplate来写灵活查询，它提供了接近原生驱动的操作能力，是复杂查询场景的主力。
我实际项目里的经验是：简单固定查询用Repository，复杂动态查询用MongoTemplate，两套工具配合使用，既享受了Spring Data的便利，又不失灵活性。
4.2 MongoTemplate下的条件构造与分页
举个例子，用户列表查询场景：前端会传多个不固定的筛选项，比如用户ID、事件类型、时间范围、扩展字段里的某个属性。用Repository的方法名定义法写这种动态条件会把方法名写成一大长串，可读性极差。这时用Query加Criteria构建条件就清晰多了：
@Autowired private MongoTemplate mongoTemplate; public Page<UserTrace> search(String userId, String eventType, LocalDateTime startTime, LocalDateTime endTime, int page, int size) { Query query = new Query(); Criteria criteria = new Criteria(); if (StringUtils.hasText(userId)) { criteria.and("userId").is(userId); } if (StringUtils.hasText(eventType)) { criteria.and("eventType").is(eventType); } if (startTime != null && endTime != null) { criteria.and("createTime").gte(startTime).lte(endTime); } query.addCriteria(criteria); long total = mongoTemplate.count(query, UserTrace.class); Pageable pageable = PageRequest.of(page, size); query.with(pageable); List<UserTrace> list = mongoTemplate.find(query, UserTrace.class); return new PageImpl<>(list, pageable, total); }这段代码的好处就是“条件按需拼接”，没有传的参数不会拼进查询条件里。每个分支的条件下，Criteria链式调用语义非常清晰。分页组装就顺手一起做了，注意先用count拿总数，再查当前页数据，避免返回结果的total永远是当前页条数。
4.3 更新场景中的坑：save会整体替换
用MongoRepository.save()实现更新会有个隐蔽坑：save底层逻辑是查出主键，如果存在就更新整个文档。也就是说，如果你只set了一个字段，其他字段又都没查出来，最终可能把完整文档替换成只有部分字段的内容。处理真正的局部更新，一定要用MongoTemplate的updateFirst或updateMulti加Update操作符。
Query query = new Query(Criteria.where("id").is(traceId)); Update update = new Update(); update.set("eventValue", 10); update.set("extendInfo.deviceType", "android"); mongoTemplate.updateFirst(query, update, UserTrace.class);Update里的set只更新指定字段，其他字段原样保留，而且支持点号路径操作嵌套字段，这是MongoDB更新文档的标准做法。
4.4 聚合查询的实用场景
除了条件查询，MongoTemplate对聚合操作的支持也很强。以统计每天不同事件的次数为例：
Aggregation aggregation = Aggregation.newAggregation( Aggregation.match(Criteria.where("createTime").gte(startTime)), Aggregation.group("eventType").count().as("count"), Aggregation.sort(Sort.by(Sort.Order.desc("count"))) ); AggregationResults<Map> results = mongoTemplate.aggregate(aggregation, "user_trace", Map.class);这里的Aggregation定义跟MongoDB的aggregate管道语法几乎一一对应。理解MongoDB聚合管道的关键是：管道是一系列处理步骤的有序组合，每一步接收上一步的结果并继续处理。match负责筛选，group负责分组计数，sort负责排序。跑一次聚合查询，再在业务里配合返回结果，比在Java内存里做数据聚合高效得多。
5. 整合路上最常见的4个坑：排查过程与解决方案
5.1 localhost连不上：IPv6解析与绑定地址问题
第一次用Spring Boot连接MongoDB时，我配置的是localhost:27017，启动正常，但查询一直报连接超时。查了一圈发现，服务端mongod在默认配置下绑定的是127.0.0.1，而某些环境里Java解析localhost会优先得到::1这个IPv6地址，两边一个4一个6，根本对不上，连接自然失败。这个问题在Windows开发机上特别容易出现，因为系统网络栈默认同时启用了IPv4和IPv6。
解决办法很简单：统一用127.0.0.1，别用localhost。配置MongoDB的连接串和绑定IP时都写死为127.0.0.1，避免DNS解析这层不确定性。如果你想让Spring Boot配置更灵活一点，可以把连接地址放到环境变量或配置中心里，不同环境用不同值。
5.2 认证机制导致的应用启动失败
我给生产环境开启访问控制后，Spring Boot服务启动时反复提示认证失败。排查发现两个问题：第一，用户创建时指定的roles里db字段没有和连接串里访问的库名对上；第二，连接串里没有加authSource=admin。MongoDB的认证机制要求客户端明确告诉服务器“我去哪个库验证身份”，authSource就是干这个的。
MongoDB创建用户的典型流程是：
use admin db.createUser({ user: "appUser", pwd: "yourPassword", roles: [{ role: "readWrite", db: "mydb" }] })连接串就要写成：
spring: data: mongodb: uri: mongodb://appUser:yourPassword@127.0.0.1:27017/mydb?authSource=admin这个坑的核心教训是：用户是挂在库下面的，认证也一定要写清认证库。
5.3 字段名大小写与@Field映射不一致
Spring Data MongoDB默认把实体字段名直接映射为文档字段名，Java开发习惯是驼峰命名，比如userId、createTime。如果数据库里的文档字段本来就用下划线风格（比如user_id），或者有些历史数据里字段名大小写不统一，查询条件就会失配，查不到数据。
解决方式是给实体字段加@Field注解，显式指定文档中的实际字段名：
@Field("user_id") private String userId;这个坑容易发生在团队协作场景：有人用Robo 3T或代码脚本直接插入文档时习惯写user_id，而Java代码里用的是userId，两边各写各的，结果数据正确存在库里，但应用里怎么都查不出来。花几分钟把字段映射梳理清楚，能省很多排错时间。
5.4 日期时区问题：LocalDateTime与UTC的错位
MongoDB驱动在存储日期类型时，默认按UTC时间存储。如果你插入的是本地时间，而读取时没做时区转换，那取出来的时间会比实际早8个小时（东八区场景）。我在日志数据时间统计时曾发现每个小时的记录都少8小时的数据，排查后才意识到是时区转换问题。
比较好的做法是在配置连接串时增加serverTimezone参数，同时统一整个项目的时间处理策略：
spring: data: mongodb: uri: mongodb://127.0.0.1:27017/mydb?serverTimezone=Asia/Shanghai但更稳妥的做法是把时间统一按UTC存储，展示层再转换成本地时区。业务逻辑中所有和时间相关的比较、分组、排序都基于UTC，不会因为服务器部署地区不同而产生偏差。这个原则对任何数据库都适用，MongoDB里尤其注意。
6. 写入生产前的最后几步：索引、事务与连接池调优
6.1 索引规划：不是所有查询都能走全表扫描
MongoDB单机读能力虽然不弱，但索引设计不到位，数据量一上来照样慢。开发阶段通常能快速跑通的接口，到十万、百万级数据后如果还扫描全集合，响应时间会指数级上升。我建议在代码实体类上直接声明索引，这样Spring Data启动时能自动同步索引结构：
@Data @Document("user_trace") @CompoundIndex(def = "{'userId': 1, 'createTime': -1}") public class UserTrace { ... }@CompoundIndex声明了一个复合索引：按用户ID等值查询，再按创建时间倒序排序，这是最典型的日志查询场景索引。等值字段放前面，排序字段放后面，这是索引设计的基本规则。
如果查询条件经常变化，可以先用mongo shell手动测试索引命中情况：
db.user_trace.createIndex({ userId: 1, createTime: -1 }) db.user_trace.find({ userId: "U10001" }).sort({ createTime: -1 }).explain("executionStats")explain返回结果里的winningPlan可以确认是否走了IXSCAN而不是COLLSCAN。这一步在生产环境至关重要，等数据多了再补索引，代价是巨大的。
6.2 事务使用的条件和限制
MongoDB从4.0开始支持多文档事务，但有个前置条件：必须是副本集架构，单机部署模式下事务会直接报错。副本集模式下，Spring Boot使用事务很简单，在Service方法上加@Transactional即可：
@Transactional public void processBatch(List<String> ids) { // 先更新A集合 // 再更新B集合 // 要么都成功，要么都失败 }实际使用前想明白一件事：事务会显著增加写入延迟，因为需要多数派节点确认。MongoDB的强项定位并不是高频事务场景，如果一个业务操作涉及多个文档的原子更新，先考虑能否用嵌入子文档的方式全局打包，再考虑事务。毕竟把需要原子化的数据塞进同一个文档，才是文档数据库最自然的使用方式。
6.3 连接池参数与性能观察
Spring Boot的MongoDB自动配置默认会维护一个连接池，但默认参数不一定适合所有业务。如果并发量高，合理调大连接池上限能明显降低等待时间。通过在URI里拼接连接池参数，不用额外写配置类：
spring: data: mongodb: uri: mongodb://127.0.0.1:27017/mydb?maxPoolSize=50&minPoolSize=5&maxIdleTimeMS=60000&connectTimeoutMS=5000&serverSelectionTimeoutMS=5000简单说明一下这些参数的实际意义：maxPoolSize是到MongoDB的最大并发连接数，业务线程多但连接池小于并发数时，多余的请求会排队等待；minPoolSize是维持的最小连接数，避免空闲时池被清空又频繁重建；maxIdleTimeMS控制空闲连接的回收时间，防止被服务端断开后仍沿用失效连接。调优没有银弹，建议先监控后调整，观察系统压测时的连接耗时和等待数再做增减。
6.4 上线前的基本检查清单
结合这次整合的完整经历，整理一份上线前检查清单，算是个人的经验习惯：
- 确认数据库开启了访问控制，且连接串里的认证信息权限最小化，只用业务库的
readWrite角色，不要用root - 确认
bindIp没有暴露到公网，生产环境一律使用内网IP，配合防火墙安全组做双保险 - 确认服务端口在网络层面可通，但外部无法直接访问
- 确认所有频繁查询的字段都已经有对应索引
- 确认时间字段存储策略全项目统一
- 确认MongoDB的日志路径和
dbPath磁盘空间充足，MongoDB的journal日志也占空间，磁盘耗尽会导致进程强制退出
最后再分享一个小细节：MongoDB在Spring Boot项目里一旦形成了稳定的数据访问层，后续接新的业务场景非常快，很多“字段说变就变”的对接双方都很受益。我第一次踩完连接认证的坑之后，后续所有测试环境都统一用URI带authSource的方式，再也没在连不上这件事上浪费时间。工具本身不复杂，复杂的往往是把一个细节放到另一个细节的坑里，逐个击破就好了。
