必须用 $set 而非直接传新文档更新单个字段，因后者会清空原文档除 _id 外所有字段；$set 仅修改指定字段且自动创建不存在字段，支持嵌套路径、原子操作及 java driver 安全构建。
$set 是更新单个字段最直接、最安全的方式，别用 replaceOne() 或全量写入。
为什么必须用 $set 而不是直接传新文档
直接把整个文档当第二个参数传给 updateOne()，等价于 replaceOne()：它会删掉原文档所有字段（除了 _id），只保留你传进去的那些字段。哪怕你只改一个 status，其他 20 个字段也会被清空。
而 $set 只动你指定的字段，其余一概不动：
db.users.updateOne(
{ _id: ObjectId("...") },
{ $set: { status: "active" } }
)
- 如果
status字段原来不存在，$set会自动创建它 - 如果文档里还有
name、email、created_at等字段，全部保留 - 不加
$set包裹的写法（如{ status: "active" }）是替换语义，不是更新
updateOne() 和 updateMany() 的关键区别
两者语法完全一致，但行为边界必须清楚：
-
updateOne()：只改第一个匹配的文档，哪怕有 100 条{ type: "order" }，也只动第 1 条 -
updateMany()：所有匹配的都改，适合批量修正错误值，比如{ $set: { is_archived: true } }批量归档 - 误用
updateMany()却只打算改一条，后果通常是数据大面积错乱，且不可逆 - 执行前务必先用
find()验证筛选条件是否精准，例如：db.orders.find({ order_id: "ORD-789" }).count()
常见踩坑点：字段路径、嵌套对象和原子性
更新嵌套字段时，点号（.）必须写对，MongoDB 不会自动创建中间层级：
// ✅ 正确：user.profile.phone 存在才可更新
{ $set: { "user.profile.phone": "+123" } }
// ❌ 错误：如果 user.profile 本身是 null 或缺失，这行操作静默失败
{ $set: { "user.profile.phone": "+123" } }
- 更新数组内某个元素，要用位置索引或
$[<identifier>]</identifier>过滤器，不能靠直觉写tags.0就完事 -
$set操作是原子的，但多个$set字段之间不保证执行顺序——不过这对结果没影响，因为都是并行赋值 - 时间字段推荐用
$currentDate而非手动传new Date()，避免客户端时钟偏差
Java Driver 里怎么写 $set
别拼 BSON 文档字符串，用 Updates.set() 构建更安全：
collection.updateOne(
Filters.eq("_id", id),
Updates.set("status", "processed")
);
-
Updates.set("a.b.c", value)自动处理嵌套路径 - 如果要同时设多个字段，用
Updates.combine(Updates.set(...), Updates.set(...)) - 避免手写
Document.parse("{ $set: { ... } }")，容易漏括号、引号、大小写 - 注意
setOnInsert()和set()行为不同：前者只在 upsert 插入时生效，更新时不触发
真正容易被忽略的是：更新操作默认不返回新文档，只返回 matched_count 和 modified_count。如果你需要确认改后的值，要么再查一次，要么用 findOneAndUpdate() 并显式设 returnDocument = ReturnDocument.AFTER ——但这个方法有性能开销，别滥用。
