上个月帮一个做设备巡检系统的朋友翻代码看到他还在用 SpringBoot 拼 JDBC 手写 JSON 字符串往库里塞一条巡检记录十几个可变字段表结构改了三次每次都要停机加列。这种场景其实就是 MongoDB 的主场——文档模型天然适配字段不固定、嵌套层级深、读多写少的数据而 SpringBoot 生态对它的封装又足够成熟spring-boot-starter-data-mongodb一个依赖拉进来配置写三行MongoTemplate直接用整合成本低到可以忽略。这篇就围绕 SpringBoot 整合 MongoDB 这条主线把选型判断、依赖版本对齐、文档映射、连接池估算、批量写入、聚合与事务边界这些实际会碰到的东西一次讲透。适合刚接触文档数据库的后端同学也适合已经能跑通 Demo、但一到生产就出各种连接超时和类型错乱问题的老手——下面这些坑基本都是我或身边同行真踩过的。1. 动手之前先把选型逻辑捋顺1.1 一个真实需求场景的拆解先说我经手过的一个典型例子。某公司做工业设备巡检每台设备每次巡检产生的数据结构差异极大温度传感器上报的是{deviceId, ts, value}而人工巡检单里可能是{deviceId, ts, inspector, items:[{name, result, remark}], photos:[...]}甚至同一个集合里不同型号设备的字段集合能差出一半。最初用关系库方案是主表 若干张明细表 一个ext_json大字段兜底结果查询时既要 join 又要解析 JSON索引也建不利索。换成 MongoDB 之后整条巡检记录就是一个文档嵌套的items数组直接存在文档里一次查询把整条记录捞出来前端渲染不用再做二次拼装。这个转变的关键不在于用了 NoSQL 显得先进而在于数据本身的形状和存储的形状对上了。文档数据库的核心价值就在这里聚合根内部的从属数据天然就该跟着主文档一起读写。不过话说回来如果当时的需求是按巡检项跨设备做统计报表、还要和工单系统做多表关联那我肯定还是建议留在关系库。选型这件事最忌讳的就是拿一个新玩具硬套所有场景后面几节我会把判断标准写得更具体一些。1.2 SpringBoot 整合 MongoDB 适合与不适合的判断标准我一般用三个问题快速判断数据是不是以聚合根为单位整体读写比如订单 订单明细、文章 评论列表、设备 巡检项。是就适合如果明细需要独立被其他业务高频引用和关联就要谨慎。字段结构会不会频繁变化硬件上报、第三方回调、运营配置这类数据字段集合半年变一次很正常文档模型不用改表结构加个字段就完事。反过来如果是财务对账这种字段极其稳定、且强依赖外键约束的场景关系库更省心。读写比例和一致性要求如何读多写少、允许最终一致的场景内容、日志、画像、配置很合适。强事务、跨文档多写、需要复杂 join 的场景要么用副本集事务硬扛要么干脆别用。还有一个容易被忽略的点运维能力。MongoDB 的分片、副本集、备份恢复和传统关系库的运维习惯差别不小。团队里没人懂出了问题只能干瞪眼那还不如老老实实加两张表。技术选型从来不只是代码层面的事。1.3 版本兼容矩阵先对齐再写代码整合踩的第一个坑往往不是代码写错而是版本没对齐。Spring Data MongoDB 的版本跟 Spring Boot 绑定而底层又依赖mongodb-driver-sync三者错位就会出现各种诡异的NoSuchMethodError。下面这张表是我整理的常见组合照着选基本不会出问题Spring Boot 版本Spring Data MongoDBMongoDB Java Driver服务端建议版本2.7.x3.4.x4.6 ~ 4.94.4 / 5.0 / 6.03.0.x ~ 3.1.x4.0.x ~ 4.1.x4.9 ~ 4.115.0 / 6.03.2.x ~ 3.3.x4.2.x ~ 4.3.x4.11 / 5.06.0 / 7.03.4.x 及以上4.4.x5.27.0实际操作中最稳妥的做法是不要手动指定mongodb-driver-sync的版本交给 Spring Boot 的 BOM 管理。只有当服务端版本特别老比如还在 4.0或者特别新、驱动需要显式升级时才在dependencyManagement里覆盖。我见过有同事为了用上新特性手动把 driver 升到 5.x结果 Boot 2.7 的自动配置类里调用的方法签名变了启动直接报错排查了小半天。注意如果服务端是 MongoDB 4.0 以下且业务需要事务那就别折腾了事务要求副本集且版本 4.0单机模式怎么配都开不起来。2. 工程骨架依赖、配置与连接池2.1 起步依赖引入与排除项依赖这块非常简单一行搞定dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-mongodb/artifactId /dependency如果项目用的是 Maven 多模块注意别在同一工程里既引spring-boot-starter-data-mongodb又引mongodb-driver-legacy或者旧版mongo-java-driver这两个包同时存在时MongoClient的类会冲突启动报ClassNotFoundException或者更隐蔽的LinkageError。另外有个常被问到的问题要不要用响应式的spring-boot-starter-data-mongodb-reactive我的判断很直接——如果整条调用链已经是 WebFlux Reactor那就用响应式如果是传统 MVC别为了高性能硬上。响应式的收益在 IO 密集、高并发的场景才明显普通 CRUD 业务里Mono/Flux带来的调试成本和团队学习成本往往大于收益。我之前见过一个项目一半接口同步一半响应式最后block()到处飞反而把线程池堵死了。2.2 application.yml 分环境配置写法配置有两种主流写法选一种坚持用别混。写法一拆开写推荐参数可控性更好spring: data: mongodb: host: 127.0.0.1 port: 27017 database: inspection username: app_user password: ${MONGO_PWD} authentication-database: admin auto-index-creation: true uri: # 留空走上面的分项配置写法二URI 一把梭spring: data: mongodb: uri: mongodb://app_user:${MONGO_PWD}127.0.0.1:27017/inspection?authSourceadminmaxPoolSize80minPoolSize10maxIdleTimeMS60000两种写法的差别在于URI 方式对连接池参数、读写关注readConcern/writeConcern、超时时间的控制更细因为这些参数是 URI 的 query 部分天然支持的分项配置方式更直观但部分参数需要额外定义 Bean 才能覆盖。我个人的习惯是开发环境用分项配置改起来方便生产和预发统一用 URI密码走环境变量注入绝不写死在配置文件里。这里提一句authentication-database如果你的用户建在admin库但业务库是另一个这个参数不写会直接认证失败——这是新手最容易卡住的地方之一。2.3 连接池参数怎么估算才不翻车连接池是生产事故的高发区。默认maxPoolSize是 100听着够用但如果一个应用有多个实例、每个实例都开 100服务端连接数瞬间就上去了MongoDB 单机默认连接上限大概在两万左右加上内部连接很容易打出connection refused。给一个可以直接套用的估算公式所需连接数 ≈ (峰值 QPS × 单次操作平均耗时ms) / 1000 × 冗余系数(1.5 ~ 2)举个具体例子某个查询接口峰值 QPS 400单次find平均耗时 6ms那么并发占用约400 × 6 / 1000 2.4个连接乘 1.5 冗余理论上 4 个就够。但实际业务里存在慢查询、批量写入、聚合统计这些耗时长的操作会长时间占用连接所以我把maxPoolSize设成 50minPoolSize设 10maxIdleTimeMS设 60000maxLifeTimeMS设 1800000。再看整体应用部署 4 个实例4 × 50 200个连接加上运维工具、备份任务服务端压力完全可控。对比之前有个团队直接用默认 1008 个实例就是 800 连接一到高峰期就开始报超时把maxPoolSize降到 40 之后问题消失。参数建议值说明maxPoolSize30 ~ 80按实例数和 QPS 估算别用默认 100minPoolSize5 ~ 20保持一定预热连接避免突发建连maxIdleTimeMS60000空闲连接回收时间maxLifeTimeMS1800000连接最长存活时间防止服务端侧断连connectTimeoutMS5000建连超时别设太大serverSelectionTimeoutMS3000 ~ 5000选节点超时直接影响故障响应速度socketTimeoutMS20000 ~ 60000读写超时按最慢查询的 2 倍设waitQueueTimeoutMS5000拿不到连接时的等待上限防止线程无限堆积提示waitQueueTimeoutMS这个参数特别值得设。不设的话池子满了之后请求会无限期等待线程池被慢慢耗干最后整个服务假死日志里却什么明显错误都没有——这种故障排查起来极其痛苦。3. 文档映射把集合结构翻译成Java类3.1 Document 注解与字段命名策略实体类是最先要落地的。一个标准的映射类长这样import lombok.Data; import org.springframework.data.annotation.Id; import org.springframework.data.mongodb.core.mapping.Document; import org.springframework.data.mongodb.core.mapping.Field; import java.time.Instant; import java.util.List; Data Document(collection inspection_record) public class InspectionRecord { Id private String id; Field(device_id) private String deviceId; private String inspector; private Instant inspectTime; private ListInspectionItem items; private Integer status; }几个细节值得展开说。第一Id对应的字段类型建议用StringMongoDB 的_id本质是ObjectId但驱动会自动做转换用String在前后端传输时最省事如果你确实需要按ObjectId的时间戳做排序那就在插入后取id做一次转换或者干脆额外存一个Instant字段不要试图在_id上做业务逻辑。第二Field的作用是把 Java 的驼峰命名映射成库里的下划线命名。不加也能跑字段名就变成驼峰但这样和已有数据的字段风格不一致后续用命令行工具查数据时会很难受。这里有个更省事的做法——在配置里全局指定命名策略spring: data: mongodb: field-naming-strategy: org.springframework.data.mapping.model.SnakeCaseFieldNamingStrategy配上之后所有驼峰字段自动转下划线实体类里就不用一个一个加Field了。不过这属于一次性决定中途切换会导致已有数据读不出来上线前一定要定死。第三Instant和LocalDateTime的选择。我强烈建议用Instant理由在 5.2 节详细说。3.2 嵌套对象、数组与Map类型的落库形态嵌套是文档数据库的核心优势但写法上有讲究。看这个InspectionItemData public class InspectionItem { private String name; private String result; private String remark; private ListString photoUrls; }落库之后就是一个子文档数组。这里要注意两点数组内的子文档可以单独被索引和查询用items.name这样的路径但不能单独更新数组内某个元素的单个字段——你要么用$set配合位置操作符改整个元素要么用$push/$pull做增删。这一点和关系库的明细表按主键更新思维完全不同设计时要想清楚更新模式。还有一个常见需求是动态字段比如不同设备型号有不同指标。这时候可以用MapString, Objectprivate MapString, Object metrics;落库就是{metrics: {temp: 36.5, vibration: 0.12}}灵活是灵活但代价是无法用 Spring Data 的派生查询方法直接查只能走MongoTemplate手写 Criteria而且字段类型不受约束容易出现同一个 key 一会儿是数字一会儿是字符串的情况。我的经验是能用固定字段就用固定字段Map只在真正不可预知的场景用并且约定好 value 只允许String/Number/Boolean三种基础类型。3.3 索引声明与自动创建开关索引不建查询就是全表扫数据量一过百万直接卡死。Spring Data 提供了注解声明方式Document(collection inspection_record) CompoundIndex(name idx_device_time, def {device_id: 1, inspect_time: -1}) public class InspectionRecord { // ... Indexed private Integer status; }这里有个大坑从 Spring Data MongoDB 3.0 开始自动建索引默认关闭了你光加注解不管用必须在配置里显式打开spring: data: mongodb: auto-index-creation: true打开之后应用启动时会扫描注解并创建索引已存在且定义一致则跳过。但生产环境我通常建议关掉自动创建改用脚本或迁移工具统一管理索引。原因很实际自动创建在多实例同时启动时可能产生并发冲突更麻烦的是如果索引定义改了旧索引不会自动删除会留下一个僵尸索引占着写入性能你还得手工去 drop。索引是数据库层面的资产就该像表结构一样纳入版本管理。复合索引的字段顺序也有讲究{device_id: 1, inspect_time: -1}能支持按设备查 按时间倒序的查询但如果业务里更多是按时间范围 按状态过滤那索引就该建成{status: 1, inspect_time: -1}。这条原则跟关系库完全一致等值条件在前范围/排序条件在后。4. 数据访问实操MongoTemplate 与 Repository 两条路4.1 MongoTemplate 的增删改查标准写法Spring Data 给了两套 APIMongoTemplate和MongoRepository。我的建议是两者都用但分工明确——简单 CRUD 走 Repository复杂查询、聚合、批量操作走 Template。MongoTemplate的基本用法Service RequiredArgsConstructor public class InspectionService { private final MongoTemplate mongoTemplate; // 插入返回带 id 的对象 public InspectionRecord save(InspectionRecord record) { return mongoTemplate.insert(record); } // 条件查询 排序 限制条数 public ListInspectionRecord recent(String deviceId, int limit) { Query query new Query( Criteria.where(device_id).is(deviceId) .and(inspect_time).gte(Instant.now().minusSeconds(86400)) ).with(Sort.by(Sort.Direction.DESC, inspect_time)) .limit(limit); return mongoTemplate.find(query, InspectionRecord.class); } // 局部更新只改指定字段 public void updateStatus(String id, Integer status) { Query query new Query(Criteria.where(_id).is(id)); Update update new Update() .set(status, status) .currentDate(update_time); mongoTemplate.updateFirst(query, update, InspectionRecord.class); } }几个实操要点insert和save的区别在于insert遇到已存在的_id会抛DuplicateKeyExceptionsave则是 upsert 语义有 id 就整体替换。在需要防止重复插入的场景比如幂等消费消息用insert配合唯一索引更安全。updateFirst只更新第一条updateMulti更新所有匹配项upsert系列方法在无匹配时插入。别用错。Query对象是可以复用的但limit、skip、with会修改原对象如果多处复用同一个 Query记得Query.query(criteria)重新构造不然会踩查询条件莫名其妙被改的坑。这个坑我调了两小时才定位到。4.2 Repository 派生查询与方法命名规则仓库接口的写法非常省心public interface InspectionRecordRepository extends MongoRepositoryInspectionRecord, String { ListInspectionRecord findByDeviceIdAndInspectTimeAfter( String deviceId, Instant time); PageInspectionRecord findByStatus(Integer status, Pageable pageable); long deleteByDeviceId(String deviceId); boolean existsByDeviceIdAndStatus(String deviceId, Integer status); }方法名解析规则和 JPA 基本一致And/Or/GreaterThan/In/Regex这些都能用。但有两个坑必须提坑一字段名映射不一致。如果实体上加了Field(device_id)findByDeviceId是能正确识别的因为 Spring Data 会做属性到字段的映射但如果你手写Query里面必须写库里真实的字段名device_id写驼峰会查不到数据。坑二deleteBy会先查后删。派生删除方法是查询出所有匹配文档 → 逐个删除数据量大时性能极差而且返回的计数是删除条数。批量删除请用mongoTemplate.remove(query, Class)一次调用就完事。还有一点MongoRepository和MongoTemplate混用时事务不会自动传递除非配了MongoTransactionManager这点在第 6 节细说。4.3 分页、排序与字段投影分页用PageablePageable pageable PageRequest.of(0, 20, Sort.by(Sort.Direction.DESC, inspect_time)); PageInspectionRecord page repository.findByStatus(1, pageable);看起来很美但要注意**Page会额外执行一次count查询**。如果集合里有几百万文档每次翻页都 count 一遍成本极高。有两种应对方式一是改用Slice只查是否还有下一页不查总数二是前端改成游标分页用上一页最后一条的时间戳作为inspect_time lastTs的条件性能最好。字段投影是另一个实用技巧。列表页往往只需要几个字段没必要把带 photos 数组的完整文档拉回来Query query new Query(Criteria.where(status).is(1)) .with(Sort.by(Sort.Direction.DESC, inspect_time)) .limit(20) .fields().include(device_id, inspector, inspect_time, status); ListInspectionRecord list mongoTemplate.find(query, InspectionRecord.class);投影能显著减少网络传输量和反序列化开销列表接口响应时间从 200ms 降到 60ms 是常有的事。4.4 批量写入BulkOperations 的正确用法批量场景千万别在 for 循环里一条一条 insert一次网络往返就是一次开销几千条能把接口拖到超时。正确做法是BulkOperationspublic void batchSave(ListInspectionRecord list) { if (CollectionUtils.isEmpty(list)) { return; } int batchSize 1000; for (int i 0; i list.size(); i batchSize) { ListInspectionRecord sub list.subList(i, Math.min(i batchSize, list.size())); BulkOperations ops mongoTemplate.bulkOps( BulkOperations.BulkMode.UNORDERED, InspectionRecord.class); ops.insert(sub); ops.execute(); } }三个关键点批次大小控制在 500 ~ 1000 条太大容易触发 16MB 的文档大小限制或者驱动内部缓冲区溢出用UNORDERED模式让服务端并行执行单条失败不影响其他条分批执行而不是一次性塞方便中途记录进度和失败重试。实测数据在本地环境逐条插入 5000 条记录耗时约 12 秒改成 1000 条一批的UNORDERED批量后降到 800 毫秒左右。数量级上的差异别不当回事。5. 踩坑实录与问题速查5.1 连接、超时与认证类故障这类问题占了实际故障的七成以上整理成表方便对照现象大概率原因处理方式启动报Authentication failed用户建在 admin 库但没配authSourceURI 加authSourceadmin偶发Connection refused服务端连接数打满降maxPoolSize核对实例总数请求长时间挂起无响应池子耗尽且没设waitQueueTimeoutMS补上该参数加监控告警No server chosen/ 超时 30s节点故障但serverSelectionTimeoutMS太大调到 3000~5000ms 快速失败隔夜后首次请求超时空闲连接被中间设备断开设maxLifeTimeMS小于中间设备空闲阈值批量写入报 16MB 超限单次 bulk 数据过大缩小批次或拆分文档提示那个隔夜超时的问题特别隐蔽——白天一切正常第二天早上第一批请求必然超时之后又好了。本质是长时间空闲的连接被网络中间层静默断开而客户端还以为是活的。设maxLifeTimeMS让连接主动轮换就能绕过去。5.2 日期时区与数值类型的隐性偏差日期这块我吃过一次大亏。早期实体类用了LocalDateTime本地开发一切正常部署到服务器UTC 时区之后页面上的时间整整差了 8 小时。原因是驱动把LocalDateTime当作无时区的本地时间序列化成Date服务端按 UTC 存读回来再按 UTC 解释中间就丢了偏移。结论很干脆存时间一律用Instant需要展示时在接口层转成业务时区。如果历史数据已经用了LocalDateTime可以加一个转换器统一处理Bean public MongoCustomConversions customConversions() { return new MongoCustomConversions(Arrays.asList( new InstantToDateConverter(), new DateToInstantConverter() )); }数值类型也有坑。JSON 里1和1.0是不同的 BSON 类型int32 vs double如果你用MapString, Object存指标某个字段一会儿存整数一会儿存小数之后用Criteria.where(metrics.temp).is(36.5)查询就可能匹配不上。解决办法是在写入前统一做类型规整或者干脆定义为Double强转。5.3 _class 字段引发的序列化问题默认情况下Spring Data 会给每个文档加一个_class字段值是类的全限定名比如com.example.demo.entity.InspectionRecord。这个字段的作用是反序列化时能还原成具体类型但它有三个副作用占空间、暴露包结构、类名改了之后老数据读不出来。处理方式有两种。轻量的方式是加类型别名Document(collection inspection_record) TypeAlias(inspection) public class InspectionRecord { ... }这样_class就变成inspection短且稳定。另一种是直接在配置里关掉Bean public MongoTemplate mongoTemplate(MongoDatabaseFactory factory, MongoMappingContext context) { MappingMongoConverter converter new MappingMongoConverter(new DefaultDbRefResolver(factory), context); converter.setTypeMapper(new DefaultMongoTypeMapper(null)); // 不写 _class return new MongoTemplate(factory, converter); }关掉之后文档会干净很多但代价是不能再用父类/接口接收查询结果做多态反序列化必须明确指定具体类型。如果业务里没有多态存储的需求关掉是划算的几百万文档省下的空间和反序列化时间都不算小。5.4 性能问题速查表现象排查方向常用手段查询随数据量线性变慢缺少索引explain(executionStats)看是否 COLLSCAN单条查询偶发 1s慢查询阻塞连接池开慢查询日志slowms设 100写入吞吐上不去索引过多 / 写关注过高精简索引评估writeConcern分页越翻越慢深分页 skip 成本高改游标分页或加范围条件内存占用持续上涨大结果集全量加载加 limit、用投影、流式读取聚合查询超时管道顺序不合理$match前置尽量在索引上过滤排查的第一步永远是explain。在 Java 里可以这样打Query query new Query(Criteria.where(device_id).is(D001)); Document explain mongoTemplate.getDb() .runCommand(new Document(explain, new Document(find, inspection_record) .append(filter, new Document(device_id, D001))) .append(verbosity, executionStats)); System.out.println(explain.toJson());看winningPlan.stage是不是COLLSCANtotalDocsExamined和nReturned的比值是多少。比值接近 1 说明索引有效比值上百说明扫了大量无关文档索引该重建或者查询条件该调整。6. 进阶聚合管道与事务边界6.1 聚合查询在 Java 侧的组装方式聚合是 MongoDB 的强项Java 侧的写法有两条路。简单管道用链式 APIAggregation agg Aggregation.newAggregation( Aggregation.match(Criteria.where(status).is(1) .and(inspect_time).gte(start)), Aggregation.group(device_id) .count().as(total) .sum(items.size()).as(itemCount) .max(inspect_time).as(lastTime), Aggregation.sort(Sort.Direction.DESC, total), Aggregation.limit(50) ); AggregationResultsDeviceStat results mongoTemplate.aggregate(agg, inspection_record, DeviceStat.class); ListDeviceStat list results.getMappedResults();复杂管道比如带$lookup、$unwind、$facet建议直接用Document拼 BSONListDocument pipeline Arrays.asList( new Document($match, new Document(status, 1)), new Document($unwind, $items), new Document($group, new Document(_id, $items.name) .append(failCount, new Document($sum, new Document($cond, Arrays.asList( new Document($eq, Arrays.asList($items.result, NG)), 1, 0))))), new Document($sort, new Document(failCount, -1)) ); AggregationOperation custom context - new Document($pipeline, pipeline); // 或逐条转 Document这里的关键原则$match一定要放在管道最前面这样才能用上索引$group和$sort放在后面。如果把$match放到$unwind之后等于先展开数组再过滤中间结果集会大出好几倍。另外提醒一句聚合不要跑在业务主流程的同步接口里。一次复杂的$group在大集合上跑几秒很正常把连接占住高并发下直接拖垮连接池。这类统计要么走异步任务要么预计算成结果表。6.2 事务的启用条件与使用边界先说结论MongoDB 事务能不用就不用非用不可时务必清楚它的代价。启用条件是服务端为副本集或分片集群版本 4.0。配置上需要一个MongoTransactionManagerConfiguration public class MongoTxConfig { Bean public MongoTransactionManager transactionManager( MongoDatabaseFactory factory) { return new MongoTransactionManager(factory); } }然后再照常用Transactional注解即可。代价在哪事务内默认使用快照隔离加锁会显著影响并发事务有 60 秒的默认执行上限事务期间写操作占用的资源不会释放。我见过一个团队把整条批量导入几万条包在一个事务里跑到 40 秒左右开始报TransactionTooLargeForCache最后拆成单条提交反而稳定。实际经验是只把真正需要原子性的那一小段包进事务。比如扣库存 写流水这两步而不是查询 校验 扣库存 写流水 发消息整条链。跨文档的强一致性需求如果能在建模阶段通过把强关联数据放进同一个文档来规避那才是最优先的方案——文档数据库的设计哲学本来就是用模型换掉事务。注意事务内的读操作要显式指定读关注为snapshot否则读到的可能是事务外的最新数据逻辑上会出现事务里读到脏数据的错觉。Spring 的Transactional默认已经处理了这部分但如果你手写了MongoTemplate并自定义了ReadConcern要留意是否会覆盖。写到这里差不多了。SpringBoot 整合 MongoDB 这件事跑通 Demo 只需要半小时但真正让它稳定承载业务功夫全在版本对齐、连接池预估、索引设计和类型的统一规范上。我个人的体会是文档数据库用起来最舒服的状态是你能在设计阶段就明确哪些数据是同一个聚合、必须一起读写而不是事后到处用事务去补一致性——后者说明模型本身就没想清楚换个数据库也救不回来。最后分享一个我沿用很久的习惯每个 Mongo 集合上线前先在测试库上灌 50 万条接近真实分布的数据跑一遍全部查询接口用explain逐个看执行计划。这个动作花不了两小时但能提前拦掉八成以上的性能问题。 
长河君 · 2026/10/26 3:27:50 · 阅读 1.2k SpringBoot整合MongoDB实战：选型、连接池、索引与事务边界
上个月帮一个做设备巡检系统的朋友翻代码看到他还在用 SpringBoot 拼 JDBC 手写 JSON 字符串往库里塞一条巡检记录十几个可变字段表结构改了三次每次都要停机加列。这种场景其实就是 MongoDB 的主场——文档模型天然适配字段不固定、嵌套层级深、读多写少的数据而 SpringBoot 生态对它的封装又足够成熟spring-boot-starter-data-mongodb一个依赖拉进来配置写三行MongoTemplate直接用整合成本低到可以忽略。这篇就围绕 SpringBoot 整合 MongoDB 这条主线把选型判断、依赖版本对齐、文档映射、连接池估算、批量写入、聚合与事务边界这些实际会碰到的东西一次讲透。适合刚接触文档数据库的后端同学也适合已经能跑通 Demo、但一到生产就出各种连接超时和类型错乱问题的老手——下面这些坑基本都是我或身边同行真踩过的。1. 动手之前先把选型逻辑捋顺1.1 一个真实需求场景的拆解先说我经手过的一个典型例子。某公司做工业设备巡检每台设备每次巡检产生的数据结构差异极大温度传感器上报的是{deviceId, ts, value}而人工巡检单里可能是{deviceId, ts, inspector, items:[{name, result, remark}], photos:[...]}甚至同一个集合里不同型号设备的字段集合能差出一半。最初用关系库方案是主表 若干张明细表 一个ext_json大字段兜底结果查询时既要 join 又要解析 JSON索引也建不利索。换成 MongoDB 之后整条巡检记录就是一个文档嵌套的items数组直接存在文档里一次查询把整条记录捞出来前端渲染不用再做二次拼装。这个转变的关键不在于用了 NoSQL 显得先进而在于数据本身的形状和存储的形状对上了。文档数据库的核心价值就在这里聚合根内部的从属数据天然就该跟着主文档一起读写。不过话说回来如果当时的需求是按巡检项跨设备做统计报表、还要和工单系统做多表关联那我肯定还是建议留在关系库。选型这件事最忌讳的就是拿一个新玩具硬套所有场景后面几节我会把判断标准写得更具体一些。1.2 SpringBoot 整合 MongoDB 适合与不适合的判断标准我一般用三个问题快速判断数据是不是以聚合根为单位整体读写比如订单 订单明细、文章 评论列表、设备 巡检项。是就适合如果明细需要独立被其他业务高频引用和关联就要谨慎。字段结构会不会频繁变化硬件上报、第三方回调、运营配置这类数据字段集合半年变一次很正常文档模型不用改表结构加个字段就完事。反过来如果是财务对账这种字段极其稳定、且强依赖外键约束的场景关系库更省心。读写比例和一致性要求如何读多写少、允许最终一致的场景内容、日志、画像、配置很合适。强事务、跨文档多写、需要复杂 join 的场景要么用副本集事务硬扛要么干脆别用。还有一个容易被忽略的点运维能力。MongoDB 的分片、副本集、备份恢复和传统关系库的运维习惯差别不小。团队里没人懂出了问题只能干瞪眼那还不如老老实实加两张表。技术选型从来不只是代码层面的事。1.3 版本兼容矩阵先对齐再写代码整合踩的第一个坑往往不是代码写错而是版本没对齐。Spring Data MongoDB 的版本跟 Spring Boot 绑定而底层又依赖mongodb-driver-sync三者错位就会出现各种诡异的NoSuchMethodError。下面这张表是我整理的常见组合照着选基本不会出问题Spring Boot 版本Spring Data MongoDBMongoDB Java Driver服务端建议版本2.7.x3.4.x4.6 ~ 4.94.4 / 5.0 / 6.03.0.x ~ 3.1.x4.0.x ~ 4.1.x4.9 ~ 4.115.0 / 6.03.2.x ~ 3.3.x4.2.x ~ 4.3.x4.11 / 5.06.0 / 7.03.4.x 及以上4.4.x5.27.0实际操作中最稳妥的做法是不要手动指定mongodb-driver-sync的版本交给 Spring Boot 的 BOM 管理。只有当服务端版本特别老比如还在 4.0或者特别新、驱动需要显式升级时才在dependencyManagement里覆盖。我见过有同事为了用上新特性手动把 driver 升到 5.x结果 Boot 2.7 的自动配置类里调用的方法签名变了启动直接报错排查了小半天。注意如果服务端是 MongoDB 4.0 以下且业务需要事务那就别折腾了事务要求副本集且版本 4.0单机模式怎么配都开不起来。2. 工程骨架依赖、配置与连接池2.1 起步依赖引入与排除项依赖这块非常简单一行搞定dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-mongodb/artifactId /dependency如果项目用的是 Maven 多模块注意别在同一工程里既引spring-boot-starter-data-mongodb又引mongodb-driver-legacy或者旧版mongo-java-driver这两个包同时存在时MongoClient的类会冲突启动报ClassNotFoundException或者更隐蔽的LinkageError。另外有个常被问到的问题要不要用响应式的spring-boot-starter-data-mongodb-reactive我的判断很直接——如果整条调用链已经是 WebFlux Reactor那就用响应式如果是传统 MVC别为了高性能硬上。响应式的收益在 IO 密集、高并发的场景才明显普通 CRUD 业务里Mono/Flux带来的调试成本和团队学习成本往往大于收益。我之前见过一个项目一半接口同步一半响应式最后block()到处飞反而把线程池堵死了。2.2 application.yml 分环境配置写法配置有两种主流写法选一种坚持用别混。写法一拆开写推荐参数可控性更好spring: data: mongodb: host: 127.0.0.1 port: 27017 database: inspection username: app_user password: ${MONGO_PWD} authentication-database: admin auto-index-creation: true uri: # 留空走上面的分项配置写法二URI 一把梭spring: data: mongodb: uri: mongodb://app_user:${MONGO_PWD}127.0.0.1:27017/inspection?authSourceadminmaxPoolSize80minPoolSize10maxIdleTimeMS60000两种写法的差别在于URI 方式对连接池参数、读写关注readConcern/writeConcern、超时时间的控制更细因为这些参数是 URI 的 query 部分天然支持的分项配置方式更直观但部分参数需要额外定义 Bean 才能覆盖。我个人的习惯是开发环境用分项配置改起来方便生产和预发统一用 URI密码走环境变量注入绝不写死在配置文件里。这里提一句authentication-database如果你的用户建在admin库但业务库是另一个这个参数不写会直接认证失败——这是新手最容易卡住的地方之一。2.3 连接池参数怎么估算才不翻车连接池是生产事故的高发区。默认maxPoolSize是 100听着够用但如果一个应用有多个实例、每个实例都开 100服务端连接数瞬间就上去了MongoDB 单机默认连接上限大概在两万左右加上内部连接很容易打出connection refused。给一个可以直接套用的估算公式所需连接数 ≈ (峰值 QPS × 单次操作平均耗时ms) / 1000 × 冗余系数(1.5 ~ 2)举个具体例子某个查询接口峰值 QPS 400单次find平均耗时 6ms那么并发占用约400 × 6 / 1000 2.4个连接乘 1.5 冗余理论上 4 个就够。但实际业务里存在慢查询、批量写入、聚合统计这些耗时长的操作会长时间占用连接所以我把maxPoolSize设成 50minPoolSize设 10maxIdleTimeMS设 60000maxLifeTimeMS设 1800000。再看整体应用部署 4 个实例4 × 50 200个连接加上运维工具、备份任务服务端压力完全可控。对比之前有个团队直接用默认 1008 个实例就是 800 连接一到高峰期就开始报超时把maxPoolSize降到 40 之后问题消失。参数建议值说明maxPoolSize30 ~ 80按实例数和 QPS 估算别用默认 100minPoolSize5 ~ 20保持一定预热连接避免突发建连maxIdleTimeMS60000空闲连接回收时间maxLifeTimeMS1800000连接最长存活时间防止服务端侧断连connectTimeoutMS5000建连超时别设太大serverSelectionTimeoutMS3000 ~ 5000选节点超时直接影响故障响应速度socketTimeoutMS20000 ~ 60000读写超时按最慢查询的 2 倍设waitQueueTimeoutMS5000拿不到连接时的等待上限防止线程无限堆积提示waitQueueTimeoutMS这个参数特别值得设。不设的话池子满了之后请求会无限期等待线程池被慢慢耗干最后整个服务假死日志里却什么明显错误都没有——这种故障排查起来极其痛苦。3. 文档映射把集合结构翻译成Java类3.1 Document 注解与字段命名策略实体类是最先要落地的。一个标准的映射类长这样import lombok.Data; import org.springframework.data.annotation.Id; import org.springframework.data.mongodb.core.mapping.Document; import org.springframework.data.mongodb.core.mapping.Field; import java.time.Instant; import java.util.List; Data Document(collection inspection_record) public class InspectionRecord { Id private String id; Field(device_id) private String deviceId; private String inspector; private Instant inspectTime; private ListInspectionItem items; private Integer status; }几个细节值得展开说。第一Id对应的字段类型建议用StringMongoDB 的_id本质是ObjectId但驱动会自动做转换用String在前后端传输时最省事如果你确实需要按ObjectId的时间戳做排序那就在插入后取id做一次转换或者干脆额外存一个Instant字段不要试图在_id上做业务逻辑。第二Field的作用是把 Java 的驼峰命名映射成库里的下划线命名。不加也能跑字段名就变成驼峰但这样和已有数据的字段风格不一致后续用命令行工具查数据时会很难受。这里有个更省事的做法——在配置里全局指定命名策略spring: data: mongodb: field-naming-strategy: org.springframework.data.mapping.model.SnakeCaseFieldNamingStrategy配上之后所有驼峰字段自动转下划线实体类里就不用一个一个加Field了。不过这属于一次性决定中途切换会导致已有数据读不出来上线前一定要定死。第三Instant和LocalDateTime的选择。我强烈建议用Instant理由在 5.2 节详细说。3.2 嵌套对象、数组与Map类型的落库形态嵌套是文档数据库的核心优势但写法上有讲究。看这个InspectionItemData public class InspectionItem { private String name; private String result; private String remark; private ListString photoUrls; }落库之后就是一个子文档数组。这里要注意两点数组内的子文档可以单独被索引和查询用items.name这样的路径但不能单独更新数组内某个元素的单个字段——你要么用$set配合位置操作符改整个元素要么用$push/$pull做增删。这一点和关系库的明细表按主键更新思维完全不同设计时要想清楚更新模式。还有一个常见需求是动态字段比如不同设备型号有不同指标。这时候可以用MapString, Objectprivate MapString, Object metrics;落库就是{metrics: {temp: 36.5, vibration: 0.12}}灵活是灵活但代价是无法用 Spring Data 的派生查询方法直接查只能走MongoTemplate手写 Criteria而且字段类型不受约束容易出现同一个 key 一会儿是数字一会儿是字符串的情况。我的经验是能用固定字段就用固定字段Map只在真正不可预知的场景用并且约定好 value 只允许String/Number/Boolean三种基础类型。3.3 索引声明与自动创建开关索引不建查询就是全表扫数据量一过百万直接卡死。Spring Data 提供了注解声明方式Document(collection inspection_record) CompoundIndex(name idx_device_time, def {device_id: 1, inspect_time: -1}) public class InspectionRecord { // ... Indexed private Integer status; }这里有个大坑从 Spring Data MongoDB 3.0 开始自动建索引默认关闭了你光加注解不管用必须在配置里显式打开spring: data: mongodb: auto-index-creation: true打开之后应用启动时会扫描注解并创建索引已存在且定义一致则跳过。但生产环境我通常建议关掉自动创建改用脚本或迁移工具统一管理索引。原因很实际自动创建在多实例同时启动时可能产生并发冲突更麻烦的是如果索引定义改了旧索引不会自动删除会留下一个僵尸索引占着写入性能你还得手工去 drop。索引是数据库层面的资产就该像表结构一样纳入版本管理。复合索引的字段顺序也有讲究{device_id: 1, inspect_time: -1}能支持按设备查 按时间倒序的查询但如果业务里更多是按时间范围 按状态过滤那索引就该建成{status: 1, inspect_time: -1}。这条原则跟关系库完全一致等值条件在前范围/排序条件在后。4. 数据访问实操MongoTemplate 与 Repository 两条路4.1 MongoTemplate 的增删改查标准写法Spring Data 给了两套 APIMongoTemplate和MongoRepository。我的建议是两者都用但分工明确——简单 CRUD 走 Repository复杂查询、聚合、批量操作走 Template。MongoTemplate的基本用法Service RequiredArgsConstructor public class InspectionService { private final MongoTemplate mongoTemplate; // 插入返回带 id 的对象 public InspectionRecord save(InspectionRecord record) { return mongoTemplate.insert(record); } // 条件查询 排序 限制条数 public ListInspectionRecord recent(String deviceId, int limit) { Query query new Query( Criteria.where(device_id).is(deviceId) .and(inspect_time).gte(Instant.now().minusSeconds(86400)) ).with(Sort.by(Sort.Direction.DESC, inspect_time)) .limit(limit); return mongoTemplate.find(query, InspectionRecord.class); } // 局部更新只改指定字段 public void updateStatus(String id, Integer status) { Query query new Query(Criteria.where(_id).is(id)); Update update new Update() .set(status, status) .currentDate(update_time); mongoTemplate.updateFirst(query, update, InspectionRecord.class); } }几个实操要点insert和save的区别在于insert遇到已存在的_id会抛DuplicateKeyExceptionsave则是 upsert 语义有 id 就整体替换。在需要防止重复插入的场景比如幂等消费消息用insert配合唯一索引更安全。updateFirst只更新第一条updateMulti更新所有匹配项upsert系列方法在无匹配时插入。别用错。Query对象是可以复用的但limit、skip、with会修改原对象如果多处复用同一个 Query记得Query.query(criteria)重新构造不然会踩查询条件莫名其妙被改的坑。这个坑我调了两小时才定位到。4.2 Repository 派生查询与方法命名规则仓库接口的写法非常省心public interface InspectionRecordRepository extends MongoRepositoryInspectionRecord, String { ListInspectionRecord findByDeviceIdAndInspectTimeAfter( String deviceId, Instant time); PageInspectionRecord findByStatus(Integer status, Pageable pageable); long deleteByDeviceId(String deviceId); boolean existsByDeviceIdAndStatus(String deviceId, Integer status); }方法名解析规则和 JPA 基本一致And/Or/GreaterThan/In/Regex这些都能用。但有两个坑必须提坑一字段名映射不一致。如果实体上加了Field(device_id)findByDeviceId是能正确识别的因为 Spring Data 会做属性到字段的映射但如果你手写Query里面必须写库里真实的字段名device_id写驼峰会查不到数据。坑二deleteBy会先查后删。派生删除方法是查询出所有匹配文档 → 逐个删除数据量大时性能极差而且返回的计数是删除条数。批量删除请用mongoTemplate.remove(query, Class)一次调用就完事。还有一点MongoRepository和MongoTemplate混用时事务不会自动传递除非配了MongoTransactionManager这点在第 6 节细说。4.3 分页、排序与字段投影分页用PageablePageable pageable PageRequest.of(0, 20, Sort.by(Sort.Direction.DESC, inspect_time)); PageInspectionRecord page repository.findByStatus(1, pageable);看起来很美但要注意**Page会额外执行一次count查询**。如果集合里有几百万文档每次翻页都 count 一遍成本极高。有两种应对方式一是改用Slice只查是否还有下一页不查总数二是前端改成游标分页用上一页最后一条的时间戳作为inspect_time lastTs的条件性能最好。字段投影是另一个实用技巧。列表页往往只需要几个字段没必要把带 photos 数组的完整文档拉回来Query query new Query(Criteria.where(status).is(1)) .with(Sort.by(Sort.Direction.DESC, inspect_time)) .limit(20) .fields().include(device_id, inspector, inspect_time, status); ListInspectionRecord list mongoTemplate.find(query, InspectionRecord.class);投影能显著减少网络传输量和反序列化开销列表接口响应时间从 200ms 降到 60ms 是常有的事。4.4 批量写入BulkOperations 的正确用法批量场景千万别在 for 循环里一条一条 insert一次网络往返就是一次开销几千条能把接口拖到超时。正确做法是BulkOperationspublic void batchSave(ListInspectionRecord list) { if (CollectionUtils.isEmpty(list)) { return; } int batchSize 1000; for (int i 0; i list.size(); i batchSize) { ListInspectionRecord sub list.subList(i, Math.min(i batchSize, list.size())); BulkOperations ops mongoTemplate.bulkOps( BulkOperations.BulkMode.UNORDERED, InspectionRecord.class); ops.insert(sub); ops.execute(); } }三个关键点批次大小控制在 500 ~ 1000 条太大容易触发 16MB 的文档大小限制或者驱动内部缓冲区溢出用UNORDERED模式让服务端并行执行单条失败不影响其他条分批执行而不是一次性塞方便中途记录进度和失败重试。实测数据在本地环境逐条插入 5000 条记录耗时约 12 秒改成 1000 条一批的UNORDERED批量后降到 800 毫秒左右。数量级上的差异别不当回事。5. 踩坑实录与问题速查5.1 连接、超时与认证类故障这类问题占了实际故障的七成以上整理成表方便对照现象大概率原因处理方式启动报Authentication failed用户建在 admin 库但没配authSourceURI 加authSourceadmin偶发Connection refused服务端连接数打满降maxPoolSize核对实例总数请求长时间挂起无响应池子耗尽且没设waitQueueTimeoutMS补上该参数加监控告警No server chosen/ 超时 30s节点故障但serverSelectionTimeoutMS太大调到 3000~5000ms 快速失败隔夜后首次请求超时空闲连接被中间设备断开设maxLifeTimeMS小于中间设备空闲阈值批量写入报 16MB 超限单次 bulk 数据过大缩小批次或拆分文档提示那个隔夜超时的问题特别隐蔽——白天一切正常第二天早上第一批请求必然超时之后又好了。本质是长时间空闲的连接被网络中间层静默断开而客户端还以为是活的。设maxLifeTimeMS让连接主动轮换就能绕过去。5.2 日期时区与数值类型的隐性偏差日期这块我吃过一次大亏。早期实体类用了LocalDateTime本地开发一切正常部署到服务器UTC 时区之后页面上的时间整整差了 8 小时。原因是驱动把LocalDateTime当作无时区的本地时间序列化成Date服务端按 UTC 存读回来再按 UTC 解释中间就丢了偏移。结论很干脆存时间一律用Instant需要展示时在接口层转成业务时区。如果历史数据已经用了LocalDateTime可以加一个转换器统一处理Bean public MongoCustomConversions customConversions() { return new MongoCustomConversions(Arrays.asList( new InstantToDateConverter(), new DateToInstantConverter() )); }数值类型也有坑。JSON 里1和1.0是不同的 BSON 类型int32 vs double如果你用MapString, Object存指标某个字段一会儿存整数一会儿存小数之后用Criteria.where(metrics.temp).is(36.5)查询就可能匹配不上。解决办法是在写入前统一做类型规整或者干脆定义为Double强转。5.3 _class 字段引发的序列化问题默认情况下Spring Data 会给每个文档加一个_class字段值是类的全限定名比如com.example.demo.entity.InspectionRecord。这个字段的作用是反序列化时能还原成具体类型但它有三个副作用占空间、暴露包结构、类名改了之后老数据读不出来。处理方式有两种。轻量的方式是加类型别名Document(collection inspection_record) TypeAlias(inspection) public class InspectionRecord { ... }这样_class就变成inspection短且稳定。另一种是直接在配置里关掉Bean public MongoTemplate mongoTemplate(MongoDatabaseFactory factory, MongoMappingContext context) { MappingMongoConverter converter new MappingMongoConverter(new DefaultDbRefResolver(factory), context); converter.setTypeMapper(new DefaultMongoTypeMapper(null)); // 不写 _class return new MongoTemplate(factory, converter); }关掉之后文档会干净很多但代价是不能再用父类/接口接收查询结果做多态反序列化必须明确指定具体类型。如果业务里没有多态存储的需求关掉是划算的几百万文档省下的空间和反序列化时间都不算小。5.4 性能问题速查表现象排查方向常用手段查询随数据量线性变慢缺少索引explain(executionStats)看是否 COLLSCAN单条查询偶发 1s慢查询阻塞连接池开慢查询日志slowms设 100写入吞吐上不去索引过多 / 写关注过高精简索引评估writeConcern分页越翻越慢深分页 skip 成本高改游标分页或加范围条件内存占用持续上涨大结果集全量加载加 limit、用投影、流式读取聚合查询超时管道顺序不合理$match前置尽量在索引上过滤排查的第一步永远是explain。在 Java 里可以这样打Query query new Query(Criteria.where(device_id).is(D001)); Document explain mongoTemplate.getDb() .runCommand(new Document(explain, new Document(find, inspection_record) .append(filter, new Document(device_id, D001))) .append(verbosity, executionStats)); System.out.println(explain.toJson());看winningPlan.stage是不是COLLSCANtotalDocsExamined和nReturned的比值是多少。比值接近 1 说明索引有效比值上百说明扫了大量无关文档索引该重建或者查询条件该调整。6. 进阶聚合管道与事务边界6.1 聚合查询在 Java 侧的组装方式聚合是 MongoDB 的强项Java 侧的写法有两条路。简单管道用链式 APIAggregation agg Aggregation.newAggregation( Aggregation.match(Criteria.where(status).is(1) .and(inspect_time).gte(start)), Aggregation.group(device_id) .count().as(total) .sum(items.size()).as(itemCount) .max(inspect_time).as(lastTime), Aggregation.sort(Sort.Direction.DESC, total), Aggregation.limit(50) ); AggregationResultsDeviceStat results mongoTemplate.aggregate(agg, inspection_record, DeviceStat.class); ListDeviceStat list results.getMappedResults();复杂管道比如带$lookup、$unwind、$facet建议直接用Document拼 BSONListDocument pipeline Arrays.asList( new Document($match, new Document(status, 1)), new Document($unwind, $items), new Document($group, new Document(_id, $items.name) .append(failCount, new Document($sum, new Document($cond, Arrays.asList( new Document($eq, Arrays.asList($items.result, NG)), 1, 0))))), new Document($sort, new Document(failCount, -1)) ); AggregationOperation custom context - new Document($pipeline, pipeline); // 或逐条转 Document这里的关键原则$match一定要放在管道最前面这样才能用上索引$group和$sort放在后面。如果把$match放到$unwind之后等于先展开数组再过滤中间结果集会大出好几倍。另外提醒一句聚合不要跑在业务主流程的同步接口里。一次复杂的$group在大集合上跑几秒很正常把连接占住高并发下直接拖垮连接池。这类统计要么走异步任务要么预计算成结果表。6.2 事务的启用条件与使用边界先说结论MongoDB 事务能不用就不用非用不可时务必清楚它的代价。启用条件是服务端为副本集或分片集群版本 4.0。配置上需要一个MongoTransactionManagerConfiguration public class MongoTxConfig { Bean public MongoTransactionManager transactionManager( MongoDatabaseFactory factory) { return new MongoTransactionManager(factory); } }然后再照常用Transactional注解即可。代价在哪事务内默认使用快照隔离加锁会显著影响并发事务有 60 秒的默认执行上限事务期间写操作占用的资源不会释放。我见过一个团队把整条批量导入几万条包在一个事务里跑到 40 秒左右开始报TransactionTooLargeForCache最后拆成单条提交反而稳定。实际经验是只把真正需要原子性的那一小段包进事务。比如扣库存 写流水这两步而不是查询 校验 扣库存 写流水 发消息整条链。跨文档的强一致性需求如果能在建模阶段通过把强关联数据放进同一个文档来规避那才是最优先的方案——文档数据库的设计哲学本来就是用模型换掉事务。注意事务内的读操作要显式指定读关注为snapshot否则读到的可能是事务外的最新数据逻辑上会出现事务里读到脏数据的错觉。Spring 的Transactional默认已经处理了这部分但如果你手写了MongoTemplate并自定义了ReadConcern要留意是否会覆盖。写到这里差不多了。SpringBoot 整合 MongoDB 这件事跑通 Demo 只需要半小时但真正让它稳定承载业务功夫全在版本对齐、连接池预估、索引设计和类型的统一规范上。我个人的体会是文档数据库用起来最舒服的状态是你能在设计阶段就明确哪些数据是同一个聚合、必须一起读写而不是事后到处用事务去补一致性——后者说明模型本身就没想清楚换个数据库也救不回来。最后分享一个我沿用很久的习惯每个 Mongo 集合上线前先在测试库上灌 50 万条接近真实分布的数据跑一遍全部查询接口用explain逐个看执行计划。这个动作花不了两小时但能提前拦掉八成以上的性能问题。