mongodb java 驱动在执行 `updates.set()` 时，会将字段值中以 `$` 开头的字符串误判为聚合表达式操作符（如 `$sum`、`$concat`），导致更新失败；需使用 `$literal` 显式声明其为字面量字符串。
在 MongoDB 的 Java 驱动中，Updates.set("field", value) 方法看似简单直接，但当 value 是一个以 $ 字符开头的字符串（例如 "$300k"、"$pending" 或 "$2024-01-01"）时，驱动会自动尝试将其解析为聚合表达式——这是底层 BSON 序列化逻辑为兼容更新管道（如 updateOne(filter, update, new UpdateOptions().upsert(true) 配合聚合式更新）而设计的行为。由于 "$300k" 并非合法的 MongoDB 操作符，驱动抛出 IllegalArgumentException 或服务端返回 InvalidPipelineOperator 错误，最终更新失败。
✅ 正确做法是：显式包裹为 $literal 表达式，告知 MongoDB “此值应作为纯字符串字面量处理，而非操作符”。
✅ 推荐写法（两种等效方式）
方式一：使用 Filters.eq("$literal", ...)（语义清晰，推荐）
import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Updates.*;
List<Bson> updates = new ArrayList<>();
updates.add(set("income", eq("$literal", "$300k"))); // ← 关键：用 eq 包装 $literal
UpdateOptions options = new UpdateOptions().upsert(true);
UpdateResult result = collection.updateOne(
eq("id", 123456),
updates,
options
);方式二：手动构建 Document
import org.bson.Document;
updates.add(set("income", new Document("$literal", "$300k")));? 提示：Filters.eq("$literal", val) 在此处并非用于查询匹配，而是利用其底层 Document 构造能力生成 { "$literal": "$300k" } —— 这是官方文档认可的惯用写法（见 MongoDB Java Driver 文档 - $literal）。
⚠️ 注意事项
- ❌ 不要尝试转义 $（如 "\$300k"），BSON 层不识别 Java 字符串转义，无效；
- ❌ 不要使用 Updates.set("income", "$$300k")，双 $ 在聚合上下文中表示变量引用，仍会触发解析；
- ✅ 所有以 $ 开头的字符串值（包括 "$null"、"$undefined"、"$true" 等）均需 $literal 保护；
- ✅ 该规则适用于 set、setOnInsert、addToSet 等所有写入操作中的值字段；
- ✅ 若更新逻辑涉及动态值，建议封装工具方法统一处理：
public static Bson literal(String value) { return new Document("$literal", value); } // 使用：set("note", literal("$Urgent"))
✅ 验证效果
执行后，数据库中对应文档将准确存储：
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
{ "id": 123456, "income": "$300k" }而非被忽略、报错或意外解析为表达式。
立即学习“Java免费学习笔记（深入）”；
总之，$literal 不是“绕过限制的技巧”，而是 MongoDB 原生设计的语义明确的字面量声明机制。在 Java 驱动中主动使用它，既是解决 $ 开头字符串问题的标准方案，也是编写健壮、可维护数据操作代码的专业实践。
