新项目必须使用官方go-elasticsearch/v8或v9，禁用已归档的olivere/elastic/v7；v8/v9不提供链式DSL构造器，需手动构建map[string]interface{}或JSON查询体，并显式指定analyzer、Index名、DocumentID类型及Refresh参数以避免静默失败。
olivere/elastic 已归档，go-elasticsearch/v8 和 v9 不提供链式 DSL 构造器——所谓“框架简化查询语法”在当前 Go 生态里并不存在可靠实现。硬套封装层只会掩盖错误、拖慢排查。
为什么别信“简化 DSL”的 Go 客户端
很多项目引入 olivere/elastic 是冲着 .Query().Match() 这类链式写法去的，但它早在 2022 年就停止维护，且不兼容 ES 8.x 协议。调用时看似简洁，实际一发请求就卡在 406 Not Acceptable 或静默返回空 hits，根本看不出哪错了。
官方 go-elasticsearch/v8 和 v9 明确放弃链式 API，强制你手写 map[string]interface{} 或原始 JSON。这不是倒退，是把控制权交还给你：DSL 错了，ES 返回的 error.reason 能直接看到；字段名拼错、嵌套层级错位，json.Marshal 阶段就能报错，而不是等 ES 拒绝后才翻日志。
-
olivere/elastic/v7的client.Search().Query(...).Do(ctx)看似省事，但内部把match_phase拼成match_phrase这种 typo 会直接吞掉，只返回泛化error: 400 Bad Request -
go-elasticsearch/v9要求你显式构造esapi.SearchRequest.Body，哪怕写错一个引号，json.Marshal就 panic，不让你把错误带进线上 - 所谓“DSL 生成工具”（如某些第三方包）常忽略
boost、operator、analyzer等关键字段，中文搜索直接失效
真正能省事的只有三件事
与其找“简化语法”的框架，不如把精力花在这三处——它们能实打实减少出错概率：
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 用 Kibana Console 先跑通 DSL：把
GET /blogs/_search请求体粘贴进去执行，确认返回有hits再复制到 Go 里，别凭记忆手写 - 封装复用的
map[string]interface{}片段：比如前缀搜索固定用prefix+keyword字段，就写个函数返回该结构，而不是每次重写整个 query - 加
"explain": true到 query body：调试时开启，ES 返回里会带matched_explanations，一眼看出为啥“人工智能”没匹配上——是分词切错了，还是字段类型是text却用了term
Index 名、DocumentID、Refresh 参数必须字面一致
这三个地方写错不会报错，只返回空结果，查起来最耗时间：
立即学习“go语言免费学习笔记（深入）”；
-
Index必须是精确字符串数组，比如[]string{"blogs_v2"}，传"blogs"或"*"在生产环境会被 ES 拒收或打满慢日志 -
DocumentID类型必须和写入时完全一致：写入用strconv.FormatInt(id, 10)得到"123"，查询就不能传int64(123)或"0123" -
Refresh参数值只能是"true"、"false"、"wait_for"，传true（布尔值）或"True"（大小写错）都会导致静默失败
中文搜索搜不到？先盯住 analyzer 是否对齐
90% 的“搜不到”不是 query 写错，而是索引侧和查询侧的分词器没对齐：
- 写入时 mapping 定义了
"analyzer": "ik_max_word"，但查询时match语句里没加"analyzer": "ik_max_word"，ES 就默认走standard分词器，“人工智能”被切成 “人工”“智能”，自然匹配不上 - 验证方法：用
GET /your_index/_analyze?analyzer=ik_max_word&text=人工智能确认切词结果，再比对 query 中是否显式指定了同一 analyzer - multi_match 查询多个字段时，每个字段可单独配 analyzer：
"fields": ["title^3", "content"], "type": "best_fields", "analyzer": "ik_max_word"
