Spring Data MongoDB 批量写入实践：BulkOperations 批大小与写关注权衡

Spring Data MongoDB 批量写入实践：BulkOperations 批大小与写关注权衡

1. 先看一个真实场景：为什么单条 insert 会拖垮接口

假设你负责一个订单归档服务：每天凌晨把上游 Kafka 里积压的 80 万条订单事件写入 MongoDB 的 order_archive 集合。最初的实现很直观：遍历消息列表，逐条调用 mongoTemplate.insert(order)。上线第一周没问题，第二周数据量翻倍后，任务从 12 分钟涨到 90 分钟，最后在 2 小时的任务窗口里跑不完，接口层开始报连接池等待超时。

排查时你会发现，问题往往不在 MongoDB 本身，而在"一次网络往返只干一件事"的调用方式上。每条 insert 都要经历：应用线程从连接池借连接、序列化文档、发命令、服务端写入、返回确认、归还连接。80 万次往返的固定开销，远大于真正写盘的时间。更要命的是，逐条写入时一旦遇到唯一索引冲突或网络抖动，你很难判断"写到第几条了"，重试也不安全。

这篇要解决的就是这个问题：把"逐条交互"改成"成批交互"，并回答随之而来的两个新问题------一次批多大合适？每批要求多强的写入确认？这就是 bulk（批量）与 write concern（写关注）的权衡。

2. 一句话模型与整体框架

先记住一句话：BulkOperations 是把多条写命令打包成少量请求发给 MongoDB 的搬运工，批大小决定"一车装多少"，写关注决定"货送到哪个程度才算签收"。

把整体拆成三部分看：

• 客户端侧：MongoTemplate 提供的 BulkOperations，负责把 insert/update/remove/replace 攒进内存，并按规则切分成多个批次。
• 传输侧：每个批次被序列化成一条 insert 或 update 命令，通过连接发往副本集或分片集群。
• 服务端侧：主节点按写关注级别写 oplog、等待从节点确认，再把结果（成功条数、失败明细）返回。

一次批量写入的流转顺序如下：

业务线程
  |
  v
[收集写操作 List] --> [BulkOperations 缓存]
                            |
                            v
                 [按 batchSize / 命令类型切批]
                            |
                            v
        [逐批 execute：序列化为 insert/update 命令]
                            |
                            v
        [MongoDB 主节点写入 + 按 writeConcern 等待]
                            |
                            v
     [返回 BulkWriteResult / 抛出 BulkOperationException]
                            |
                            v
               [根据结果决定重试或告警]

这里最容易误解的是：BulkOperations 不是"一次请求"，它只是帮你把多次请求组织得更高效，具体拆成几条命令由你决定的批次策略和驱动行为共同决定。

3. 有序与无序：失败之后到底谁停下来

批量写入最核心的一个语义选择，是 ordered（有序）还是 unordered（无序）。

• 有序（默认，ordered=true）：服务端按你提交的顺序逐条执行，一旦某条失败（例如唯一键冲突），后续所有操作直接跳过。
• 无序（ordered=false）：服务端可以并发或分批执行这些操作，某条失败不影响其他条，最终返回所有失败的明细。

举个例子：你要导入 1000 条用户数据，其中第 500 条 email 与已有记录冲突。有序模式下，结果是前 499 条成功，第 500 条失败，501~1000 条全部没执行；无序模式下，可能 999 条成功，只有那一条冲突记录失败。

对比项	有序 ordered=true	无序 ordered=false
执行顺序	严格按提交顺序	不保证顺序
失败行为	遇到错误即停止后续	跳过失败，继续其余
服务端并发	基本串行	可并行执行
吞吐	较低	较高
结果含义	成功段是连续前缀	成功集合是离散的
典型用途	有依赖的写、需精确断点	导入、幂等同步、去重写入

选择原则很简单：当多条写之间有顺序依赖时用有序；当它们彼此独立、失败可容忍时用无序。 大多数"批量导入/同步"场景属于后者，用无序能显著减少因单条脏数据导致的整批回滚。

4. 用 BulkOperations 写出第一个最小示例

目标：向 product 集合批量插入 2000 条商品，对比有序与无序的耗时和失败行为。

前置环境：Spring Boot 3.x、Java 17、MongoDB 6.x 副本集（至少一主一从便于观察写关注）、spring-boot-starter-data-mongodb 依赖。

import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.BulkOperations;
import org.springframework.data.mongodb.core.query.Query;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.List;

@Service
public class ProductBulkService {

    private final MongoTemplate mongoTemplate;

