升级MongoDB Java驱动至4.6.1后，原有聚合查询因$and被误识别为非法管道阶段而失败；根本原因在于旧代码重复调用and()构造器导致生成冗余$and外层包装，新驱动严格校验阶段名所致。
升级mongodb java驱动至4.6.1后，原有聚合查询因`$and`被误识别为非法管道阶段而失败；根本原因在于旧代码重复调用`and()`构造器导致生成冗余`$and`外层包装，新驱动严格校验阶段名所致。
MongoDB Java驱动从3.x升级到4.x（尤其是4.6+）是一次重大架构演进：驱动底层全面迁移到新的MongoCollection API，同时强化了聚合管道语法校验——不再容忍非标准或嵌套不当的逻辑操作符结构。其中最典型的兼容性断裂点，就是对$and的处理方式变更。
在3.8.1及更早版本中，驱动对Filters.and(...)的使用相对宽松：即使开发者在聚合管道中误将and()返回的Bson对象直接添加为独立阶段（如pipeline.add(Filters.and(...))），驱动也可能“宽容”地尝试解析并执行。但4.6.1引入了严格的阶段名白名单校验机制，当Filters.and(...)生成的BSON文档被错误地作为顶层聚合阶段（即形如 { "$and": [...] }）加入管道时，驱动会拒绝执行，并抛出明确错误：
"Unrecognized pipeline stage name: '$and'"
⚠️ 关键误区：$and 是查询过滤器（filter）操作符，不是聚合管道的独立阶段。它只能出现在 $match 阶段内部，绝不能作为管道中的一个独立阶段。
✅ 正确做法是：将 Filters.and(...) 构造的复合条件，作为 $match 阶段的参数传入，再通过 Aggregates.match(...) 添加到管道中：
import static com.mongodb.client.model.Aggregates.*;
import static com.mongodb.client.model.Filters.*;
// ✅ 正确：将 and 过滤器封装进 match 阶段
Bson filter = and(
eq("status", "active"),
gte("createdAt", LocalDate.now().minusDays(30))
);
List<bson> pipeline = Arrays.asList(
match(filter), // ← 正确：$match 阶段内包含 $and 逻辑
project(include("name", "email"))
);</bson>
❌ 错误示例（导致报错）：
// ❌ 错误：直接 add(and(...)) —— 驱动会试图将其当作独立阶段 {$and: [...]}
pipeline.add(and(eq("status", "active"), gte("createdAt", ...))); // ⚠️ 触发 "$and" 阶段名错误
? 补充说明：若原代码使用了类似 pipeline.add(and(...)) 的写法（常见于早期不规范的聚合构建逻辑），请务必替换为 pipeline.add(match(and(...))) 或更推荐的链式写法 pipeline.addAll(Arrays.asList(match(...), ...))，确保所有过滤逻辑均置于 $match 上下文中。
? 注意事项：
- Spring Boot 2.7.10 默认依赖 MongoDB Driver 4.6.x（与您当前版本一致），因此降级驱动可能导致 ClassNotFoundException（如 MongoClientSettings 类路径变更），不应回退驱动版本；
- 检查全部聚合构建代码，除 and() 外，or()、nor()、not() 等逻辑过滤器同理，必须嵌套在 match() 中；
- 建议启用驱动日志（logging.level.org.mongodb.driver=DEBUG）观察实际发送的BSON管道，验证 $and 是否出现在 $match 内部。
升级本质是向标准靠拢。修复此问题不仅解决报错，更使代码符合MongoDB官方聚合语义规范，提升可维护性与跨版本兼容性。
