Beego ORM 查询不能通用封装，必须按模型分层定制，因 QuerySeter 有隐式状态、Read 仅支持单字段主键、Filter 字段名须匹配 struct 字段而非列名；推荐为每个模型定义专属 Query 结构体，每次新建干净实例并显式管理生命周期。
Beego 的 ORM 查询不能直接封装成通用 DAO 层，必须按模型分层、按场景定制，否则会踩坑——尤其是 QuerySeter 生命周期、Read 单字段限制、Filter 链式调用隐式复用等问题。
为什么不能写一个「万能 GetByFields」函数
很多人试图封装类似 GetByFields(model, map[string]interface{}) 的通用查询函数，结果发现：查不到数据、条件被忽略、甚至返回随机记录。根本原因是 orm.QuerySeter 不是纯函数，它内部持有未清空的 SQL 构建状态和参数缓存。
-
o.QueryTable("user").Filter("name", "a").Filter("age", 25)是 OK 的，但把它拆进循环或中间函数里，容易意外复用前一次的QuerySeter实例 -
o.Read(&u, "name")只支持单字段主键查找，传多个字段（如o.Read(&u, "name", "age")）会静默失败，不报错也不匹配 - struct tag 中的
orm:"column(xxx)"和实际数据库列名必须严格一致，大小写敏感，且Filter的字段名必须是 struct 字段名，不是数据库列名（除非你用FilterRaw）
推荐的封装方式：每个模型配一个 Query 结构体
不要追求“一套代码查所有表”，而是为每个业务模型（如 User、Order）定义专属的查询结构体，把 QuerySeter 创建、过滤、执行逻辑收束在一处。
例如，在 dao/user_query.go 中：
type UserQuery struct {
qs orm.QuerySeter
}
func NewUserQuery() *UserQuery {
return &UserQuery{
qs: orm.NewOrm().QueryTable(&User{}),
}
}
func (q *UserQuery) ByName(name string) (*User, error) {
u := new(User)
err := q.qs.Filter("Name", name).One(u)
return u, err
}
func (q *UserQuery) ByNameAndAge(name string, age int) (*User, error) {
u := new(User)
err := q.qs.Filter("Name", name).Filter("Age", age).One(u)
return u, err
}
- 每次调用
NewUserQuery()都新建一个干净的QuerySeter，避免状态污染 - 方法名明确表达语义（
ByName、ByNameAndAge），比泛型GetBy(map[string]interface{})更易读、更易测试 - 如果需要支持不定条件（比如后台搜索页），用
FilterRaw+ 参数拼接，而不是强行塞进 map
多条件查询时，Filter 链式调用必须注意顺序和重置
当你动态组合条件（如根据前端传参决定是否加 age__gt 或 name__contains），不能反复复用同一个 QuerySeter 实例，也不能靠 if-else 拼接字符串——beego ORM 不支持运行时修改已构建的 SQL 条件链。
- 错误写法：
qs := o.QueryTable(&User{}); if name != "" { qs.Filter("Name", name) }; if age > 0 { qs.Filter("Age", age) }—— 这里的qs.Filter()返回新实例，但你没接住，原qs不变 - 正确做法：每步都重新赋值，或用函数式风格累积：
qs = qs.Filter("Name", name) - 更安全的做法是封装成 builder 函数：
func (q *UserQuery) WithName(name string) *UserQuery { q.qs = q.qs.Filter("Name", name); return q }，支持链式调用q.WithName("a").WithAge(25).First()
事务中复用 QuerySeter 要显式绑定到同一个 ORM 实例
在事务里做多次查询或更新时，所有操作必须共享同一个 orm.Ormer 实例，否则会跨连接、丢失事务上下文。
- 错误：在
o := orm.NewOrm()开启事务后，又在某个 DAO 方法里调用orm.NewOrm().QueryTable(...)—— 这是另一个连接，不在事务内 - 正确：把
orm.Ormer作为参数传入 DAO 方法，或通过 context 透传：func (q *UserQuery) UpdateName(o orm.Ormer, id int, name string) error { ... } - 别依赖全局
orm.NewOrm()，它每次新建连接，不适合事务/长生命周期场景
真正难的不是写查询，而是让每次查询的边界清晰、状态可控。ORM 封装一旦脱离具体模型和使用路径，就容易变成隐藏 bug 的温床——尤其是当团队多人维护、查询逻辑分散在不同文件时，QuerySeter 的隐式状态最容易引发偶发性数据错乱。
