真正卡住人的是连接通但查不到数据、DSL正确却返回空、上线后批量超时，根源在客户端选型、认证方式、查询构造三步。
gin 集成 elasticsearch 不是“配个 client 就能搜”，真正卡住人的永远是连接通了但查不到数据、DSL 写对了但返回空、或者上线后突然批量超时——这些问题几乎都出在客户端选型、认证方式、查询构造这三步。
用哪个 Go 客户端？看 ES 版本，不是看 Go 版本
ES 7.x（如 7.17）→ 必须用 github.com/olivere/elastic/v7；ES 8.x 或 9.x（包括刚装的 8.15、9.0）→ 只能用 github.com/elastic/go-elasticsearch/v9。混用直接 400/406 静默失败，日志里只显示 error decoding response body 或空 hits，根本不会告诉你协议不匹配。
-
olivere/elastic/v7已归档，2026 年起停止安全更新，且不支持 ES 8+ 的api_key认证和searchable snapshot -
go-elasticsearch/v9要求显式传esapi.SearchRequest，不提供MatchQuery()这类链式构造器，得手写map[string]interface{}再json.Marshal - Docker/K8s 环境下，无论哪个客户端，都必须关掉节点嗅探：
SetSniff(false)（olivere）或初始化时设Sniffer: &http.Transport{}（go-elasticsearch），否则会因内网 IP 导致后续请求超时
认证配置别只填用户名密码
ES 8+ 默认强制 HTTPS + Basic Auth，哪怕本地单节点也得显式处理；ES 7.x 若启用了安全插件，username/password 和 api_key 是互斥的——优先用 api_key，它更轻量、可细粒度控制权限。
-
olivere/elastic/v7：用elastic.SetBasicAuth(user, pass)或elastic.SetAPIKey(apiKey)，后者优先级更高 -
go-elasticsearch/v9：认证信息要塞进elastic.Config，比如APIKey: "xxx"或Username: "xxx", Password: "xxx" - 开发环境连本地 ES 8.x 时，还得额外加
Transport: &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}，否则 TLS 握手失败
Search 请求三要素缺一不可
go-elasticsearch/v9 的 esapi.SearchRequest 不补默认值，漏一个字段就发废请求：返回空结果、no search context found 或 panic。
-
Index：必须是[]string{"my_index"}，不能是""或"*"；生产禁用通配符，ES 可能拒收或打满慢日志 -
Body：必须是*bytes.Reader，常见错误是json.Marshal(req)后没包bytes.NewReader()，导致请求体为空，ES 返回400 Bad Request -
Context：必须带超时，例如context.WithTimeout(ctx, 3*time.Second)；不设的话 HTTP client 可能卡死在连接池，goroutine 悬停
中文搜不到？先查分词器和字段类型
90% 的“搜不到”不是 query 写错，而是索引侧配置和查询行为不一致。比如 mapping 里 title 字段用了 ik_max_word 分词器，但查询 DSL 没指定 "analyzer": "ik_max_word"，ES 就默认走 standard，把“人工智能”切成“人工”“智能”，自然匹配不上。
- 验证分词：用
curl -X GET "localhost:9200/my_index/_analyze?pretty" -H "Content-Type: application/json" -d '{"analyzer": "ik_max_word", "text": "人工智能"}' - 字段类型错配：
keyword类型字段只能用TermQuery，不能用MatchQuery；text类型才支持全文检索 -
refresh延迟：文档写入后默认 1 秒才可搜索，刚Index()完立刻Search()，大概率为空；开发期可临时加"refresh": "true"，但批量导入严禁使用
Index 名拼错一个字母、Body 没包 bytes.Reader——这些细节不跑一遍真实请求+响应体，光看日志根本发现不了。 
