结论：gin本身不处理数据库，整合mongodb的核心是mongo-go-driver的正确使用；gin只负责把http请求参数转成bson.m或结构体，再交给driver执行查询——错配context、漏写bson tag、游标不close，这三类问题占线上故障的70%以上。
直接说结论：Gin 本身不处理数据库，整合 MongoDB 的核心是 mongo-go-driver 的正确使用；Gin 只负责把 HTTP 请求参数转成 bson.M 或结构体，再交给 driver 执行查询——错配 context、漏写 bson tag、游标不 Close，这三类问题占线上故障的 70% 以上。
怎么建立安全可靠的 MongoDB 连接
连接不是“连上就行”，生产环境必须控制超时、复用和验证时机：
-
mongo.Connect()必须传带超时的context.WithTimeout(ctx, 10*time.Second)，不能用context.Background()或context.TODO() - URI 从环境变量读取：
os.Getenv("MONGODB_URI")，避免硬编码"mongodb://localhost:27017" -
client.Ping()要用新 context（context.WithTimeout），且必须在defer client.Disconnect(ctx)前执行 - 连接池参数建议显式设置：
options.Client().SetMaxPoolSize(20).SetMinPoolSize(5)，QPS 高时需按响应时间调整
结构体字段 tag 写错会导致查询静默失败
Go 结构体映射 BSON 不靠 json tag，只认 bson tag；写错或漏掉，FindOne().Decode() 会成功但字段为空，不报错也不提示：
- ID 字段必须用
primitive.ObjectID类型 +bson:"_id,omitempty"，下划线不能少，“omitempty”决定插入时是否自动生成 - 时间字段只能是
time.Time，tag 写成bson:"created_at"，不能是字符串或 int64 - 嵌套结构体每一层都要加
bsontag，否则子字段不会被序列化进 BSON - 如果用
bson.M{"name": "alice"}查询，value 类型必须与库中字段一致——"age": 25不能写成"age": "25"
游标没 Close 是 goroutine 泄漏的常见源头
Collection.Find() 返回的是 *mongo.Cursor，它持有底层连接和缓冲区，不主动释放就会持续占用资源：
- 必须在函数入口处
defer cursor.Close(ctx)，ctx 应为当前请求生命周期的 context（不是 Connect 时那个） - 遍历必须先调
cursor.Next()，再cursor.Decode(&item)；跳过Next()直接Decode()会 panic - 批量结果用
cursor.All()简单，但内存压力大；高并发场景推荐for cursor.Next() { ... }流式处理 -
cursor.Err()才反映解码错误（如类型不匹配），仅检查Next()返回值会漏掉这类问题
用 c.BSON() 直接返回 BSON 文档要小心兼容性
Gin 1.12+ 提供了 c.BSON() 方法，能省去 JSON 序列化开销，但有明确限制：
- 只适用于 Go struct 映射到 BSON 的场景，且所有字段必须有合法
bsontag，否则部分字段丢失 - 前端必须能解析
application/bsonMIME 类型，浏览器原生不支持，通常只用于微服务间通信 - 无法自动处理
primitive.ObjectID的字符串化（比如前端需要 ID 是字符串而非 BSON ObjectId），仍需手动转换 - 若结构体含
time.Time，BSON 中存的是 UTC 时间戳，前端解析时注意时区
最常被忽略的其实是 context 生命周期管理：Connect 用的 context 控制建连超时，Ping 和查询用的 context 控制操作超时，游标 Close 用的 context 必须是请求级——混用或复用同一 context 实例，会在高负载下引发连接卡死或泄漏。
