beego框架的orm模块仅支持mysql、postgresql、sqlite等关系型数据库，不原生支持mongodb；因其基于sql抽象设计，依赖表结构、join、事务等rdbms特性，而mongodb为文档型数据库，协议与操作模型根本不同，故orm.registerdatabase("mongo", ...)会panic或静默失败。
Beego 框架本身不原生支持 MongoDB；它的 orm 模块只适配关系型数据库（MySQL、PostgreSQL、SQLite），无法注册或操作 MongoDB 连接。想在 Beego 项目里用 MongoDB，必须绕过 orm，直接使用官方 Go 驱动 go.mongodb.org/mongo-driver/mongo 或已停止维护但仍有项目在用的 mgo。
为什么 Beego ORM 不能连 MongoDB
Beego 的 orm 是基于 SQL 抽象设计的：它依赖 SELECT/INSERT/UPDATE/DELETE 语句、事务、预编译、表结构映射等 RDBMS 特性。MongoDB 是文档型数据库，没有表、没有 JOIN、不支持标准 SQL，其 CRUD 基于 BSON 文档和集合操作，底层协议也完全不同。所以 orm.RegisterDataBase("mongo", ...) 会直接 panic 或静默失败。
常见错误现象：panic: unknown driver "mongodb" 或调用 orm.NewOrm() 后执行任何操作都报 runtime error: invalid memory address——本质是 ORM 尝试对一个未注册成功的 DB 实例做 SQL 解析。
正确做法：用官方驱动 + Beego 生命周期管理连接
把 MongoDB 客户端当作 Beego 应用的一个全局依赖来初始化，而不是塞进 ORM 流程。关键点是：连接复用、上下文透传、错误处理收敛。
- 在
main.go的init()或beego.Run()前，用mongo.Connect()创建并缓存*mongo.Client - 连接字符串必须含
?connect=direct（单机）或?replicaSet=rs0（副本集），否则可能卡住或超时 - 务必设置
context.WithTimeout控制连接建立耗时，避免启动阻塞；例如 10 秒超时足够诊断网络或配置问题 - 不要在每个 handler 里重复
Connect()；Beego 的Controller是短生命周期对象，应从全局 client 获取Database和Collection实例
示例片段（非完整）：
var mongoClient *mongo.Client
func initMongo() error {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))
if err != nil {
return err
}
mongoClient = client
return nil
}
Beego Controller 中安全调用 MongoDB 方法
Go 的 MongoDB 驱动所有读写操作都要求显式传入 context.Context，而 Beego 的 Controller 并不自动提供带取消机制的请求上下文。必须手动从 c.Ctx.Request.Context() 提取，并视情况加超时。
- 避免用
context.Background()—— 会导致查询无法随 HTTP 请求中断而取消，堆积 goroutine - 写操作（
InsertOne,UpdateOne）建议加context.WithTimeout(c.Ctx.Request.Context(), 5*time.Second) - 读操作若涉及聚合或大数据量扫描，超时可设为 8–12 秒，但需配合 MongoDB 索引优化，而非单纯调大 timeout
- 别漏掉
defer cursor.Close(c.Ctx.Request.Context())—— 游标泄露是线上 MongoDB 连接数飙升的常见原因
典型调用模式：
func (c *MainController) Get() {
ctx, cancel := context.WithTimeout(c.Ctx.Request.Context(), 5*time.Second)
defer cancel()
coll := mongoClient.Database("mydb").Collection("users")
res := coll.FindOne(ctx, bson.M{"name": "alice"})
var user User
if err := res.Decode(&user); err != nil {
c.Data["json"] = map[string]string{"error": err.Error()}
c.ServeJSON()
return
}
c.Data["json"] = user
c.ServeJSON()
}
容易被忽略的坑：BSON 标签、时区、连接池泄漏
Beego 项目常混用 JSON 和 BSON 结构体标签，导致字段写入 MongoDB 后为空或错位。MongoDB 驱动只认 bson tag，不是 json。
- 结构体字段必须用
`bson:"field_name"`显式声明，否则默认按首字母小写导出名映射（如Name→name），且零值字段不会写入 - 时间字段务必加
`bson:"created_at" time:"2006-01-02T15:04:05Z"`，否则可能存成空或 Unix 时间戳整数，后续查不出来 - 如果用了
mgo（不推荐新项目），注意其 Session 不是线程安全的，每次操作后要session.Clone()或session.Copy()，否则并发下会 panic - 官方驱动的
mongo.Client是线程安全的，但如果你在中间件或 filter 里反复mongo.Connect()而不Disconnect()，连接池会持续增长直至 OOM
真正麻烦的从来不是“怎么连上”，而是“连上之后怎么不让它在高并发下崩掉”——BSON 映射错一位、游标忘 Close 一次、Context 缺 timeout 一回，都可能变成凌晨三点的告警。
