必须用olivere/elastic/v7而非go-elasticsearch/v8，因v7保留完整错误响应体、支持显式超时与raw response inspect，便于调试拼音模糊、同义词扩展等复杂DSL问题；v8错误包装过度、DSL字段名不校验、响应体默认被吞，查错成本高。
直接用 elastic/v7 客户端，别碰 v8 ——当前（2026年中）v8 的文档残缺、SearchRequest 构造反直觉、错误响应体默认被吞，线上查错成本翻倍。
为什么 elastic/v7 比 go-elasticsearch/v8 更适合语言学习类检索
语言学习场景下，全文检索常涉及拼音模糊、同义词扩展、错字容错、短语位置匹配等，这些都依赖精细控制 query DSL 和底层 HTTP 响应。而 elastic/v7（社区维护的 olivere/elastic 分支）保留了完整错误体、支持显式超时、允许 inspect raw response body，遇到 failed to parse date 或 no mapping found for field 这类问题，能立刻看到 ES 返回的原始提示；go-elasticsearch/v8 默认把 400 错误包装成泛化 error: bad request，必须手动读取 res.Body 才能拿到真正报错字段，开发调试效率低。
常见错误现象：
- 搜索返回空结果，但数据明明已索引 → 很可能是
match_phrase写成match_phase，v8 不校验 DSL 字段名，只在请求发出去后被 ES 拒绝 - 中文分词失效 →
ik_max_wordanalyzer 配置正确，但字段 mapping 类型是keyword而非text，v7 的CreateIndex错误响应会直接指出"type": "keyword" is not compatible with "analyzer"
初始化 client 必须设 transport 超时，否则 goroutine 卡死
默认 http.Transport 没有设置 Timeout、IdleConnTimeout，一旦 ES 响应慢或网络抖动，Go 请求会无限等待，拖垮整个服务。语言学习应用常有大量并发查词请求，这点尤其致命。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 显式配置
http.Transport，至少设Timeout: 5 * time.Second - 禁用 sniff（
SetSniff(false)），避免客户端自动探测集群节点，本地开发或单节点部署时反而引入 DNS 解析失败风险 - 不要全局单例复用一个
*elastic.Client实例做所有业务 —— 例如“用户生词本搜索”和“教材全文检索”应隔离连接池，防止某一路慢查询耗尽连接
示例片段：
client, err := elastic.NewClient(
elastic.SetURL("http://localhost:9200"),
elastic.SetSniff(false),
elastic.SetHealthcheck(false),
elastic.SetHttpClient(&http.Client{
Transport: &http.Transport{
Timeout: 5 * time.Second,
},
}),
)构造 query DSL 时，字段类型不匹配比语法错误更常导致空结果
语言学习数据里，常见字段如 word（需分词）、pos（词性，如 "v." / "n."，应为 keyword）、phonetic（拼音，需支持前缀匹配），三者 mapping 类型必须严格对应查询方式。DSL 写对了，但字段类型错了，ES 就静默跳过该条件。
使用场景与参数差异：
- 查“近义词”：用
terms_set+minimum_should_match_script，但要求字段是keyword数组，不是text - 查“带声调拼音”：用
prefix查询，字段必须是keyword；若用text+ik_pinyinanalyzer，则需match_phrase_prefix - 查“例句中含某词且前后 3 词内有转折连词”：要用
span_near，字段必须是text且启用 position_increment_gap
性能影响：字段类型错配不会报错，但会绕过倒排索引，退化为 filter cache miss 或全扫描，QPS 下降明显。上线前务必用 Kibana Dev Tools 手动验证 mapping 和 query 是否匹配。
bulk 写入时别忽略 failed items，尤其对词典类增量更新
语言学习系统常需批量导入新词、例句、释义，用 BulkProcessor 或 BulkService 提升吞吐量。但 ES bulk 响应是混合体："errors": true 表示部分失败，而 Go 客户端默认不抛异常，err == nil 时仍可能有几十条 document 写入失败。
容易踩的坑：
- 没检查
res.Failed()，导致词典漏数据却无感知 - 重试逻辑写在 bulk 外层，但 ES bulk 内部已对单条失败做了重试，外层再包一层易造成重复写入（如 _id 相同触发 version conflict）
- 没设
pipeline参数处理拼音生成，靠应用层拼接phonetic字段，导致 bulk 中某条因拼音生成 panic 而整批失败
建议每次 bulk 后遍历 res.Items，打印或上报 item.Status 和 item.Error.Reason，特别是 "type": "mapper_parsing_exception" 这类映射级错误，往往是字段类型或 analyzer 配置遗漏所致。
最常被忽略的点：mapping 一旦创建就不能改字段类型，语言学习数据常需后期加拼音、词向量、语义标签等字段，必须在第一次 CreateIndex 时就预留好 dynamic_templates 或明确声明所有未来可能用到的字段类型，否则只能 reindex —— 对百万级词库来说，停服 reindex 是不可接受的。
