新项目应使用 github.com/elastic/go-elasticsearch/v8，因其支持 ES 8.x 的 API key 认证、searchable snapshot 等特性，而 olivere/elastic/v7 已归档且自 2026 年起停止安全更新；v8 客户端不提供链式 DSL 构造器，需手动构建 map[string]interface{} 查询结构并 json.Marshal；中文搜索必须显式指定 analyzer（如 ik_max_word），否则默认 standard 分词器导致漏匹配；Index 名、DocumentID 类型、Refresh 参数须严格一致，否则静默失败；上线前须用 _analyze 和 _cat/indices 验证索引名、mapping、分词器三者对齐。
新项目直接用 github.com/elastic/go-elasticsearch/v8，别碰已归档的 olivere/elastic/v7；它不支持 ES 8.x 的 API key 认证、searchable snapshot 等关键特性，且自 2026 年起完全停止安全更新。
esapi.SearchRequest 必须手写 JSON body，不能链式调用
官方 v8 客户端不提供 MatchQuery()、BoolQuery() 这类高级 DSL 构造器。你得自己组织查询结构，再 json.Marshal 成字节流传给 Body 字段。
- 错误写法：
"{query:{match:{title:foo}}}"→400 Bad Request（foo缺少双引号） - 推荐写法：用
map[string]interface{}构建，例如map[string]interface{}{"query": map[string]interface{}{"match": map[string]interface{}{"title": "人工智能"}}}，再json.Marshal - 注意嵌套层级：ES 的
match是 query 下一级，不是 root；highlight、aggs都要和query同级 - 调试时加
"explain": true到 body 里，返回会带评分细节，方便排查分词或权重问题
中文搜索必须显式指定 analyzer，否则默认标准分词器失效
如果你的索引 mapping 用了 ik_max_word，但查询没带 "analyzer": "ik_max_word"，ES 就会用默认的 standard 分词器切“人工智能”成“人工”“智能”，而 ik 能切出“人工智能”这个完整词项——结果就是搜不到。
- 查单字段：在
match或multi_match中加"analyzer": "ik_max_word" - 查多字段：用
multi_match+"type": "best_fields"，每个字段可单独配 analyzer - 验证分词：用
GET /your_index/_analyze?analyzer=ik_max_word手动测输入文本是否被正确切分
Index、DocumentID、Refresh 三个参数稍错就静默失败
它们不报错，只返回空 hits，排查起来极耗时间。
立即学习“go语言免费学习笔记（深入）”；
-
Index名必须和 mapping 定义完全一致：比如索引实际叫blogs_v2，但代码里写blogs，查询永远 0 结果，ES 不提示 -
DocumentID类型必须和写入时一致：写入用strconv.FormatInt(blog.ID, 10)得到字符串"123"，查询就不能传int64(123)或带前导零的"0123"，否则返回404 Not Found -
Refresh别设"true"：它强制刷新，让文档立即可见，但吞吐暴跌；生产环境应设"wait_for"或干脆不设（依赖 ES 默认 1s refresh interval），否则高并发写+查容易漏数据
最易忽略的是 analyzer 和 ID 类型的一致性——它们不出错，只让你以为“搜不到”，实际是“根本没匹配上”。上线前务必用 _analyze 和 _cat/indices 交叉验证索引名、mapping、分词器三者是否对齐。
