Go MongoDB驱动必须为所有操作设置context超时，\_id字段类型须为primitive.ObjectID并加bson:"_id,omitempty"标签，filter必须用primitive.M且字段名严格匹配bson tag，否则导致静默失败。
连接必须带 context 超时，否则程序可能卡死
Go 的 mongo-go-driver 所有操作都强依赖 context，不设超时不是“默认没限制”，而是“永远等下去”。网络抖动、DNS 失败、副本集选举期间，client.Connect() 或 collection.Find() 会无限阻塞——你看到的“没报错”其实是假成功。
- 连接阶段用
context.WithTimeout(context.Background(), 10*time.Second)，调完client.Connect(ctx)立即cancel() - 查询/写入操作别复用连接时的
ctx；读建议 5 秒起，写可设 10 秒 - 错误里出现
context deadline exceeded是正常信号，说明超时生效了，不是 bug
filter 和 update 必须用 primitive.M，别用 map[string]interface{}
用 map[string]interface{} 构造 filter 时，Go 类型推导可能把整数转成 int64 或 float64，而 MongoDB 对数字类型敏感，导致查不到数据却无报错——游标为空，cursor.Next() 返回 false，你根本不知道哪错了。
- 始终用
primitive.M{"name": "alice", "age": 25}，它明确映射为 BSON 文档 - 字段名必须和
bsontag 一致：结构体字段UserName对应bson:"user_name"就不能写成"username" - 调试时加一句
fmt.Printf("filter: %+v", filter)，确认输出结构符合预期
_id 字段类型不对，插入后 ID 是空字符串
插入新文档时，driver 默认生成 ObjectID 并写入 _id。但如果你定义结构体时把 _id 写成 string 类型，driver 不会覆盖它，结果存进去的是空字符串，后续用 primitive.ObjectIDHex() 解析直接 panic：invalid ObjectIdHex。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
_id字段类型必须是primitive.ObjectID，且加bson:"_id,omitempty"tag - 插入前别手动赋值
_id，让 driver 自动注入；如需指定，用primitive.NewObjectID() - 从 DB 读出来传给前端时，记得转成字符串：
doc.ID.Hex()；直接 JSON 序列化ObjectID会变成 base64
Find() 返回空结果却不报错？大概率是 filter 拼错了
MongoDB 的语义是：“查不到”合法，“字段不存在”也合法——所以 filter 字段名拼错、嵌套路径写法不对（比如该写 "address.city" 却写了 "address.city.name"）、类型不匹配（string 和 int 混用），它都安静返回空游标，不抛 error。
立即学习“go语言免费学习笔记（深入）”；
- 先检查
bsontag 是否和实际 collection 中字段名完全一致（大小写、下划线） - 嵌套字段用点号路径，数组字段用
$elemMatch，别直接写"tags.0" - 执行前打印
filter和真实 BSON 结构对比，比盲猜快十倍
最常被忽略的不是语法，而是 context 生命周期管理、_id 类型绑定、以及 filter 的静默失败——这三处一错，日志里找不到线索，debug 要靠猜。
