用 olivere/elastic/v7 还是 elastic/go-elasticsearch/v9？
现在该选哪个客户端，取决于你用的 Elasticsearch 版本——不是“哪个更新更好”，而是“不匹配就直接连不上”。olivere/elastic/v7 专为 ES 7.x 设计，对 ES 8+ 的 API 变更（比如删除 type、强制 HTTPS、_search 接口路径调整）完全不兼容；而 elastic/go-elasticsearch/v9 是官方维护的 v9 客户端，支持 ES 7.17+ 到 8.x，并已适配 9.0 的早期变更（如新的 auth header 格式）。如果你刚装 ES，默认是 8.15 或更高，olivere/elastic 一连就报 400 Bad Request 或 406 Not Acceptable，根本进不了后续步骤。
- ES 7.10–7.17 → 可用
olivere/elastic/v7，但建议只用于存量项目迁移 - ES 8.0+ → 必须用
elastic/go-elasticsearch/v9，否则IndexRequest会因缺少Content-Type: application/json被拒 - 别混用：同一项目里同时 import 两个客户端，容易因
context.Context传参或http.RoundTripper冲突导致超时静默失败
esapi.SearchRequest 构造时最容易漏掉的三个字段
写搜索逻辑时，很多人照着文档拼 JSON body 就完事，结果返回空数组或 no search context found。其实 esapi.SearchRequest 是个“半裸”结构体，它不自动补默认值，少设一个关键字段，ES 就当你是发了个不完整请求。
-
Index必须显式传，不能留空字符串；传"*"虽然能查全部索引，但生产环境禁止——ES 会拒绝或触发慢日志告警 -
Body必须是*bytes.Reader，不能直接传map[string]interface{}；常见错误是json.Marshal后忘了bytes.NewReader()，导致请求体为空 -
Context必须带超时，比如context.WithTimeout(ctx, 5*time.Second)；不设的话，底层 HTTP client 可能卡死在连接池里，整个 goroutine 悬停
示例片段：
req := esapi.SearchRequest{
Index: []string{"products"},
Body: bytes.NewReader([]byte(`{"query":{"match":{"title":"golang"}}}`)),
Context: context.WithTimeout(ctx, 3*time.Second),
}
同步写入 MySQL + Elasticsearch 时，为什么搜不到刚插入的数据？
这不是代码 bug，是 Elasticsearch 默认的 refresh 机制在起作用：文档写入后默认 1 秒才可被搜索到（near real-time），而 MySQL 的 INSERT 是立即可见的。用户点“发布博客”→ 立刻去搜 → 找不到，就是这个原因。
立即学习“go语言免费学习笔记（深入）”；
- 开发期可临时加
Refresh: "true"强制刷新，但仅限单文档操作，批量导入时会严重拖慢性能 - 生产环境应改用异步同步：MySQL 写完后发消息（如 Kafka / Redis Stream），由独立 worker 拉取并调用 ES 的
BulkIndex，同时控制 refresh interval（如设为30s） - 别依赖
GET /index/_refresh手动刷——它锁整个分片，高并发下反而造成搜索延迟毛刺
Gin 路由里做全文搜索，怎么避免阻塞 HTTP handler？
ES 查询本身不耗 CPU，但网络 IO 和上下文超时控制不到位，会让整个 HTTP handler 卡住。尤其当 ES 集群响应慢、或用户传了模糊词触发大量分词时，req.Do() 可能 hang 住几秒。
- 必须用带 cancel 的 context：从 Gin 的
c.Request.Context()派生，再加 timeout，不能直接用context.Background() - 别在 handler 里做重试逻辑：ES 客户端已内置重试（
MaxRetries: 3），自己再包一层for i := 0; i 会导致超时叠加 - 聚合类查询（如
aggs）要预估 size：如果用户搜 “手机”，ES 默认只返回前 10 个 bucket，但前端可能需要 top 50 品牌，就得显式设"size": 50，否则前端永远收不到全量统计
真正麻烦的不是写法，而是当 ES 返回 503 Service Unavailable 时，Gin handler 已经写了部分 response header，你没法优雅 fallback 成 “稍后再试” 页面——只能靠前置网关或前端重试兜底。
