go官方mongodb驱动严格区分“查无结果”与“出错”，findone()查无结果返回nil *mongo.singleresult但err为nil，须调用result.err()判断；primitive.m不可与map[string]interface{}混用；结构体需bson tag；time.time字段须保持原类型；insertmany()不填充_id，需手动赋值；连接字符串timeout仅作用于初始连接，操作级超时须用带deadline的context。
Go 官方 MongoDB 驱动（mongo-go-driver）不是“教程友好型”库——它不封装业务逻辑，也不自动处理空值或类型转换；直接照搬 Python 或 Node.js 的写法会卡在 context、interface{} 和 primitive.M 上。
为什么 collection.FindOne() 返回 nil 却没报错？
这是最常被误读的点：Go 驱动把“查无结果”和“发生错误”严格区分开。FindOne() 在文档不存在时返回 nil 的 *mongo.SingleResult，但错误只在真正出问题（如网络断开、权限不足）时才非 nil。
- 必须显式调用
err := result.Err()才能知道是“没找到”还是“出错了” - 不能只判
if result == nil就认为失败；更不能跳过result.Decode(&v)前的err检查 - 典型错误现象：
panic: runtime error: invalid memory address—— 因为对nil的result直接调用了Decode
primitive.M 和 map[string]interface{} 能混用吗？
不能。虽然看起来一样，但 primitive.M 是 map[string]interface{} 的类型别名，且驱动内部做了字段顺序、nil 处理、时间/二进制等类型的特殊编码。混用会导致写入字段丢失、时间戳变零值、甚至 WriteException。
- 查询/更新一律用
primitive.M{"name": "alice", "age": 30}，别用map[string]interface{} - 结构体字段要映射到 BSON 字段？加
bson:"name"tag，比如Name string `bson:"name"` - 插入含
time.Time的结构体时，确保字段类型是time.Time（不是string），否则驱动不会自动转成 BSON Date
如何安全地批量插入并拿到所有 _id？
InsertMany() 不会自动填充传入切片中结构体的 _id 字段——它只返回新生成的 _id 列表，你需要自己关联回原始数据。
立即学习“go语言免费学习笔记（深入）”；
- 如果结构体里没定义
ID primitive.ObjectID `bson:"_id,omitempty"`字段，插入后你根本拿不到那个_id对应哪条记录 - 正确做法：插入前手动赋值
doc.ID = primitive.NewObjectID()，再传给InsertMany()；这样既能控制 ID 生成时机，又能反向追溯 - 注意：
InsertMany()默认不事务，1000 条失败会回滚全部；如需部分成功，得用unordered: true选项（通过options.InsertMany().SetOrdered(false)）
连接字符串里的 timeout 参数到底管什么？
它只控制初始连接建立阶段的超时，不是查询或写入的超时。很多线上问题（如偶尔卡死在 collection.Find()）其实是没设操作级 context，导致请求无限挂起。
- 连接字符串里的
connectTimeoutMS=5000只影响mongo.Connect()这一步 - 每个操作都必须带带 deadline 的
context，例如：ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) - 忘记 cancel context？可能引发 goroutine 泄漏；尤其在 HTTP handler 里，要用
defer cancel()
真正麻烦的从来不是语法——而是 MongoDB 的松散模式遇上 Go 的强类型约束时，那些没显式声明、没检查错误、没设 context 的“默认行为”。
