优先选与ES版本严格匹配的客户端：ES 7.x用olivere/elastic/v7，ES 8.x用elastic/go-elasticsearch/v8；务必设SetSniff(false)，预注册analyzer，批量写入用BulkProcessor。
olivere/elastic 和 elastic/go-elasticsearch 是 Go 项目集成 Elasticsearch 最常选的两个客户端，但它们行为差异大、版本错位多，直接套用示例容易在连接、索引创建或查询阶段静默失败。选错库或忽略版本约束，是多数人卡住的第一步。
选哪个客户端：v7 还是 v8？看你的 ES 版本，不是看 Go 版本
ES 7.x 和 8.x 的 HTTP 接口有实质性变化（比如 _type 彻底移除、默认安全开启、GET /_search 响应结构微调），客户端必须严格对齐：
-
olivere/elastic/v7只兼容 ES 7.x（含 7.17），不支持 ES 8.x —— 即使你用 Go 1.22 编译也跑不通 -
elastic/go-elasticsearch/v8是官方维护的 v8 客户端，强制要求 ES 8.x，且默认启用 TLS 和 Basic Auth（哪怕本地单节点也需显式关掉） - 若强行混用（如用 v8 客户端连 ES 7.10），常见错误是
400 Bad Request或error decoding response body，因为 JSON 字段缺失或类型不匹配
连接时必设 SetSniff(false)，尤其 Docker/K8s 环境
默认开启的节点嗅探（sniffing）会尝试请求 http://es-node:9200/_nodes/http 获取集群拓扑，但在容器网络中常返回内网 IP（如 172.18.0.3），导致后续请求超时或 403。这不是代码写错，是网络可见性问题。
正确做法：
- Docker Compose 场景下，
SetURL("http://elasticsearch:9200")+SetSniff(false) - ES 8.x +
go-elasticsearch时，还需加elastic.Config{Transport: &http.Transport{...}}显式禁用 TLS 验证（开发环境） - 漏掉
SetSniff(false)的典型现象：首次Ping()成功，但CreateIndex()卡死或返回context deadline exceeded
索引 Mapping 中的 analyzer 必须提前注册，不能靠运行时自动推断
Go 代码里写 "analyzer": "ik_max_word" 或 "gse_analyzer"，只在字段定义里生效；如果对应分词器没在 Elasticsearch 启动时加载或通过 API 注册，创建索引会直接报错 analyzer [ik_max_word] not found，而不是延迟到写入时报错。
立即学习“go语言免费学习笔记（深入）”；
验证方式（命令行）：
curl -X GET "localhost:9200/_analyze?pretty" -H 'Content-Type: application/json' -d'
{
"analyzer": "gse_analyzer",
"text": "自然语言处理"
}'
若返回 "error": {... "reason": "analyzer [gse_analyzer] not found"，说明插件未安装或配置未生效 —— 此时 Go 代码再怎么改 mapping 都无效。
- 第三方分词器（如
ik、gse）需单独下载插件并重启 ES - 自定义 analyzer 必须在
elasticsearch.yml或索引 settings 中明确定义，不能只写在 mapping 里 - ES 8.x 起，
index.analysis配置项已移至索引级别 settings，全局配置被废弃
批量写入用 BulkProcessor，别手写循环 Index()
单条 Index() 调用走完整 HTTP 请求+JSON 序列化+网络往返，吞吐量通常低于 200 docs/sec；而 BulkProcessor（olivere/elastic 提供）能自动合并、重试、限速，轻松压到 5k+ docs/sec。
关键配置点：
-
Workers：建议设为 CPU 核数，过高反而触发 ES 的thread_pool.bulk.rejected -
FlushInterval：设1s比设100ms更稳，避免小批量高频请求打满连接池 -
AfterFunc回调里检查res.Failed()，否则失败文档会被静默丢弃
漏掉这些，你会看到日志里大量 connection refused 或 ES bulk queue size 持续 > 90%，但 Go 程序看似“正常运行”。
