MongoDB C# Driver 在 `ElemMatch + Contains + 类型转换` 下的翻译差异

MongoDB C# Driver 在 ElemMatch + Contains + 类型转换 下的翻译差异

写在前面

这篇文章来自一次很典型、也很有代表性的线上问题排查：

• 同一段 MongoDB C# Driver 查询表达式
• 在老版本驱动里可以正常工作
• 升级到新版本驱动后，翻译出的 Mongo 查询变了
• 最终在 MongoDB 执行时报错

如果你只想先看结论，可以先记住下面 4 句话：

1. Contains 本身通常不是问题，真正危险的是 Contains 里面对 Mongo 字段做了显式类型转换。
2. 在 MongoDB.Driver 2.30.0 中，ElemMatch(... ids.Contains((int)nullableField)) 可能不再翻译成普通 $in，而会退化成 $expr。
3. $expr 放在 $elemMatch 里面会报错：$expr can only be applied to the top-level document。
4. 对可空字段，field.Value、嵌套 Filter.In(...)、或直接字段路径 In("array.field", ids)，通常都比 (int)field 更稳。

本文会从现象开始，逐层解释到驱动翻译机制，再落到工程实践和代码写法选择。无论你是：

• 只想先解决问题的业务开发
• 想理解 Mongo 查询翻译机制的中级开发
• 想看驱动版本差异和表达式树细节的高级开发

都可以按自己的深度来读。

---

1. 问题是怎么出现的

项目中的原始代码如下：

filter &= filterBuilder.ElemMatch(
    m => m.Kids4Sends,
    ks => condition.KidIds.Contains((int)ks.KidId));

对应的模型字段是：

public class MomentKids4Sends
{
    [BsonElement("id")]
    public int? KidId { get; set; }
}

也就是说：

• condition.KidIds 是 IEnumerable<int>
• ks.KidId 是 int?
• 为了让两边类型一致，代码里写了 (int)ks.KidId

从 C# 语义看，这很自然，很多人第一眼都会这么写。

但在项目当前环境中：

• MongoDB.Driver: 2.30.0
• 运行环境: .NET 8

这段代码被翻译成的 Mongo 查询片段不是我们以为的普通 $in，而是：

{
  "Kids4Sends": {
    "$elemMatch": {
      "$expr": {
        "$in": ["$id", [3013, 4201, 4205, 4206, 4207, 4212, 4216, 4217, 4218]]
      }
    }
  }
}

MongoDB 执行时报错：

$expr can only be applied to the top-level document

到这里，问题就不再是"代码逻辑对不对"，而变成了：

• 为什么驱动会这样翻译？
• 为什么老版本驱动没事？
• 为什么 .Value 可以，(int) 却不行？
• 怎么改最稳？

---

2. 先讲直观结论：问题不在 Contains，而在类型转换

很多人一看到报错，会先怀疑：

• 是不是 Contains 不能放在 ElemMatch 里？
• 是不是 ElemMatch 不支持集合判断？
• 是不是 MongoDB 不支持这种查询？

其实都不是。

真正的问题在这里：

(int)ks.KidId

这是一次对 Mongo 字段的显式类型转换。

从 C# 角度，这只是"把 int? 转成 int"。

但从 MongoDB Driver 的角度，这不再是一个纯粹的"字段访问"，而是一个"表达式计算"。

这就是后面行为分叉的根源。

---

3. 为什么 (int)ks.KidId 和 ks.KidId.Value 不一样

这一步是理解整个问题的关键。

3.1 对业务开发来说，它们很像

下面两种写法看起来都像是在"拿出 KidId 的整数值"：

ks.KidId.Value

(int)ks.KidId

在 C# 运行时语义里，它们确实很接近。

3.2 但在表达式树里，它们根本不是一类节点

MongoDB C# Driver 不是直接执行这段 lambda，而是先拿到表达式树，再把表达式树翻译成 Mongo 查询。

这两种写法在表达式树里的形态不同：

