Beego 不支持 Elasticsearch，因其 ORM 仅适配关系型数据库且 search 模块为空实现；必须用 olivere/elastic/v7 手动对接，注意 ES 版本、IK 分词器配置及索引预定义。
Beego 本身不提供 Elasticsearch 官方集成层，必须手动对接 REST API 或使用第三方 Go 客户端；直接用 elastic/v7（或 olivere/elastic）是最稳妥的选择，但要注意 Go 模块兼容性和 ES 版本对齐。
为什么不能用 Beego 内置 ORM 或 Search 模块
Beego 的 orm 模块只支持 MySQL、PostgreSQL、SQLite 等关系型数据库，不识别 Elasticsearch 的索引、mapping、DSL 查询等概念；它的 search 包是空实现，未绑定任何搜索引擎。试图把 ES 当作“另一个数据库”塞进 orm.RegisterDriver 会直接 panic。
常见错误现象：panic: unknown driver "elasticsearch" 或调用 orm.QueryTable("xxx").Filter("title__contains", "go") 时无响应、无日志、返回空结果。
- Beego 的查询语法（如
__contains、__gt）无法翻译成 ES 的match、range或bool查询 - ES 的分词、相关性评分、高亮、聚合等核心能力，在 Beego ORM 层完全不可见
- 索引生命周期（创建、更新 mapping、刷新）、bulk 写入等运维操作，ORM 也不提供入口
推荐客户端：olivere/elastic v7 + Beego Controller 封装
截至 2026 年，olivere/elastic 是 Go 生态中维护最活跃、文档最全的 ES 客户端，v7 分支明确支持 Elasticsearch 7.x（如 7.17），且与 Beego 2.x 兼容良好。不要用已归档的 elastic/v6 或尚未稳定支持 8.x 的新版 elastic。
安装命令：
go get github.com/olivere/elastic/v7@v7.0.30
在 Beego 启动时初始化全局 client（例如在 main.go 的 init() 或 run() 前）：
var esClient *elastic.Client
func initES() {
var err error
esClient, err = elastic.NewClient(
elastic.SetURL("http://localhost:9200"),
elastic.SetSniff(false),
elastic.SetHealthcheck(false),
)
if err != nil {
beego.Error("failed to create ES client:", err)
os.Exit(1)
}
}
-
SetSniff(false)和SetHealthcheck(false)必须显式关闭，否则 Beego 启动时可能因 ES 未就绪而卡死或 panic - 不要在每个 Controller 方法里重复 new client，连接池复用才能扛住并发
- 若 ES 启用了 Basic Auth，需加
elastic.SetBasicAuth("user", "pass")
全文检索请求怎么从 Beego Controller 发出去
Beego 的 Controller 只负责接收参数、调用业务逻辑、返回 JSON，ES 查询应封装为独立 service 函数，避免把 DSL 组装逻辑混进 Controller。
例如，实现一个按标题+内容模糊搜索的接口：
func (c *SearchController) Get() {
q := c.GetString("q")
from := c.GetInt("from", 0)
size := c.GetInt("size", 10)
results, err := searchArticles(esClient, q, from, size)
if err != nil {
c.Data["json"] = map[string]interface{}{"error": err.Error()}
c.ServeJSON()
return
}
c.Data["json"] = results
c.ServeJSON()
}
对应的 searchArticles 示例（使用 multi_match + highlight）：
func searchArticles(client *elastic.Client, q string, from, size int) ([]map[string]interface{}, error) {
res, err := client.Search().
Index("articles").
Query(elastic.NewMultiMatchQuery(q, "title^3", "content")).
Highlight(elastic.NewHighlight().Field("title").Field("content")).
From(from).Size(size).
Do(context.Background())
if err != nil {
return nil, err
}
var hits []map[string]interface{}
for _, hit := range res.Hits.Hits {
doc := make(map[string]interface{})
json.Unmarshal(hit.Source, &doc)
doc["highlight"] = hit.Highlight
hits = append(hits, doc)
}
return hits, nil
}
-
multi_match的字段权重（title^3）直接影响排序，不加权重会导致标题匹配和正文匹配一样重要 -
highlight返回的是字段级高亮片段，不是原始文档，必须手动合并回响应体 - 务必传
context.Background()，否则超时控制失效；生产环境建议用带 timeout 的 context
Mapping 和索引初始化容易被忽略的点
Beego 不会帮你建索引或推导 mapping。如果你直接往 articles 索引写入数据，ES 会自动 mapping（dynamic mapping），但中文字段默认变成 keyword 类型，导致 match 查询永远不命中——这是线上最常踩的坑。
正确做法：在项目启动时（比如 initES() 之后）显式创建索引并指定 IK 分词器：
_, err := client.CreateIndex("articles").BodyString(`{
"settings": {"analysis": {"analyzer": {"ik_analyzer": {"type": "custom","tokenizer": "ik_max_word"}}}},
"mappings": {
"properties": {
"title": {"type": "text", "analyzer": "ik_analyzer"},
"content": {"type": "text", "analyzer": "ik_analyzer"},
"created_at": {"type": "date"}
}
}
}`).Do(context.Background())
- ES 7.x 已移除 type，
mappings下直接写properties，别套一层_doc - IK 分词器必须提前装好（
elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.17.0/elasticsearch-analysis-ik-7.17.0.zip），版本必须严格匹配 ES - mapping 一旦创建就不能修改字段类型，改错只能删索引重建；上线前务必用 Kibana Dev Tools 验证
GET /articles/_mapping
