推荐使用官方 mongo-go-driver 连接 Iris,因其支持 TLS/认证/连接池/上下文取消;禁用已归档的 mgo,它不兼容 MongoDB 5.0+ 及 SCRAM-SHA-256 认证;需显式调用 client.Connect 并 Ping 测试连通性,连接字符串中 ?tls=true 启用证书校验,本地开发可加 ?tls=false&tlsInsecure=true(仅限调试)。

直接用 iris 框架连 MongoDB,不推荐“自己手写连接逻辑”。Iris 本身不内置 MongoDB 驱动,必须靠 mgo 或官方 mongo-go-driver 实现,而后者才是当前(2026 年)唯一被 MongoDB 官方维护、支持 TLS/认证/连接池/上下文取消的方案。
用 mongo-go-driver 连接 Iris 项目
Iris 是 Go Web 框架,它不干涉你如何初始化数据库客户端——关键是你得在 main() 或启动阶段完成连接,并把 *mongo.Client 安全地挂到 app.RegisterValue 或自定义容器里供 handler 使用。
- 别用已归档的
mgo:它不支持 MongoDB 5.0+ 的新协议和 SCRAM-SHA-256 认证,本地开发可能通,上生产大概率连不上 Atlas 或启用了安全策略的集群 - 必须显式调用
client.Connect(ctx)并等待完成;只 new Client 不等于已连上,mongo.Connect返回的是惰性连接,首次操作才真正拨号 - 连接字符串里带
?tls=true时,Go 会校验证书;若连本地无 TLS 的 mongod,得加?tls=false&tlsInsecure=true(仅开发),否则报x509: certificate signed by unknown authority - 示例片段:
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI("mongodb://localhost:27017"))
if err != nil {
log.Fatal(err)
}
defer client.Disconnect(context.TODO())
// 测试连通性
err = client.Ping(context.TODO(), readpref.Primary())
if err != nil {
log.Fatal(err)
}
在 Iris handler 里安全获取 collection
不要每次请求都 client.Database(...).Collection(...)——这虽不报错,但浪费 CPU 去解析字符串、查 map。collection 对象是线程安全的,可复用。
- 推荐在启动时就拿到
*mongo.Collection,比如usersColl := client.Database("myapp").Collection("users") - 通过
app.RegisterValue((*mongo.Collection)(nil), usersColl)注入,handler 中用ctx.Values().Get("*mongo.Collection").(*mongo.Collection)取出(注意类型断言) - 如果用了依赖注入库(如 wire),更建议把 collection 作为构造参数传给 service 层,而非从 ctx 硬取
- 别在 handler 里用
context.Background()调数据库;要用ctx.Request().Context(),否则超时或取消信号无法传递到底层驱动
插入与查询文档的典型写法
Go 的 struct tag 和 BSON 字段映射容易出错,尤其是时间、ObjectId、嵌套字段这三类。
-
_id字段必须对应primitive.ObjectID类型,不能用string或int;插入前用primitive.NewObjectID()生成,或从 URL 参数用primitive.ObjectIDHex(idStr)解析 - 时间字段用
time.Time,tag 写成bson:"created_at,omitempty",驱动会自动转为 BSON UTC datetime;别手动转 string,否则查不出来 - 嵌套结构体要加
bson:",inline"才能扁平展开进文档,否则会多一层 key;例如Address struct { City string } `bson:",inline"` - 查询单条用
FindOne(ctx, filter).Decode(&u);查多条用Find(ctx, filter).All(ctx, &users);filter 必须是bson.M或bson.D,不是 map[string]interface{}
常见错误:Find 返回空但没报错
这是最常卡住新手的问题——Find 自身不返回 error,Decode 或 All 才会。但即使没匹配到文档,它们也只返回 mongo.ErrNoDocuments,不是 panic。
- 别写
if err != nil { ... }就完事;要区分errors.Is(err, mongo.ErrNoDocuments)和真正的连接/权限错误 - 用
FindOne查单条时,如果想允许“不存在”,就忽略mongo.ErrNoDocuments;如果业务上必须存在,就要明确处理该 error - 聚合查询(
Aggregate)返回的是*mongo.Cursor,必须用cursor.All或循环cursor.Next拿结果,直接 print cursor 得到的是地址,不是数据 - 忘记设
context.WithTimeout导致查询卡死?驱动默认无超时,线上必须包一层ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
真正麻烦的从来不是“怎么连上”,而是“连上之后怎么让每条查询都可观察、可中断、可调试”——尤其当集合有 2000 万文档、又没建对索引时,一句 Find 就能让整个服务夯住几秒。


















