必须使用对应ES版本的客户端：ES 8.0+/9.x需用elastic/go-elasticsearch/v9或v8，禁用已归档的olivere/elastic/v7；请求须显式设置Index、Body、Context三字段，且注意分词器、refresh、字段类型匹配及_source解析规范。
选错客户端版本，请求根本发不出去
ES 8.0+ 和 9.x 已强制移除 _type、要求 HTTPS、变更 /_search 路径结构、校验 Content-Type: application/json。用已归档的 olivere/elastic/v7 连接 ES 8.15 或 9.0，会直接返回 400 Bad Request 或更隐蔽的 406 Not Acceptable，不是你 query 写错了，是协议层被拒。
必须用 github.com/elastic/go-elasticsearch/v9（新项目）或 v8（兼容 8.x 主流版本）。v7 只能用于存量 ES 7.10–7.17 环境，且不再接收任何更新。
- 别混用两个客户端：同一进程里同时 import
olivere/elastic和elastic/go-elasticsearch，会导致context.Context传参冲突、http.RoundTripper复用异常，出现静默超时 -
go get时明确指定版本：go get github.com/elastic/go-elasticsearch/v9@latest，避免 go mod 自动降级到 v7 - v9 初始化后，立刻调
es.Info()验证连通性；失败时检查错误是否含"x509: certificate signed by unknown authority"——本地开发需显式禁用证书校验
esapi.SearchRequest 必须显式设三个字段
官方客户端不补默认值，漏一个就等于发了个废请求：空 hits、no search context found、甚至 panic。
-
Index：必须为非空[]string{"articles"}，禁止传""或"*"；生产环境通配符会被 ES 拒收或打满慢日志 -
Body：必须是*bytes.Reader；常见错误是json.Marshal(q)后没包bytes.NewReader()，导致请求体为空，ES 直接返回400 Bad Request -
Context：必须带超时，例如context.WithTimeout(ctx, 3*time.Second)；不设的话 HTTP client 可能卡死在连接池，goroutine 悬停不释放
正确写法示例：
立即学习“go语言免费学习笔记（深入）”；
req := esapi.SearchRequest{
Index: []string{"articles"},
Body: bytes.NewReader([]byte(`{"query":{"match":{"title":"golang"}}}`)),
Context: context.WithTimeout(ctx, 3*time.Second),
}
res, err := req.Do(ctx, es)
if err != nil {
// 注意：err 可能是 *elastic.Error，可取 res.StatusCode 判断
}
defer res.Body.Close()
中文搜不到？先查分词器、refresh 和字段类型
90% 的“搜不到”问题出在索引侧，不是 Go 代码写错。
- 分词器不一致：索引用了
ik_max_word，但查询 DSL 没加"analyzer": "ik_max_word"，ES 默认走standard分词器，“人工智能”被切成 “人工”“智能”，而 IK 会切出完整词项 -
refresh延迟：文档写入后默认 1 秒才可搜索；刚调完IndexRequest.Do()就查，必然为空；开发期可临时设Refresh: "true"，但批量导入严禁使用 - 字段类型错配：mapping 中
title是keyword，却用match查询——keyword不分词，match查不了；该用term或把 mapping 改成text
查之前先跑：GET /articles/_mapping，确认字段类型、analyzer 和 search_analyzer 是否匹配。
解析 hit.Source 时最容易 panic
ES 返回的文档内容在 hit._source 下，不是 JSON 根对象。直接 json.Unmarshal(raw, &MyDoc{}) 会失败或字段全空。
- 正确做法是调
hit.Source方法：err := json.Unmarshal(*hit.Source, &doc)，注意*hit.Source是指针 -
hit.Source可能为nil（比如查询时设了"_source": false），必须判空 - 别用
hit["_source"]这种 map 方式读——它其实是map[string]interface{}，嵌套深时易 panic，且无法绑定 struct tag
最稳的反序列化路径：
for _, hit := range res.Hits.Hits {
if hit.Source == nil {
continue
}
var doc Article
if err := json.Unmarshal(*hit.Source, &doc); err != nil {
log.Printf("failed to unmarshal hit: %v", err)
continue
}
// use doc...
}
实际集成中，最难绷的不是写查询，而是让索引行为、写入逻辑、查询 DSL 和 Go 结构体四者严格对齐。稍有 mismatch，就变成“数据明明写了，就是搜不出来”，排查时容易反复改 Go 代码，却忽略 mapping 或 analyzer。 