• ks.KidId.Value 是 MemberAccess
• (int)ks.KidId 是 Convert

也就是说，驱动看到的不是"两个差不多的写法"，而是：

• 前者像"访问字段的某个成员"
• 后者像"先做一次类型转换，再继续参与运算"

这个差异，会直接影响驱动能不能把它识别成一个简单的字段路径。

---

4. 为什么能翻译成普通 $in 这么重要

MongoDB 的普通字段匹配通常长这样：

{ "field": { "$in": [1, 2, 3] } }

这种写法有一个前提：

• 左边必须是一个明确的字段路径

比如：

• "id"
• "Kids4Sends.id"
• "receiverStudent.kidId"

如果驱动能够确认"这里就是字段 id"，它就可以生成这种最自然、最简单、也最稳定的查询。

但如果驱动觉得：

• 左边不是单纯字段
• 而是"字段再经过一层表达式计算"

那它就很可能不能继续走普通字段查询翻译，而是退回到"表达式求值"的路线，也就是 $expr。

所以问题的本质可以压缩成一句话：

驱动是否还能把你的写法识别为"字段路径"。

---

5. $expr 是什么，为什么它会在这里出问题

$expr 是 MongoDB 里用于"按表达式求值"的查询能力。

例如：

{
  "$expr": {
    "$gt": ["$endAt", "$startAt"]
  }
}

它和普通字段查询的区别是：

• 普通查询偏"字段匹配"
• $expr 偏"表达式计算"

这次驱动生成的是：

{
  "$expr": {
    "$in": ["$id", [...]]
  }
}

意思是：

• 先取当前上下文里的 $id
• 再判断它是否属于某个数组

这在"顶层文档查询"里是成立的。

但当前场景不是顶层，而是在：

{
  "Kids4Sends": {
    "$elemMatch": {
      ...
    }
  }
}

MongoDB 对这里的限制是：

$expr can only be applied to the top-level document

所以不是说这个 $expr 永远不合法，而是：

它被放错了位置。

---

6. 为什么老驱动可以，新驱动不行

这是本次排查里最容易让团队困惑的地方。

因为直觉上大家会以为：

• "是不是 Contains 翻译器改了？"
• "是不是 ElemMatch 行为改了？"

实际更接近的原因是：

• Contains 相关逻辑不是关键变化点
• 真正变化更大的是字段翻译阶段对 Convert 的容忍度

6.1 在 2.15.1 + .NET 6 下

同样的写法：

builder.ElemMatch(m => m.Kids4Sends, ks => kidIds.Contains((int)ks.KidId))

最终可以被翻译成普通 $in：

{
  "Kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [3013, 4201, 4205] }
    }
  }
}

也就是说，老版本驱动对这种"Nullable<int> -> int 的转换"更宽松，最终还是把它认成了字段。

6.2 在 2.30.0 + .NET 8 下

同样的写法会变成：

{
  "Kids4Sends": {
    "$elemMatch": {
      "$expr": {
        "$in": ["$id", [3013, 4201, 4205]]
      }
    }
  }
}

说明新版本驱动对这种 Convert 更严格了：

• 它不再愿意把 (int)nullableField 继续视为简单字段路径
• 一旦无法保持为字段路径，就只能退回表达式语义

6.3 这不是"忽略了强转"

有时大家会问：

老驱动是不是直接忽略了 (int)？

更准确的说法不是"忽略"，而是：

老驱动把这个转换视为一个仍然可以折叠回字段路径的转换。

也就是它认为：

• 这个转换没有改变底层 BSON 字段定位方式
• 所以还可以继续翻译成 id.$in

而新驱动则更谨慎，不再轻易这么处理。

---

7. 为什么 .Value 在新驱动里还能工作

这也是一个非常值得单独讲清楚的点。

7.1 .Value 并不等于 (int)

尽管业务含义看起来接近，但驱动内部对它们不是同一个分支处理。

condition.KidIds.Contains(ks.KidId.Value)

