Fiber 集成 Elasticsearch 需手动配置官方 elasticsearch-go 客户端、正确构造 DSL（如 multi_match 含 analyzer）、定义结构体精准解析 highlight 和 aggregations，避免反序列化错误。
Fiber 是 Go 语言的轻量级 Web 框架，本身不内置 Elasticsearch 支持，必须手动集成。它不像 Spring Boot 那样有 spring-boot-starter-data-elasticsearch 这类开箱即用的模块。想用 Fiber 做全文检索，核心是：选对客户端、正确构造查询 DSL、处理返回结构、避免反序列化陷阱。
用 elasticsearch-go 官方客户端连接 ES
elasticsearch-go（v8.x 对应 ES 8.x，v7.x 对应 ES 7.x）是 Elastic 官方维护的 Go SDK，比第三方库更稳定、更新及时。别用已归档的 olivere/elastic，它不支持 ES 8 的 API 变更（比如移除了 type、强制 HTTPS + 认证）。
- 必须核对版本：ES 8.15.1 → 用
github.com/elastic/go-elasticsearch/v8 - 初始化时传入正确的
uris和认证信息，ES 8 默认启用安全认证 - 示例初始化：
cfg := elasticsearch.Config{ Addresses: []string{"https://localhost:9200"}, Username: "elastic", Password: "changeme", Transport: &http.Transport{ TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, // 开发环境可跳过证书校验 }, } es, err := elasticsearch.NewClient(cfg) - 生产环境必须关闭
InsecureSkipVerify，并配置 CA 证书
构建 match_query 或 multi_match 查询 DSL
Fiber 不提供查询构建器，所有 DSL 都得手写 JSON 或用 map[string]interface{} 构造。中文检索依赖 IK 分词器，字段必须设为 text 类型并指定 analyzer: "ik_max_word"，否则 match 查不到结果。
- 错误写法：
match_query直接查keyword字段 → 返回空 - 正确写法：确保索引 mapping 中
title是text类型，且用了 IK 分词 - 简单全文查询示例：
query := map[string]interface{}{ "query": map[string]interface{}{ "multi_match": map[string]interface{}{ "query": "云计算教程", "fields": []string{"title^3", "content^2", "tags"}, "analyzer": "ik_max_word", }, }, } - 注意：
analyzer要写在multi_match内部，不是外层；^3表示字段权重，影响评分排序
用 fiber.Ctx.JSON() 返回高亮结果时字段易错
ES 返回的高亮内容在hits.hits[].highlight 下，是 map[string][]string 结构，但 Go 默认反序列化会丢掉 key（比如 title 字段高亮数组），或把 []string 当成 []interface{} 导致 panic。
- 别直接
ctx.JSON(200, res)原始响应体 ——highlight会是nil或类型错误 - 推荐做法：定义结构体显式接收关键字段，例如：
type SearchResult struct { ID string `json:"_id"` Score float64 `json:"_score"` Source map[string]interface{} `json:"_source"` Highlight map[string][]string `json:"highlight,omitempty"` } - 或用
json.RawMessage延迟解析 highlight 部分，避免中间转换损失
聚合查询（Aggregation）需手动解包 buckets
Fiber 里做热度统计、分类聚合时，ES 返回的是嵌套的 buckets 数组，Go 的结构体无法自动映射多层动态 key（比如按 category.keyword 聚合后，每个 bucket 的 key 是字符串，doc_count 是数字）。
- 常见错误：定义
Aggs map[string]struct{ Buckets []Bucket }，但 Bucket 字段名与 ES 返回不一致（ES 返回的是key，不是Key） - 正确方式：用
map[string]interface{}先接顶层 aggs，再逐层取buckets，用类型断言提取：aggData := res.Aggregations["category_agg"].(map[string]interface{}) buckets := aggData["buckets"].([]interface{}) for _, b := range buckets { bucket := b.(map[string]interface{}) key := bucket["key"].(string) count := int(bucket["doc_count"].(float64)) // 处理 key/count } - 这种写法丑但可靠；追求类型安全可写自定义 UnmarshalJSON 方法，但小项目没必要
Elasticsearch 的查询逻辑和返回结构在 Go 里没有魔法封装，Fiber 只负责 HTTP 层转发和响应。真正容易卡住的点，永远是 mapping 定义是否匹配、DSL 键名大小写是否准确、以及 Go 对动态 JSON 的宽容度太低——宁可多打几行类型断言，也别信“自动反序列化能猜对”。
