Beego ORM 模糊匹配必须用__contains或__icontains等双下划线后缀,不支持LIKE直接写法;常见错误包括拼错操作符、字段映射缺失、字符集未设utf8mb4;支持__startswith/__endswith/__icontains等语义化匹配。

Beego ORM 的模糊匹配语法必须用 __contains 或 __icontains
Beego ORM 不支持 SQL 里的 LIKE '%xxx%' 直接写法,所有模糊匹配都得靠表达式后缀。最常用的是 __contains(大小写敏感)和 __icontains(忽略大小写)。注意双下划线是硬性要求,写成 _contains 或 contains 都会静默失效,查不到数据也不报错。
常见错误现象:
- 写了
Filter("name", "%alice%")—— 这是纯字符串等值匹配,不是模糊查询 - 用了
Filter("name__like", "%alice%")—— Beego ORM 没有__like操作符,会被忽略 - 字段名拼错,比如数据库列是
user_name,但 struct tag 没配orm:"column(user_name)",导致条件生成到不存在的字段上
正确写法示例:
qs := o.QueryTable(&User{})
var users []User
num, err := qs.Filter("Name__contains", "ali").All(&users)
// 生成类似:WHERE `name` LIKE '%ali%'
区分前缀、后缀、全匹配:用 __startswith / __endswith / __icontains
Beego ORM 提供了更细粒度的字符串匹配控制,比手拼 % 更安全、语义更清晰:
-
__startswith→ 对应LIKE 'xxx%',适合搜索用户名以某字符开头 -
__endswith→ 对应LIKE '%xxx',适合匹配邮箱后缀(如"@gmail.com") -
__icontains→ 大小写不敏感的全模糊,适合搜索文章标题、商品名称等用户输入场景
注意:__startswith 和 __endswith 在 MySQL 中能走索引(如果字段有前缀索引或完整索引),而 __contains 基本无法利用索引,大数据量时要谨慎。
示例:
// 查找邮箱以 gmail.com 结尾的用户
qs.Filter("Email__endswith", "@gmail.com")
// 查找城市名包含 "shen" 且不区分大小写
qs.Filter("City__icontains", "shen")
中文模糊查询失败?检查连接参数里的 charset=utf8mb4
如果对中文字段(如 Name)执行 __contains 却始终返回空结果,大概率是数据库连接没设对字符集。Beego ORM 生成的 LIKE 条件本身没问题,但 MySQL 在 utf8(实际是 utf8mb3)下无法正确处理 emoji 或部分生僻中文,会导致比较失败。
必须确保 RegisterDataBase 的连接字符串里含 ?charset=utf8mb4:
orm.RegisterDataBase("default", "mysql", "root:pass@/mydb?charset=utf8mb4&loc=Local")
- 漏掉
charset=utf8mb4:中文存入变???,查询自然不匹配 - 只写
charset=utf8:MySQL 5.5.3+ 虽兼容,但对四字节 UTF-8 字符支持不完整 - 没加
&loc=Local:time.Time字段可能因时区错位被写成零值,间接影响关联查询结果
复杂条件组合时,Filter 和 Exclude 的顺序不影响 SQL 逻辑
Beego ORM 的 Filter 是 AND 累积,Exclude 是 NOT 包裹,最终生成的 WHERE 子句顺序由调用先后决定,但语义等价。比如:
qs.Filter("Name__icontains", "admin").
Filter("Status", 1).
Exclude("Role", "guest")
等价于:
WHERE name LIKE '%admin%' AND status = 1 AND role != 'guest'
容易踩的坑:
- 把
Exclude写在Filter前面,误以为会“先排除再筛选”,其实只是条件并列,无执行先后 - 对同一字段多次
Filter(如Filter("Age__gt", 18).Filter("Age__lt", 60)),ORM 会合并为AND,不是覆盖 - 想实现 OR 逻辑?Beego ORM 原生不支持,得用
Ormer.Raw()写原生 SQL,或者拆成两次查询再 merge
模糊匹配本身不触发 N+1,但若后续链式调用 LoadRelated,就得小心关联表字段是否也做了对应模糊配置 —— 比如 User.Profile.Name__contains 要求 Profile 模型已注册且外键关系正确声明。











