先说几个核心判断：在Go生态里集成Elasticsearch，go-elasticsearch/v8是当前唯一还在活跃维护的官方客户端，而曾经风光无限的olivere/elastic已经归档，不再兼容ES 8.x+。如果你还抱着老版本客户端连新集群，得到的结果大概率是406 Not Acceptable或者干脆静默返回空响应——别怀疑代码写错了，是协议层面就没打通。
接下来的几个坑，算是把不少开发者绊倒过的“老问题”，值得拿出来单独说说。
esapi.SearchRequest的Body必须是*bytes.Reader
很多人写全文搜索时，习惯把json.Marshal()得到的字节切片直接塞进Body字段，结果ES返回400 Bad Request，日志里只有一句“invalid request body”。问题出在哪？esapi.SearchRequest.Body的类型是io.ReadSeeker，不是[]byte。
- 错误写法：
Body: jsonBytes——编译可能能过，但运行时请求体为空。 - 正确写法：
Body: bytes.NewReader(jsonBytes)。 - 构造JSON时，推荐用
map[string]interface{}，避免手拼字符串导致引号嵌套出错。例如：map[string]interface{}{"query": map[string]interface{}{"match": map[string]interface{}{"title": "golang"}}}。 - 中文搜索必须显式指定
"analyzer": "ik_max_word"，否则默认走标准分词器，“人工智能”会被切成“人工”和“智能”，而索引时用ik存的是“人工智能”这个词项，查不到很正常。
MatchQuery和TermQuery混用，查不到数据是常态
DSL语法合法，ES也不报错，但TotalHits.Value()始终为0。这种情况，十有八九是字段类型和查询语义错配了。
MatchQuery("title", "golang")适用于text类型字段，会触发分词和相关性打分。TermQuery("status", "published")才能匹配keyword类型字段；用MatchQuery查keyword字段，等于白查。- 组合条件时，别把什么都堆进
Must：全文搜索放在BoolQuery().Must()里，状态/范围过滤放在.Filter()里——不打分、可缓存、性能更好。 - 时间范围也别拼字符串：
RangeQuery("created_at").Gte("now-7d").Lte("now")是ES原生支持的表达式，不用转成具体时间戳。
解析hits.Source时，结构体字段名必须和mapping完全一致
result, err := req.Do(ctx)成功，但result.Hits.Hits是空slice，或者hit.Source解析后字段全是零值——不是没数据，是JSON key对不上。
- ES返回的文档内容在
hit._source下，不是顶层字段；不能直接json.Unmarshal(raw, &doc)。 - 必须调用
hit.Source方法：err := json.Unmarshal(*hit.Source, &doc)，注意*hit.Source是指针解引用。 - 结构体tag必须严格匹配mapping定义的字段名：
user_id≠userId，created_at≠createdAt，差一个下划线就查得到但解析失败。 - 如果mapping里字段是
"properties": {"tags": {"type": "keyword"}}，结构体就得写Tags string `json:"tags"`，不能写成Tags []string——除非mapping明确设了"index": false或用了nested类型。
client初始化漏配置，本地通、上K8s就超时或401
90%的“context deadline exceeded”和“401 Unauthorized”都卡在elasticsearch.NewClient()这一步，不是网络问题，是配置没对齐。
- 必须显式传
Addresses: []string{"https://elasticsearch.default.svc.cluster.local:9200"}（K8s Service名），别信默认的localhost。 - 加
Transport: &http.Transport{...}并设置Timeout，v8默认无超时，goroutine会悬停。 - 务必关掉sniff：
Sniff: false，Docker/K8s里sniff会尝试连内网IP，直接失败。 - 启用Basic Auth就得填
Username和Password字段；漏一个，错误就是一行401 Unauthorized，没有更多上下文。
最后提醒一句：ES的错误响应常常不抛异常，而是静默返回空hits或406这类非5xx状态码。调试时，先看res.StatusCode和res.String()，别只盯着err != nil。这个习惯，能帮你省下不少排查时间。
