Spring MongoDB 多重 $or 条件查询的正确实现方式

在 spring data mongodb 中，直接多次调用 `addcriteria()` 添加多个 `$or` 子句会触发底层 `basicdocument` 的限制报错；正确做法是将各 `$or` 条件封装为独立 `criteria` 对象，再通过 `andoperator()` 组合，最终一次性构建完整查询。

Spring Data MongoDB 提供了高度抽象的 Criteria API，但其底层仍受限于 MongoDB 驱动对 BSON 文档结构的约束——一个文档中不能存在多个同名操作符（如多个 $or）作为顶层字段。你遇到的错误：

Due to limitations of the com.mongodb.BasicDocument, you can't add a second '$or' expression

正是因为在 Query 中连续调用 addCriteria() 时，框架试图将两个独立的 $or 表达式并列写入同一级 BSON 对象，违反了 MongoDB 查询语法规范。

✅ 正确实现方式是：将每个逻辑组（如 $or）封装为独立 Criteria 实例，再用 Criteria.andOperator(...) 将其组合为单一根条件。对应你原始的 MongoDB 原生查询：

{ 
  "$and": [ 
    { "$or": [ { "field1": "value1" }, { "field2": "value2" } ] }, 
    { "$or": [ { "field3": "value3" }, { "field3": null }, { "field3": { "$exists": true } } ] } 
  ] 
}

应转换为以下 Java 代码：

Criteria firstOr = new Criteria().orOperator(
    Criteria.where("field1").is("value1")
,
    Criteria.where("field2").is("value2")
);

Criteria secondOr = new Criteria().orOperator(
    Criteria.where("field3").is("value3"),
    Criteria.where("field3").isNull(),              // 推荐写法：isNull() 等价于 is(null)
    Criteria.where("field3").exists(true)          // 注意：exists(true) 表示字段存在（非 null 且有定义）
);

Criteria finalCriteria = new Criteria().andOperator(firstOr, secondOr);
Query query = new Query(finalCriteria);

⚠️ 关键注意事项：

• Criteria.where("field3").is(null) 应优先使用 isNull()，语义更清晰且兼容性更好；
• exists(false) 表示“字段不存在”，而你原生查询中写的是 { "field3": { "$exists": true } }，因此应使用 exists(true)；
• 不要链式调用 .orOperator() 或 .andOperator() 在已有 Criteria 上——它仅用于创建新 Criteria，而非追加条件；
• 若需动态构建复杂条件，可将多个 Criteria 存入 List，再传入 andOperator(list.toArray(new Criteria[0]))。

最后，执行查询只需：

List results = mongoTemplate.find(query, MyDocument.class, "collectionName");

这种结构化构建方式不仅规避了驱动限制，还提升了代码可读性与可维护性，是 Spring Data MongoDB 处理复合逻辑查询的标准实践。