    public ProductBulkService(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    public void importProducts(List<Product> products, boolean ordered) {
        BulkOperations bulk = mongoTemplate.bulkOps(
                ordered ? BulkOperations.BulkMode.ORDERED : BulkOperations.BulkMode.UNORDERED,
                Product.class);

        for (Product p : products) {
            bulk.insert(p);
        }

        try {
            BulkWriteResult result = bulk.execute();
            System.out.println("matched=" + result.getMatchedCount()
                    + ", inserted=" + result.getInsertedCount()
                    + ", modified=" + result.getModifiedCount());
        } catch (BulkOperationException ex) {
            // 有序模式下会在这里拿到失败明细
            System.err.println("部分失败: " + ex.getErrors());
            throw ex;
        }
    }

    public static class Product {
        private String id;
        private String sku;
        private String name;
        private int stock;
        // 省略 getter/setter
    }
}

关键步骤说明：

1. bulkOps(mode, Product.class) 创建批量句柄，mode 决定有序/无序。
2. 循环 bulk.insert(p) 只是把文档加入内存队列，此时还没有发请求。
3. 调用 execute() 才真正产生网络请求；驱动会把队列中的操作合并成一条或多条命令。
4. 有序模式下遇到冲突会抛 BulkOperationException，可通过 getErrors() 定位失败索引和原因。

预期结果：2000 条无冲突数据下，无序通常比有序快 20%~50%；若故意插入一条重复 sku，有序会在该条中断，无序只丢那一条。容易改错的地方是：把 execute() 放进循环里，等于又把批量退化成了单条写入。

5. 批大小：一车装多少才不翻车

5.1 批次不是越大越好

很多人以为"一个 BulkOperations 塞 10 万条最省事"，但实际会踩三个坑：

• 内存压力：所有待写文档先缓存在应用堆里，10 万条大文档可能占几百 MB，叠加并发任务容易 OOM。
• 单条命令过大：MongoDB 单条命令有大小上限（默认 16MB 级别的 maxBsonObjectSize 与 maxWriteBatchSize 限制），超出会报错。
• 失败代价大：一批全失败需要重试整批，重试成本随批次线性上升。

批大小的本质是：在"减少网络往返"和"控制单次内存/失败爆炸半径"之间找平衡点。

5.2 推荐的切批写法

import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.BulkOperations;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;

import java.util.List;

public class BatchImportHelper {

    private static final int BATCH_SIZE = 1000;

    private final MongoTemplate mongoTemplate;

    public BatchImportHelper(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    public int batchUpsert(String upsertField, List<ProductBulkService.Product> items) {
        int total = 0;
        for (int i = 0; i < items.size(); i += BATCH_SIZE) {
            List<ProductBulkService.Product> slice =
                    items.subList(i, Math.min(i + BATCH_SIZE, items.size()));

            BulkOperations bulk = mongoTemplate.bulkOps(
                    BulkOperations.BulkMode.UNORDERED, ProductBulkService.Product.class);
            for (ProductBulkService.Product p : slice) {
                Query query = Query.query(Criteria.where("sku").is(p.getSku()));
                bulk.upsert(query, p);
            }
            BulkWriteResult result = bulk.execute();
            total += result.getModifiedCount() + result.getInsertedCount();
        }
        return total;
    }
}

这段代码做了两件关键事：应用层按 1000 条切批，且每种批次内部用 upsert 而不是 insert，让同步任务天然幂等、可重跑。

5.3 批大小的经验区间

文档大小	建议批大小	说明
< 1KB	1000~5000	小文档，网络往返是主要瓶颈
1KB~10KB	500~1000	兼顾内存与命令大小
10KB~100KB	100~500	大文档优先控内存
> 100KB	20~100	接近命令上限，需实测

注意这只是起点，不是结论。真正合适的值依赖你的文档大小、网络 RTT、副本集确认策略和并发度，必须用真实数据压测。

6. 写关注：货送到哪个程度才算签收

写关注（write concern）回答的问题是：主节点写入后，要不要等从节点也落盘，才算这次写成功？ 它由三个参数描述：w（要多少个节点确认）、j（是否写 journal）、wtimeout（等待超时毫秒）。

w 值	含义	延迟	数据安全
0	不等待任何确认	最低	最差，可能丢
1	主节点写入即返回	低	主节点宕机可能丢
majority	多数节点确认	较高	可容忍少数节点故障
带 j=true	额外要求写 journal	进一步升高	进程崩溃也不易丢

一个直观类比：w=1 像快递员把包裹放到你家门口就走，w=majority 像要求你和邻居同时签收。类比能帮你记住"确认人数越多越安全越慢"，但它不能替代真实机制------副本集选举、oplog 传播、journal 刷盘这些细节，才是延迟真正发生的地方。

6.1 在 Spring Data 中设置写关注

import com.mongodb.WriteConcern;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.MongoTemplate;
import com.mongodb.client.MongoClient;

@Configuration
public class MongoWriteConcernConfig {