在 2.30.0 中仍然可以翻译成：

{
  "Kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [...] }
    }
  }
}

7.2 原因是驱动对 Nullable<T>.Value 有专门处理

从行为上看，可以理解为：

• .Value 仍然被当成"字段访问的延续"
• 驱动还能沿着 KidId -> id 这条路径往下翻译

而 (int)ks.KidId 则被识别成：

• 不是字段访问
• 而是一层显式转换表达式

所以：

• .Value 更容易保留"字段路径语义"
• (int) 更容易丢失"字段路径语义"

---

8. 用最小 Demo 看懂差异

下面给一个可以独立理解的最小模型：

public class Moment
{
    [BsonElement("Kids4Sends")]
    public MomentKids4Sends[] Kids4Sends{ get; set; } = Array.Empty<MomentKids4Sends>();
}

public class MomentKids4Sends
{
    [BsonElement("id")]
    public int? KidId { get; set; }
}

测试代码：

var kidIds = new[] { 3013, 4201, 4205 };
var builder = Builders<Moment>.Filter;

var a = builder.ElemMatch(
    m => m.Kids4Sends,
    ks => kidIds.Contains((int)ks.KidId!));

var b = builder.ElemMatch(
    m => m.Kids4Sends,
    ks => kidIds.Contains(ks.KidId.Value));

var c = builder.ElemMatch(
    m => m.Kids4Sends,
    Builders<MomentKids4Sends>.Filter.In(k => k.KidId, kidIds.Cast<int?>()));

var d = builder.In("kids4Sends.id", kidIds);

8.1 在 2.30.0 + .NET 8 下

a：

{
  "kids4Sends": {
    "$elemMatch": {
      "$expr": {
        "$in": ["$id", [3013, 4201, 4205]]
      }
    }
  }
}

b：

{
  "kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [3013, 4201, 4205] }
    }
  }
}

c：

{
  "kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [3013, 4201, 4205] }
    }
  }
}

d：

{
  "kids4Sends.id": { "$in": [3013, 4201, 4205] }
}

8.2 在 2.15.1 + .NET 6 下

a、b、c、d 都可以正常翻译成普通 $in，不会产生 $expr。

这说明问题不是 MongoDB 本身不支持，而是驱动不同版本对表达式的翻译策略不同。

---

9. 不同写法分别代表什么语义

这是工程实践里特别重要的一节。

很多问题不是"哪种写法能跑"，而是"哪种写法表达了最准确的意图"。

下面看几种常见改法。

写法 1：直接写字段路径

filter &= filterBuilder.In("kids4Sends.id", kidIds);

翻译结果：

{ "kids4Sends.id": { "$in": [...] } }

优点：

• 最直接
• 最稳定
• 最不依赖驱动对复杂表达式的理解

缺点：

• 用了字符串路径
• 重构时不如强类型安全
• 字段名如果改了，编译器不会提醒

适用场景：

• 条件简单
• 只需要判断数组子项中某个字段是否命中
• 团队优先考虑稳定性和可预期性

写法 2：保留 lambda，但改成 .Value

filter &= filterBuilder.ElemMatch(
    m => m.Kids4Sends,
    ks => kidIds.Contains(ks.KidId.Value));

翻译结果：

{
  "kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [...] }
    }
  }
}

优点：

• 仍然是强类型表达式
• 从业务视角易读
• 在 2.30.0 下当前可正常翻译

缺点：

• 写了 .Value，语义上默认假定这里非 null
• 如果以后同一条件继续扩展，仍然可能受 LINQ 翻译细节影响

适用场景：

• 字段实际上允许为 null，但当前业务已经能保证不会用 null 命中
• 团队希望保持 lambda 风格

写法 3：嵌套使用强类型 Filter.In(...)

filter &= filterBuilder.ElemMatch(
    m => m.Kids4Sends,
    Builders<MomentKids4Sends>.Filter.In(k => k.KidId, kidIds.Cast<int?>()));

