用 Go Typed Client 快速上手 Elasticsearch —— 从建索引到聚合的完整实战

1. 准备工作

bash 复制代码

go get github.com/elastic/go-elasticsearch/v9

小贴士

如果你的集群启用了安全特性，需要在 elasticsearch.Config 中配置 Username/Password 或 APIKey。

Typed Client 通过 NewTypedClient 创建，内部复用 *http.Client，建议全局单例化，避免频繁建立连接。

go 复制代码

cfg := elasticsearch.Config{
	Addresses: []string{"https://es.local:9200"},
	Username:  "elastic",
	Password:  "mypassword",
	// APIKey: "...", 二选一
}
es, _ := elasticsearch.NewTypedClient(cfg)

2. 创建索引并映射字段

go 复制代码

import (
	"context"
	"github.com/elastic/go-elasticsearch/v9/typedapi/indices/create"
	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
)

_, err := es.Indices.Create("test-index").
	Request(&create.Request{
		Mappings: &types.TypeMapping{
			Properties: map[string]types.Property{
				"price": types.NewIntegerNumberProperty(), // 自动设置 "type":"integer"
			},
		},
	}).
	Do(context.Background())
if err != nil { /* 处理异常 */ }

要点

关键点	说明
`types.NewIntegerNumberProperty()`	Builder 会自动注入 `type=integer`，避免手写字符串
`.Request()`	接收强类型结构体，写错字段编译期即报错
`.Do(ctx)`	统一执行入口，返回 `*Response` 与 `error`

3. 写入文档

3.1 直接传递结构体（最常用）

go 复制代码

doc := struct {
	Id    int    `json:"id"`
	Name  string `json:"name"`
	Price int    `json:"price"`
}{1, "Foo", 10}

if _, err := es.Index("test-index").
	Request(doc).
	Do(context.Background()); err != nil {
	log.Fatal(err)
}

3.2 传递已序列化的 JSON

go 复制代码

payload := []byte(`{"id":1,"name":"Foo","price":10}`)
_, err := es.Index("test-index").Raw(payload).Do(context.Background())

适用于手动拼装 或性能敏感 场景，跳过 encoding/json 二次编码。

4. 读取文档

go 复制代码

resp, err := es.Get("test-index", "1").Do(context.Background())
if err != nil { ... }
fmt.Printf("Source=%s\n", resp.Source_)

5. 判断文档是否存在

go 复制代码

ok, err := es.Exists("test-index", "1").IsSuccess(context.Background())
switch {
case err != nil:
	// 请求失败
case ok:
	fmt.Println("文档存在")
default:
	fmt.Println("文档不存在")
}

IsSuccess 通过 HTTP 状态码 判断，内部已处理 404 与重定向。

6. 搜索

6.1 使用强类型 Request 构建 DSL

go 复制代码

import "github.com/elastic/go-elasticsearch/v9/typedapi/search"

resp, err := es.Search().
	Index("test-index").
	Request(&search.Request{
		Query: &types.Query{
			Match: map[string]types.MatchQuery{
				"name": {Query: "Foo"},
			},
		},
	}).
	Do(context.Background())

生成的 DSL

json 复制代码

{
  "query": { "match": { "name": { "query": "Foo" } } }
}

6.2 快速解析命中

go 复制代码

for _, hit := range resp.Hits.Hits {
	var d struct {
		Name  string `json:"name"`
		Price int    `json:"price"`
	}
	if err := json.Unmarshal(hit.Source_, &d); err != nil { ... }
	fmt.Printf("%s => %d\n", d.Name, d.Price)
}

7. 聚合 ------ 求价格总和

go 复制代码

total, err := es.Search().
	Index("test-index").
	Request(&search.Request{
		Size: some.Int(0), // 只要聚合结果，不要文档
		Aggregations: map[string]types.Aggregations{
			"total_prices": {
				Sum: &types.SumAggregation{Field: some.String("price")},
			},
		},
	}).
	Do(context.Background())
if err != nil { ... }

sum := total.Aggregations.Sum("total_prices").Value
fmt.Printf("价格总和：%.0f\n", *sum)

some.Int(0) 与 some.String() 是 Typed API 的 可空包装器 ，避免 *int 指针声明的繁琐。
结果通过 Aggregations.Sum("name") 类型安全地取出，无需手写 map 断言。

8. 进阶实践 & 性能建议

单例客户端 ：在 main() 或 DI 容器里初始化一次，复用连接池。
Context 超时 ：在高并发场景用 context.WithTimeout 控制慢查询。
Bulk 批量索引 ：大规模写入请使用 es.Bulk() + 并行 worker。
显式 Refresh ：测试场景可在写入后 .Refresh("wait_for")，生产环境由索引刷新策略决定。
Typed vs. Raw：Typed API 更安全、可读；Raw/Low-level Client 更灵活。可按模块混用。

9. 小结

Typed Request + Builder 让映射、DSL、聚合都拥有 IDE 自动补全和编译期校验。
常见场景（建索引 / CRUD / Search / Aggs）几乎只需一两行链式调用即可搞定。
掌握 some 包 的可空包装器、IsSuccess 以及 Do(ctx) 的范式，能写出既易读又健壮的 Go-ES 代码。

一步到位搭建起 Go × Elasticsearch 的类型安全数据层，让你的业务逻辑远离魔法字符串，尽享编译器的守护！