    @Bean
    public MongoTemplate mongoTemplate(MongoClient client,
                                       org.springframework.data.mongodb.MongoDatabaseFactory factory) {
        // 全局默认写关注：多数派确认，最多等 5 秒
        factory.withWriteConcern(WriteConcern.MAJORITY.withWTimeout(5000, java.util.concurrent.TimeUnit.MILLISECONDS));
        return new MongoTemplate(factory);
    }
}

也可以只对批量写入临时提高或降低要求，用 bulkOps(...) 之后配合 MongoTemplate 的 withSession 或在集合层面指定 WriteConcern。关键点是：写关注可以在客户端、数据库、集合、单次操作四个层级设置，优先级从单次操作向上覆盖。

6.2 wtimeout 的边界

wtimeout 到期不等于写入失败，而是"等待确认超时"。此时主节点可能已经写成功，只是没等到足够的从节点确认。工程上要把这类超时当成不确定状态处理，而不是简单重试，否则可能造成重复写。

7. 一次完整批量写入的推演

把前面的概念串起来，走一遍 10 万条订单归档的完整过程：

1. 应用从 Kafka 拉取 10 万条订单
2. 按 1000 条切批，共 100 批
3. 每批构造 UNORDERED BulkOperations，操作类型为 upsert
4. 每批 execute() -> 发一条 update 命令
5. 主节点写入并追加 oplog
6. 若 w=majority，等待 1 个从节点确认
7. 从节点确认后返回 BulkWriteResult
8. 应用累加 modified/inserted，处理 errors
9. 100 批完成后打印总耗时与失败数

在这条链路里，有三个位置可能成为瓶颈：第 2 步的切批策略（切太碎则往返多，切太大则内存高）、第 6 步的等待（w 越高越慢）、第 8 步的异常处理（无序模式下必须逐条检查错误，不能只看有没有抛异常）。

8. 有序、无序、写关注如何组合

这三个维度不是独立的，组合起来会形成不同的工程姿态：

组合	吞吐	数据安全	适用场景
无序 + w=1	最高	低	日志、埋点、可丢数据
无序 + w=majority	高	中高	大部分业务同步
有序 + w=1	中	低	有依赖、但能容忍丢
有序 + w=majority	低	高	资金、订单等关键路径

决策顺序建议：先问数据能不能丢，再问有没有顺序依赖，最后才调批大小。 很多人一上来就调批大小，其实写关注才是延迟的大头。

9. 贴近业务的第二个完整示例：幂等订单同步

目标：从上游系统同步订单，要求可重复执行、单条脏数据不影响整体、关键字段用写关注保证不丢。

import com.mongodb.WriteConcern;
import org.springframework.data.mongodb.core.BulkOperations;
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;
import org.springframework.data.mongodb.core.query.Update;

import java.util.List;
import java.util.concurrent.TimeUnit;

public class OrderSyncService {

    private static final int BATCH_SIZE = 500;
    private final MongoTemplate mongoTemplate;

