Go语言集成Elasticsearch全文检索与搜索优化

先说几个核心判断：在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{"http://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。这个习惯，能帮你省下不少排查时间。