iris 框架无官方 elasticsearch 集成，需手动对接 olivere/elastic 客户端；务必配置 tls、禁用 sniff、启用健康检查，并在启动时显式建索引与 mapping，避免中文分词失效。
Iris 框架本身不提供 Elasticsearch 官方集成层，必须用 elasticsearch-go 客户端手动对接；直接 import 并调用 REST API 是最稳的路径，别指望“开箱即用”的 SearchService。
为什么 Iris 没有像 Laravel Scout 或 Yii2-elasticsearch 那样的封装？
Iris 是轻量级 Web 框架，定位是 HTTP 路由、中间件和响应控制，不内置 ORM、搜索、队列等业务层能力。它的生态里没有维护 Elasticsearch 适配器的官方或主流社区包——你看到的第三方 iris-elasticsearch 项目基本已归档或仅支持 ES 6.x，且无测试覆盖。
所以你得自己搭桥：用 olivere/elastic/v8（对应 ES 8.x）或 olivere/elastic/v7（对应 ES 7.17），配合 Iris 的 ctx.JSON() 和依赖注入做胶水层。
连接配置和客户端初始化容易漏掉什么？
常见错误是忽略 TLS、超时、健康检查这三项：
-
olivere/elastic默认不校验证书，生产环境必须显式设SetScheme("https")+SetHttpClient()注入带tls.Config{InsecureSkipVerify: false}的 client - 没设
SetSniff(false)：Iris 启动时若 ES 集群不可达，elastic.NewClient()会阻塞并 panic，而不是返回 error；关掉自动节点发现可避免启动失败 - 忘记
SetHealthcheck(true)和SetHealthcheckTimeout(5 * time.Second)：否则节点宕机后请求仍发过去，报no active connection found - ES 8.x 默认禁用
http.port，只开https.port，curl 测试得用curl -k https://127.0.0.1:9200，不是http://
建索引和 mapping 怎么写才不会上线后翻车？
mapping 一旦写入就不能改字段类型，而 Iris 不像 Yii/Laravel 那样有模型钩子自动同步。你得在应用启动时（比如 app.OnStart()）执行一次 PutMapping，且必须确保：index 名字与后续写入一致、analyzer 名称与插件注册名匹配（如 ik_smart）、date 字段显式声明 format。
示例片段（ES 8.x + ik 插件已装）：
mapping := `{
"mappings": {
"properties": {
"title": { "type": "text", "analyzer": "ik_smart" },
"content": { "type": "text", "analyzer": "ik_smart" },
"published_at": { "type": "date", "format": "strict_date_optional_time||epoch_millis" }
}
}
}`
_, err := esClient.IndexPutMapping().Index("article").BodyString(mapping).Do(ctx)
注意：IndexPutMapping() 在索引不存在时会自动创建，但如果你需要 control settings（如 number_of_shards），就得先用 IndexCreate() 显式建索引再套 mapping。
全文查询怎么避免 match 全部失效？
中文搜不出结果，八成是 analyzer 没生效或字段类型错了：
- 确认
title字段 mapping 是"type": "text"，不是"keyword"；"keyword"类型不走分词，match查询永远不命中 - 用
esClient.Analyze()手动测分词效果：esClient.Analyze().Index("article").Text("Gin框架集成Elasticsearch").Analyzer("ik_smart").Do(ctx)，看返回的 tokens 是否含"gin"、"框架" - 查询 DSL 别硬拼 JSON 字符串，用
elastic.NewQueryStringQuery("title:iris")或elastic.NewMatchQuery("title", "iris")，它们自动处理转义和上下文 - 高亮字段必须在
_source中存在，且 mapping 不能设"store": false；否则Highlight()返回空数组
复杂 bool 查询建议用 elastic.NewBoolQuery().Must(...).Filter(...) 分离相关性计算与过滤逻辑，filter 条件（如 status、range）进 Filter() 才能利用缓存。
真正麻烦的不是连上或查出数据，而是 mapping 固化前没压测分词效果、上线后才发现中文全搜不到；或者用了 SetSniff(true) 导致服务起不来却查不出原因。这些点不写死在启动脚本里，靠文档或注释根本挡不住人手误。
