必须传 context、uri 编码密码、调用 client.ping 验证连通性：密码含 @ / 等特殊字符需 url 编码（如 pa%40ss%2fword），mongo.connect 必须用 context.withtimeout 包裹，返回 client 后立即执行 client.ping(ctx, nil) 才真正完成 tcp 握手与认证。
别用 mgo，现在连不上 MongoDB ≥ 5.0；所有操作必须传 context，否则可能卡死或超时失控。
连接前必须做三件事：URI 编码、client.Ping、带 timeout 的 mongo.Connect
密码含特殊字符（如 @、/）的 URI 不做 URL 编码，mongo.Connect 会静默失败，日志里只报“invalid URI”，不提示具体哪错。
mongo.Connect 返回 client 后，必须立刻调用 client.Ping(ctx, nil) 验证连通性——它才是真正发起 TCP 握手并验证认证的步骤，光 connect 不等于能用。
mongo.Connect 必须用 context.WithTimeout 包一层，不能直接传 context.Background() 或 context.TODO()，否则 DNS 解析卡住、网络抖动时整个 goroutine 就挂死了。
- URI 示例（密码
pa@ss/word）应编码为mongodb://user:pa%40ss%2Fword@host:27017 - 连接代码片段中常见错误写法：
mongo.Connect(context.TODO(), opts)→ 改成ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second); defer cancel(); mongo.Connect(ctx, opts) - 没调
Ping就直接查数据，遇到 TLS 认证失败或权限不足时，错误常被吞成context deadline exceeded，误导你去调超时时间
InsertOne 后怎么拿到新文档的 _id？别读原始 struct
Go 结构体字段如果首字母小写（比如 type User { id string }），即使加了 bson:"_id" tag，InsertOne 也不会写入 _id 字段，MongoDB 会自动生成一个，但你完全拿不到。
InsertOneResult.InsertedID 是唯一可靠来源，类型是 interface{}，实际通常是 primitive.ObjectID，需要断言转换。
- 结构体字段名必须首字母大写：
ID string `bson:"_id,omitempty"` - 插入后取 ID 正确写法：
res, _ := collection.InsertOne(ctx, doc); id := res.InsertedID.(primitive.ObjectID) - 如果直接从插入前的
doc变量里读doc.ID，值仍是空字符串或零值——因为 BSON 序列化时跳过了未导出字段
UpdateOne 不报错 ≠ 更新成功：检查 MatchedCount 和过滤器写法
UpdateOne 找不到匹配文档时默认不 panic，返回 MatchedCount: 0，新手常以为“更新成功”只是没改到数据，其实是过滤器写错了。
过滤器不能用 map[string]interface{}，得用 bson.M 或 bson.D——前者是 map，后者是有序 slice，对涉及数组位置操作（如 $[i]）必须用 bson.D。
- 查
_id必须转类型：bson.M{"_id": primitive.ObjectIDHex("64a1b2c3d4e5f67890123456")}，传字符串会匹配失败（BSON 类型不等） - 更新后务必检查：
if result.MatchedCount == 0 { log.Printf("no doc matched filter: %+v", filter) } - 字段名拼错、大小写不一致、嵌套路径漏点号（如该写
"profile.email"却写了"profileemail"）都会导致MatchedCount == 0
Find 后不 cursor.Close 会泄漏 goroutine 和内存
collection.Find 返回的 *mongo.Cursor 是有状态资源，底层持有网络连接和缓冲区。不显式 cursor.Close(ctx)，哪怕函数 return 了，goroutine 也会卡在等待下一批数据，最终拖垮连接池。
cursor.Decode 必须传指针，否则解码失败且不报错，结果 slice 里全是零值。
- 正确模式：
defer cursor.Close(ctx)放在Find后立刻执行 - 解码单条：
var doc MyStruct; if err := cursor.Decode(&doc); err != nil { ... } - 循环解码必须每次新建变量或重置指针，复用同一个变量地址会导致后续 decode 覆盖前值
最易被忽略的是：所有操作都依赖 context 生命周期。一个 HTTP handler 里传进来的 ctx 如果被 cancel 了，正在跑的 Find 或 UpdateOne 会立刻中断——这不是 bug，是设计，但如果你没处理好 error 分支，就变成“请求没响应也不报错”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
