Gin与MongoDB无耦合，本质是用mongo-go-driver在HTTP处理函数中操作数据；关键在连接需带超时context、URI从环境变量读取、连接池参数显式设置、bson tag精准映射、游标必须Close、UpdateOne参数顺序不可颠倒。
直接说结论： Gin 和 MongoDB 本身不耦合，所谓“配合”，本质是用 mongo-go-driver 在 Gin 的 HTTP 处理函数里做数据操作——关键不在框架怎么写路由，而在连接怎么建、上下文怎么传、游标和资源怎么释放。
mongo.Connect() 必须带超时 context，不能用 context.Background()
常见错误是直接写 context.Background() 传给 mongo.Connect()，一旦 MongoDB 不可用，程序会卡死或 panic，且无法被上层取消。生产环境必须用带超时的 context。
- 用
context.WithTimeout(context.Background(), 10*time.Second)控制建连总耗时 - 连接成功后，
client.Ping()也得用新 context（同样带超时），不能复用 Connect 那个 - URI 不要硬编码，从环境变量读取：
os.Getenv("MONGODB_URI")，本地开发可 fallback 到"mongodb://localhost:27017" - 连接池参数建议显式设置：
options.Client().SetMaxPoolSize(20).SetMinPoolSize(5)，避免默认值在高并发下排队或浪费内存
bson tag 写错，FindOne 会静默返回 nil，不报错
Go 结构体映射 BSON 文档靠的是 bson tag，不是 json。漏写、拼错、类型不匹配，都会导致解码失败，但 err 是 nil，result 是零值，极难排查。
- ID 字段必须是
primitive.ObjectID类型，tag 写成`bson:"_id,omitempty"`—— 下划线不能少，omitempty决定插入时是否自动生成 - 时间字段必须是
time.Time，tag 如`bson:"created_at"`，不能是字符串或 int64 - 嵌套结构体每一层都要加
bsontag，否则子字段不会序列化/反序列化 - 如果手动构造查询条件（如
bson.M{"title": "Go blog"}），value 类型必须和数据库字段一致："age": 25不能写成"age": "25"
Find() 游标没 Close，goroutine 和内存会泄漏
collection.Find() 返回的是 *mongo.Cursor，它持有网络连接和内部缓冲区。不显式 Close()，哪怕函数返回，资源也不会释放。
立即学习“go语言免费学习笔记（深入）”；
- 务必在获取游标后立即 defer：
defer cursor.Close(ctx)，ctx 应该是当前请求的生命周期 context - 遍历必须先调
cursor.Next()，再cursor.Decode(&v)；跳过Next()直接Decode()会 panic - 批量结果可用
cursor.All(ctx, &results)转切片，但要注意内存占用；高并发或大数据量时，优先流式处理 - 检查游标错误要用
cursor.Err()，不能只看Next()返回值 —— 类型不匹配等解码错误，Next()可能仍返回 true
UpdateOne 的 filter 和 update 参数顺序不能颠倒
collection.UpdateOne() 第一个参数是 filter（查哪些文档），第二个是 update（怎么改），顺序反了会导致空匹配或意外覆盖。
- filter 建议用
bson.M或bson.D，例如bson.M{"_id": id} - update 必须用 MongoDB 更新操作符，如
bson.M{"$set": bson.M{"title": newTitle}}，不能直接传 struct - 更新前最好先
FindOne()验证文档存在，避免静默失败 - UpdateOne 返回的
result.MatchedCount和result.ModifiedCount要检查，确认是否真有文档被匹配和修改
最常被忽略的其实是 context 生命周期和游标释放时机——它们不出现在任何一行业务逻辑里，却决定服务能不能长期稳定跑下去。写完 CRUD 之后，先检查这两处，比优化 SQL 还重要。