    public OrderSyncService(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    public SyncReport sync(List<Order> orders) {
        int success = 0;
        int failed = 0;
        for (int i = 0; i < orders.size(); i += BATCH_SIZE) {
            List<Order> slice = orders.subList(i, Math.min(i + BATCH_SIZE, orders.size()));
            BulkOperations bulk = mongoTemplate.bulkOps(
                    BulkOperations.BulkMode.UNORDERED, Order.class)
                    .withWriteConcern(WriteConcern.MAJORITY
                            .withWTimeout(3000, TimeUnit.MILLISECONDS));

            for (Order o : slice) {
                Query q = Query.query(Criteria.where("orderNo").is(o.getOrderNo()));
                Update u = new Update()
                        .set("status", o.getStatus())
                        .set("amount", o.getAmount())
                        .setOnInsert("createdAt", o.getCreatedAt());
                bulk.upsert(q, u);
            }

            try {
                BulkWriteResult r = bulk.execute();
                success += r.getModifiedCount() + r.getInsertedCount();
            } catch (BulkOperationException ex) {
                failed += ex.getErrors().size();
                // 记录失败批次起始下标，便于人工补偿
            }
        }
        return new SyncReport(success, failed);
    }

    public record SyncReport(int success, int failed) {}
}

class Order {
    private String orderNo;
    private String status;
    private java.math.BigDecimal amount;
    private java.time.Instant createdAt;
}

关键点解释：

• 用 upsert + setOnInsert 实现幂等：已存在则更新状态，不存在则插入并补上创建时间。
• 无序模式保证一条脏数据不会阻断整批。
• 关键订单用 majority + 3s wtimeout，在安全与延迟间折中。
• BulkWriteResult 只给汇总计数，单条失败要看 ex.getErrors()。

预期输出：1000 条订单、其中 3 条字段非法时，成功约 997 条，失败 3 条，任务不中断。易改错点：把 Update 里的 set 和 setOnInsert 搞反，导致每次同步都覆盖创建时间。

10. 生产排障案例：批量写入变慢的定位顺序

现象：某同步任务从 8 分钟涨到 40 分钟，日志显示没有明显报错。

排查顺序与观察点：

第 1 步 看单批耗时分布 -> 是否某几批特别慢（热点/锁/大文档）
第 2 步 看 writeConcern -> 是否被人改成 majority + 无限 wtimeout
第 3 步 看批大小     -> 是否单批过大导致 GC 停顿
第 4 步 看索引       -> 是否 upsert 的查询字段没建索引，导致全表扫描
第 5 步 看副本集延迟 -> 从节点是否跟不上，导致 majority 等待变长
第 6 步 看连接池     -> 并发批量任务是否争抢连接

最常见的根因是两个：upsert 的查询条件字段缺少索引，以及 wtimeout 未设置导致线程长时间挂起。前者用 db.collection.getIndexes() 确认，后者用 db.serverStatus().metrics.getLastError 观察等待情况。

11. 常见误区

• 误以为 bulkOps 自动分批。 它只是缓存操作，批次策略需要你自己控制；大批次一次性 execute() 会带来内存和命令大小风险。
• 误以为无序模式不会报错。 它只是不中断，错误仍然通过 BulkOperationException 或结果返回。
• 误以为写关注只影响安全、不影响性能。 从 w=1 到 w=majority，在跨机房副本集上延迟可能翻数倍。
• 误以为 wtimeout 超时等于失败。 这是不确定状态，盲目重试会造成重复写。
• 误以为批越大吞吐越高。 超过某个点后，GC 和网络包切分开销会让吞吐反降。

12. 生产实践建议

• 批量导入默认用 无序 + upsert，让任务幂等可重跑。
• 批大小从 500~1000 起步，用真实文档大小压测后再调。
• 关键路径用 majority，但一定要配 wtimeout，避免线程无限等待。
• 为 upsert 的查询字段建唯一索引，既提速又防重。
• 记录每批的起始下标和耗时，便于失败断点续传。
• 监控 BulkOperationException 的错误码分布，区分是数据问题还是网络问题。

13. 排障清单

现象	可能原因	检查方法
整批失败	有序模式遇到冲突	看异常中的失败索引
部分失败	无序模式脏数据	检查 getErrors()
越来越慢	缺索引 / 从节点延迟	getIndexes()、rs.status()
偶发超时	wtimeout 过短	观察 wtimeout 与网络 RTT
OOM	批过大 / 未切批	检查堆内存与批大小
重复数据	超时后盲目重试	确认 upsert 幂等性

14. 面试/复盘问题

1. BulkOperations 的 ordered 和 unordered 在失败语义上有什么本质区别？各自适合什么场景？
2. 为什么批量写入需要应用层切批？驱动和 MongoDB 各自有哪些大小限制？
3. w=majority 和 j=true 分别解决什么问题？为什么会增加延迟？
4. wtimeout 超时后，为什么不能直接重试？如何设计幂等写入来规避？
5. 如果一批写入中只有少量失败，你如何在不重跑全量的前提下补偿？

15. 总结：把批量写入收回一张决策图

当你要写批量数据时，按这个顺序做决定：

数据能丢吗？
  |-- 能丢     -> w=0/1，无序，批大一点追求吞吐
  |-- 不能丢   -> w=majority，考虑 j=true，配 wtimeout

写操作有顺序依赖吗？
  |-- 有       -> 有序，批小一点，便于断点续传
  |-- 没有     -> 无序，可并发，容错更好

文档大吗？
  |-- 小       -> 批 1000~5000
  |-- 大       -> 批 100~500，优先控内存

核心结论只有一句：BulkOperations 解决"往返次数太多"，批大小解决"一次装多少"，写关注解决"什么时候算成功"。三者必须一起调，单看任何一项都会得出错误结论。 先把数据和场景看清，再选组合，最后才是压测调参。

16. 参考资料

• Spring Data MongoDB 官方文档：BulkOperations 与 BulkMode 章节
• MongoDB 官方手册：Bulk Write Operations、Write Concern、Read Concern
• MongoDB 官方手册：Replica Set Elections 与 Write Concern for Replica Sets
• MongoDB Java Driver 官方文档：BulkWriteResult、BulkWriteError、WriteConcern
• 《MongoDB 权威指南》（Kristina Chodorow 等）关于写关注与副本集的章节