Beego ORM 不提供开箱即用的全文模糊搜索，其 contains / icontains 仅生成 LIKE 查询：contains 为 WHERE col LIKE '%val%'（区分大小写），icontains 为 WHERE LOWER(col) LIKE LOWER('%val%')（不区分大小写），须用于字符串字段且不可链式叠加操作符。
Beego 本身不提供开箱即用的「全文模糊搜索」能力，它依赖底层数据库（如 MySQL、PostgreSQL）或外部服务（如 Elasticsearch）来实现。直接在 QuerySeter.Filter() 中用 icontains 或 contains 是最常用、最轻量的模糊匹配方式，但必须清楚它只生成 LIKE 查询，不是分词检索。
QuerySeter 的 contains / icontains 怎么写才生效
Beego ORM 的模糊匹配靠操作符驱动，不是靠字段类型或额外配置：
-
contains生成WHERE column LIKE '%value%'，区分大小写 -
icontains生成WHERE LOWER(column) LIKE LOWER('%value%')，不区分大小写 - 必须配合字符串字段使用；对
int或time.Time字段用会静默失败或报错 - 不能链式叠加多个
contains到同一字段（如title__icontains__startswith不合法）
示例：
qs := orm.QueryTable(&User{})
qs.Filter("name__icontains", "张") // WHERE LOWER(name) LIKE LOWER('%张%')
qs.Filter("email__contains", "@gmail") // WHERE email LIKE '%@gmail%'
带分页的模糊搜索如何避免 offset 性能陷阱
Beego 的 Limit(n, offset) 是反直觉的：第二个参数是 offset，第一个是 limit。模糊搜索 + 分页时容易误写成 .Limit(10, 20)（本意是第 3 页），结果查出前 20 条跳过 10 条——逻辑翻转。
- 务必确认参数顺序：
Limit(每页条数, 起始偏移) - 起始偏移 = (当前页码 - 1) × 每页条数，别手算错
- 当模糊条件导致结果集很小（比如只匹配到 5 条），
Limit(10, 20)会返回空切片，不是错误，需业务层判断是否“无更多数据” - 大数据量下，
OFFSET越大越慢；真要支持深分页，得改用游标分页（比如基于id > ?），Beego 不内置支持，需手动拼 SQL 或用Raw()
为什么用 ik 分词器的 Elasticsearch 不该走 Beego ORM
如果你已接入 Elasticsearch 并配置了 ik_max_word 分词器，就不要试图让 Beego ORM 去查 ES —— 它只适配关系型数据库。Beego 没有原生 ES 客户端集成，硬套 ORM 会绕远路：
- ES 的
match、multi_match、highlight等能力，无法通过Filter()表达 - mapping 中定义的
analyzer和search_analyzer在 ORM 层完全不可见 - 正确做法是：在 Controller 里用官方
elastic/v8客户端直连 ES，把查询参数（如c.GetString("q")）构造成 DSL 请求，再把结果映射回 Go struct - 如果坚持用 Beego 封装，至少把 ES 调用抽成独立 service，别塞进 model 或 queryseter 链路里
前端传参和后端校验的常见断点
模糊搜索最容易在请求流转中“消失”，尤其涉及 URL 编码和空值处理：
- 前端用
GET /user/list?q=李&page=2，后端必须用c.GetString("q")，不是c.Input().Get("q")（后者已废弃） -
c.GetString("q")对空字符串或纯空白字符返回""，需显式判断：if q := strings.TrimSpace(c.GetString("q")); q != "" { qs = qs.Filter("name__icontains", q) } - 中文、特殊符号（如
+、%）在 URL 中会被编码，c.GetString()自动解码，无需额外url.QueryUnescape - 别在 Filter 前对关键词加
%——icontains已内置，重复添加会导致%%keyword%%，查不到数据
真正麻烦的从来不是“怎么写模糊查询”，而是“怎么让关键词从用户输入框，完整、干净、可预期地抵达数据库的 LIKE 子句里”。中间任何一环丢掉空格、忽略编码、错判空值，都会让搜索看起来“有时灵有时不灵”。
