必须用 mongo-go-driver，因其是官方唯一维护驱动，支持最新 mongodb 版本及 vector search 等新特性；mgo 已归档，不支持事务、change streams、tls 1.3 和 scram-sha-256 认证，2026 年起连不上 mongodb ≥ 5.0。
用 mongo-go-driver 连接 MongoDB，别碰旧版 mgo
现在 Iris 框架本身不封装数据库驱动，集成 MongoDB 的核心就是选对 Go 官方驱动：mongo-go-driver。mgo 已停更多年，用它在 Go 1.22+ 环境下大概率编译失败或连不上 6.x+ 版本的 MongoDB。官方驱动支持连接字符串、超时控制、上下文取消，和 Iris 的 context.Context 天然契合。
常见错误现象：
-
undefined: mgo.Dial—— 说明你还在引用已废弃的mgo - 连接后写入卡住、无报错但数据没进库 —— 很可能是没调用
collection.InsertOne(ctx, doc)中的ctx，或没设超时
实操建议：
- 执行
go get go.mongodb.org/mongo-driver/mongo和go get go.mongodb.org/mongo-driver/bson - 连接时务必传入带超时的
context，例如ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) - 不要把
*mongo.Client存为全局变量后反复Connect()；应只初始化一次，复用 client 实例
Iris 中间件里挂载 MongoDB client 最稳妥
把数据库连接实例注入到 Iris 请求生命周期里，比在每个 handler 里手动取 client 更可控。Iris 的 app.Use 或 app.ConfigureContainer（v12.2.11+）都支持依赖注入，但最轻量、无侵入的做法是用中间件往 ctx.Values() 塞 client。
使用场景：
- 需要按请求隔离数据库操作（比如多租户场景下动态切换 database name）
- 想统一做连接健康检查或日志埋点
- 避免 handler 内部 new client 导致连接泄露
示例片段（非完整代码，仅示意关键链路）：
app.Use(func(ctx iris.Context) {
client := app.Logger().Get("mongo-client").(*mongo.Client) // 假设已存入 app.Logger()
ctx.SetValues(map[string]interface{}{"mongo": client})
ctx.Next()
})
<p>app.Get("/user/{id}", func(ctx iris.Context) {
client := ctx.Values().Get("mongo").(*mongo.Client)
collection := client.Database("mydb").Collection("users")
id := ctx.Params().Get("id")
var user User
collection.FindOne(ctx.Request().Context(), bson.M{"_id": id}).Decode(&user)
ctx.JSON(user)
})</p>
写入前必须注册 BSON 编解码器，否则 struct 字段全空
Go struct 默认不会自动映射到 BSON 字段名，mongo-go-driver 不会读取 json: tag，必须显式用 bson:。如果漏掉，插入文档时所有字段都是空值或零值，查出来也是空对象，但没有任何报错。
参数差异：
-
json:"name"→ 只影响 JSON 序列化，对 MongoDB 无效 -
bson:"name"→ 驱动写入/读取 BSON 时使用的字段名 -
bson:"name,omitempty"→ 字段为空值时不写入文档（推荐用于可选字段）
典型结构体写法：
type User struct {
ID primitive.ObjectID `bson:"_id,omitempty" json:"id,omitempty"`
Name string `bson:"name" json:"name"`
Email string `bson:"email" json:"email"`
CreatedAt time.Time `bson:"created_at" json:"created_at"`
}
别忽略连接池和超时配置，本地开发也得设
默认连接池大小是 100，看起来够用，但如果你在本地启动 MongoDB 用的是 mongod --dbpath ../blog/ 这种单节点模式，又没配 SetMaxPoolSize，高并发压测时容易触发 context deadline exceeded。这不是网络问题，是驱动等不到空闲连接。
性能 / 兼容性影响：
- 不设
ConnectTimeout：首次连接失败会卡满默认 30 秒 - 不设
SocketTimeout：一次慢查询可能拖垮整个 handler - 不调
SetMaxPoolSize：本地小内存机器上容易 OOM 或假死
建议初始化 client 时加这些配置：
client, err := mongo.Connect(ctx, options.Client().
ApplyURI("mongodb://localhost:27017").
SetConnectTimeout(5 * time.Second).
SetSocketTimeout(10 * time.Second).
SetMaxPoolSize(20).
SetMinPoolSize(5))
真正容易被忽略的是：BSON 字段名大小写必须和 struct tag 严格一致，MongoDB 本身区分大小写，而很多开发者复制示例时只改了 struct 字段名，忘了同步改 bson: tag，结果查不到数据还怀疑是查询逻辑错了。