翻译结果：

{
  "kids4Sends": {
    "$elemMatch": {
      "id": { "$in": [...] }
    }
  }
}

优点：

• 强类型
• 不依赖 (int) 或 .Value
• 明确表达"对子文档字段做 Mongo 原生过滤"
• 如果以后要在同一个子元素上继续叠加多个条件，更容易保持语义一致

缺点：

• 代码比写法 1 略长
• 对不熟 Mongo Driver API 的开发者来说，可读性不如最简单的字段路径法

适用场景：

• 希望兼顾强类型和稳定翻译
• 未来可能继续对同一个 Kids4Sends 元素增加多个条件

---

10. 写法 1 和 写法 3，除了强类型还有什么差别

这个问题非常适合进阶读者。

很多人会问：

如果当前只是查 id in (...)，那写法 1 和写法 3 不就是一样的吗？

答案是：

• 在当前这个单条件场景下，实际效果基本等价
• 但在"后续维护和语义扩展能力"上，它们仍有差别

10.1 当前单条件时，效果确实几乎一样

以下两种写法在这次场景中都能正确筛出：

• kids4Sends 数组中，存在某个元素的 id 在集合内

所以如果只看当前结果，二者没有本质业务差异。

10.2 扩展到"同一个数组元素必须同时满足多个条件"时，差别就出来了

例如未来想表达：

• KidId 在指定集合里
• 并且 IsFavorite == true
• 并且 ReadAt == null

如果你继续走 ElemMatch + 子 Filter，会很自然：

filter &= filterBuilder.ElemMatch(
    m => m.Kids4Sends,
    Builders<MomentKids4Sends>.Filter.And(
        Builders<MomentKids4Sends>.Filter.In(k => k.KidId, kidIds.Cast<int?>()),
        Builders<MomentKids4Sends>.Filter.Eq(k => k.IsFavorite, true),
        Builders<MomentKids4Sends>.Filter.Eq(k => k.ReadAt, null)));

这明确表达的是：

同一个 Kids4Sends 元素必须同时满足所有条件。

而如果习惯性写成多个点路径条件：

filter &= filterBuilder.In("kids4Sends.id", kidIds);
filter &= filterBuilder.Eq("kids4Sends.isFavorite", true);
filter &= filterBuilder.Eq("kids4Sends.readAt", BsonNull.Value);

那语义就未必还是"同一个元素同时满足"，而可能变成：

• 一个元素满足 id
• 另一个元素满足 isFavorite
• 第三个元素满足 readAt

这在数组子文档查询里是非常常见的维护陷阱。

所以从长期可维护性看：

• 写法 1 更像"快速、稳定、简单"
• 写法 3 更像"强类型、可扩展、语义边界更清楚"

---

11. 这个问题在代码里是不是到处都有

我们针对做过一轮静态排查，重点看了：

• ElemMatch(...)
• Find / CountDocumentsAsync / Match(...) 里的 Contains(...)
• 查询表达式中的 (int)、.Value
• 是否属于 Mongo Driver 翻译，而不是 EF 或内存 LINQ

结论是：

当前里，已确认和这次完全同类的问题，只有 Moment 这一处原始写法。

但这不代表其他地方完全没有风险。更准确的理解是：

• 不是所有 Contains 都危险
• 不是所有 ElemMatch 都危险
• 只有当"Mongo 查询表达式 + 可空字段 + 显式数值转换"这几个条件叠加时，风险才明显上升

11.1 当前看起来安全的典型场景

下面这些场景通常没问题：

• 顶层标量字段 Contains(x.KidId)，且 KidId 本身就是 int
• ElemMatch(... Filter.In(...))
• ElemMatch(... field.Value)，且驱动当前能稳定识别

11.2 真正要警惕的模式

如果以后在 Mongo 查询里看到下面这种形式，要立刻多看一眼：

ids.Contains((int)doc.NullableIntField)

尤其是出现在：

