用 esapi.searchrequest 做全文搜索需手写 json body，推荐 map[string]interface{} 构造；注意 analyzer 一致、index/id 类型匹配、refresh 合理设置；新项目应选官方 go-elasticsearch/v8 并启用 explain 调试。
用 esapi.SearchRequest 做全文搜索，不是调 MatchQuery 就完事
Go 官方客户端（github.com/elastic/go-elasticsearch/v8）不提供高级 DSL 构建器，所有查询都得手写 JSON body。这意味着你不能像 olivere/elastic 那样链式调用 MatchQuery("title", "foo")，必须自己拼结构、注意字段嵌套层级和引号转义。
- 常见错误：直接传字符串
"{query:{match:{title:foo}}}"→ JSON 解析失败，因为foo缺少双引号，ES 返回400 Bad Request - 正确做法：用
map[string]interface{}构造再json.Marshal，或严格使用双引号的 raw JSON 字符串（推荐前者，避免引号嵌套混乱） - 中文分词依赖 analyzer：如果索引用了
ik_max_word，但查询没指定"analyzer": "ik_max_word"，可能搜不到结果——因为默认用标准分词器切分“人工智能”，变成“人工”“智能”，而 ik 会切出“人工智能”这个整体词项
Index 名、DocumentID 和 Refresh 参数怎么设才不踩坑
这三个参数看着简单，但线上出问题八成栽在这儿：
-
Index必须存在且 mapping 正确；若用blogs索引，但实际 mapping 是blog_v2，查不到数据也不会报错，只会返回空hits -
DocumentID类型要和写入时一致：写入用strconv.FormatInt(blog.ID, 10)，查询就不能传int64或带前导零的字符串，否则404 Not Found -
Refresh设为"true"会让写入立即可见，但严重拖慢吞吐；生产环境应设为"wait_for"或干脆不设（靠 ES 默认 1s refresh interval），否则高并发写+查容易漏数据
为什么用 go-elasticsearch/v8 而不是 olivere/elastic/v7
olivere/elastic 已归档（archived），v7 是最后一个版本，不再接收 PR 或安全更新；而官方 client 持续维护 v8，适配 Elasticsearch 8.x 的新特性（如 API key 认证、EQL 查询、searchable snapshot）。
- v8 强制要求 TLS 和身份认证（即使本地开发也要显式关掉
cfg.Transport = &http.Transport{...}或设SetInsecure()） - v7 默认支持
client.Search().Query(...).Do(ctx)这种流式写法，v8 全部退回到esapi.XXXRequest{...}.Do(ctx, es)，初学者容易漏传context或忘记defer res.Body.Close()导致 fd 泄露 - 如果你项目已用 v7 且无升级计划，没问题；但新项目起步，别为了省几行代码选一个停止维护的库
查不到结果？先检查 _source、highlight 和 explain
全文搜索失败时，ES 很少直接告诉你“分词没对上”，而是静默返回空数组。这时候得靠调试字段定位：
立即学习“go语言免费学习笔记（深入）”；
- 加
"_source": true到请求 body，确认文档真被索引进去了（有时IndexBlog函数里忘了body, _ := json.Marshal(...)，传了 nil） - 加
"highlight": {"fields": {"title": {}}}，看是否命中关键词；没高亮说明 query 没匹配到任何 term，大概率是 analyzer 不一致或字段名写错（比如写了titile） - 加
"explain": true，返回里会有details字段解释为什么相关度是 0 —— 这是最准的诊断依据，比翻日志快得多
真正麻烦的从来不是写不出查询语句，而是不知道它为什么没返回结果。把 explain 当成默认开关开着，比反复改 query 猜来猜去省两个小时。
