go-elasticsearch/v8是当前唯一推荐客户端，olivere/elastic已归档且不兼容ES 8.x+；esapi.SearchRequest.Body必须为*bytes.Reader，需用bytes.NewReader(jsonBytes)而非直接传字节切片。
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 对不上。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 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() 这一步，不是网络问题，是配置没对齐。
立即学习“go语言免费学习笔记（深入）”；
- 必须显式传
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，没有更多上下文
hits 或 406 这类非 5xx 状态码；调试时得先看 res.StatusCode 和 res.String()，而不是只盯着 err != nil。 