• ElemMatch(...)
• Any(...)
• Where(...)
• Match(...)

里面时，更值得警觉。

---

12. 如何设计一套更稳的团队写法规范

如果把这次问题上升到团队规范层面，我建议至少明确下面几条。

12.1 不要在 Mongo 查询表达式里随手对字段做显式强转

特别是：

(int)nullableField

(long)nullableField

(int)arrayElement.SomeNullableId

这些在 C# 里很顺手，但在 Driver 翻译层面不一定稳。

12.2 对数组子文档过滤，优先考虑两种写法

简单场景优先：

filterBuilder.In("kids4Sends.id", kidIds)

需要强类型和扩展能力时优先：

filterBuilder.ElemMatch(
    m => m.Kids4Sends,
    Builders<MomentKids4Sends>.Filter.In(k => k.KidId, kidIds.Cast<int?>()))

12.3 如果必须使用 .Value，要先确认业务上 null 是否可接受

.Value 在翻译上可能更稳，但它表达的是：

我认为这里应该有值

如果业务上 null 是一种真实状态，就要明确这种写法是否会误导维护者。

12.4 升级 MongoDB Driver 后，要关注"翻译结果是否变化"

很多团队升级依赖时只看：

• 编译是否通过
• 单测是否通过

但对 MongoDB C# Driver 这种"表达式翻译器"型依赖，建议额外关注：

• 同一段 lambda 翻译出的 BSON 是否变化
• 尤其是数组、可空值、Any/Contains/Convert 组合场景

---

13. 给不同层级读者的总结

如果你是初级开发

记住一句话就够了：

Mongo C# Driver 看到的不是你"想表达什么"，而是你"具体怎么写表达式"。

(int)ks.KidId 和 ks.KidId.Value 在你眼里差不多，在驱动眼里可能完全不是一回事。

如果你是中级开发

要建立一个意识：

查询表达式不是普通业务代码，它是"会被翻译"的代码。

一旦代码要被翻译：

• 表达式树节点类型
• 可空值处理
• 驱动版本差异

都可能影响最终查询结果。

如果你是高级开发或架构师

这次案例很适合作为团队规范的一个缩影：

• 不要把"C# 语义正确"等同于"Mongo 翻译稳定"
• 对会被翻译的表达式，优先选择"更接近目标查询语言"的写法
• 在依赖升级时，把"查询翻译回归"纳入风险评估

---

14. 最后的工程建议

如果你现在就要给团队一个简单可执行的建议，我会这么写：

1. 在 MongoDB C# Driver 查询里，避免写 Contains((int)nullableField)。
2. 对数组子文档过滤，简单场景优先用字段路径 In("array.field", ids)。
3. 如果需要强类型和更强的后续扩展能力，优先用 ElemMatch + 子 Filter.In(...)。
4. 升级 MongoDB.Driver 时，对 ElemMatch / Any / Contains / Nullable / Convert 组合场景做最小回归测试。

---

附录 1：本文核心示例代码

var kidIds = new[] { 3013, 4201, 4205 };
var builder = Builders<Moment>.Filter;

var problematic = builder.ElemMatch(
    m => m.Kids4Sends,
    ks => kidIds.Contains((int)ks.KidId!));

var valueVersion = builder.ElemMatch(
    m => m.Kids4Sends,
    ks => kidIds.Contains(ks.KidId.Value));

var nestedFilterVersion = builder.ElemMatch(
    m => m.Kids4Sends,
    Builders<MomentKids4Sends>.Filter.In(k => k.KidId, kidIds.Cast<int?>()));

var pathVersion = builder.In("kids4Sends.id", kidIds);

---

附录 2：一句话版结论

在 MongoDB.Driver 2.30.0 中，ElemMatch 里对 int? 字段写 Contains((int)field)，可能让驱动失去"字段路径"识别能力，从普通 $in 退化成 $expr，最终在 $elemMatch 中报错；而 .Value、子 Filter.In(...)、或直接字段路径写法通常更稳。