search调用返回空或panic的根本原因是esclient未成功初始化或字段映射不一致；分页需限制from+size≤10000或改用searchafter；模糊查询须匹配分词器并避免keyword字段match；反序列化要求字段导出、类型匹配且校验source非nil。
直接用 elastic.NewClient 初始化客户端后调用 Search 方法就能发起查询，但不处理上下文超时、错误重试、索引名拼接或字段映射差异，线上请求大概率会 500 或返回空结果。
为什么 Search 调用返回空或 panic？
常见现象是 Do(context.Background()) 返回 nil 结果但无报错，或 panic 提示 invalid memory address。根本原因通常是：
-
EsClient未成功初始化（比如 ES 地址不通、认证失败），但代码里只fmt.Println(err)忽略了，后续调用Search时对nil指针操作 - 索引名不存在，ES 默认不报错，而是返回空
hits；需提前用IndexExists检查 - 查询结构体字段名与 ES mapping 不一致（如 Go struct 字段是
UserName，mapping 是user_name），导致反序列化失败，Source字段为空
From 和 Size 怎么安全分页？
ES 的分页不是 MySQL 的 offset/limit，From + Size 超过 index.max_result_window（默认 10000）就会报错 result window is too large。实际使用必须：
- 限制最大
Size，比如硬编码.Size(100)，禁止前端传任意大值 - 深度分页改用
SearchAfter：先取排序字段（如@timestamp）值，下一页传.SearchAfter("2026-08-11T23:00:00Z") - 避免用
From(10000).Size(10)这类组合，服务端应校验from + size
怎么让模糊查询不漏匹配又不慢？
直接用 NewMatchPhraseQuery 或 NewQueryStringQuery 容易要么召回率低，要么拖垮集群。关键在 query 类型和字段配置的配合：
- 中文搜索必须确认字段用了
ik_smart或ik_max_word分词器，否则match查询对中文无效 - 用户输入短词（如“手机”）优先用
NewMultiMatchQuery查多个字段，并设.Type("best_fields") - 想支持拼写容错，加
.Fuzziness("AUTO")，但别在高 QPS 接口上无条件开启，它会显著增加 CPU 开销 - 绝对不要在
keyword类型字段上做match查询——它只会全量扫描，响应时间不可控
查询结果反序列化总出错？
Go struct 字段无法自动绑定到 ES 返回的 JSON，最常被忽略的是三个点：
- 所有字段必须导出（首字母大写），且加
jsontag，比如UserName string `json:"user_name"` - ES 返回的
_source是 map[string]interface{}，如果结构体字段类型和实际值不匹配（如 ES 存的是字符串"123"，struct 定义为Age int），json.Unmarshal会静默失败，Age保持 0 - 用
SearchResult.Hits.Hits[i].Source做反序列化前，先检查Source != nil，否则 panic
ES 查询接口真正难的不是写 Search().Query().Do() 这一行，而是每一步都得预设失败路径：连接可能断、索引可能没建、字段可能改名、用户可能输错词、分页可能越界。这些地方少一个 guard，上线后就是半夜告警。
