Elasticsearch JS 客户端子客户端（Child Client）实践指南
一、子客户端是什么？
-
共享连接池：父/子实例共用 TCP 连接与健康状态，避免重复建连。
-
事件共享：父与子共用同一个事件发射器（diagnostic 等）。
- 如果你对父客户端做了扩展，子会继承；
- 若只对子扩展，父不会受到影响。
-
可配项：创建子客户端时，几乎可传入与
new Client()相同的选项，但不能覆盖连接池相关的选项（ssl/tls、agent、pingTimeout、Connection、resurrectStrategy）。 -
关闭行为：父或任一子调用
close()，所有共享该连接池的客户端都会被关闭。
二、快速上手
const { Client } = require('@elastic/elasticsearch')const client = new Client({cloud: { id: '<cloud-id>' },auth: { apiKey: 'base64EncodedKey' }
})const child = client.child({headers: { 'x-foo': 'bar' } // 只对这个子实例生效的默认请求头
})client.info().then(console.log, console.log)
child.info().then(console.log, console.log)
三、典型用法场景
1) 多租户隔离（按租户打标）
const tenantA = client.child({headers: { 'x-tenant': 'A' },opaqueIdPrefix: 'tenantA' // 便于链路追踪
})const tenantB = client.child({headers: { 'x-tenant': 'B' },opaqueIdPrefix: 'tenantB'
})
2) 业务线分治（不同默认超时/压缩）
const searchClient = client.child({requestTimeout: 10_000,compression: 'gzip',name: 'svc-search'
})const ingestClient = client.child({requestTimeout: 60_000, // 写入容忍更长name: 'svc-ingest'
})
3) 可观测与诊断（标识 + 上下文）
const analytics = client.child({name: 'analytics',context: { service: 'analytics', region: 'us-west-2' }
})// 共享的 diagnostic 事件仍然能区分来源（看 name/context/opaqueId）
client.diagnostic.on('response', (e) => {// e.meta.name / e.meta.request.params.context
})
四、最佳实践清单
- 能用 child 就别 new：只是“默认请求选项不同”时，用
child()既省内存又省握手成本。 - 别改连接池级别选项：在子客户端里避免配置/覆盖
ssl/tls、agent、pingTimeout、Connection、resurrectStrategy。 - 统一关闭：应用退出时只需在父或任一子上
close()一次即可。 - Cloud 场景勿 sniff：子客户端沿用父端策略；Cloud 背后是负载均衡，不需要嗅探。
- 链路可观测：为每个子客户端设置
name/opaqueIdPrefix/context，诊断日志更清晰。
五、反例与踩坑
- ❌ 把不同证书/代理放在子客户端里：这会触及连接池级别配置，API 不允许。需完全独立的
new Client()。 - ❌ 误以为 close 只关一个实例：任意父/子
close()会关闭所有共享该池的实例。 - ❌ 把大块业务逻辑写进请求 Hook 却未区分子实例：请根据
name/headers/context做分流，避免串线。
六、组合示例：多租户 + 搜索/写入分治
const base = new Client({ cloud: { id: '<cloud-id>' }, auth: { apiKey: '...' } })const tenant = (code) => base.child({headers: { 'x-tenant': code },opaqueIdPrefix: `tenant-${code}`
})const tAsearch = tenant('A').child({ name: 'A-search', requestTimeout: 10_000, compression: 'gzip' })
const tAingest = tenant('A').child({ name: 'A-ingest', requestTimeout: 60_000 })// 使用
await tAsearch.search({ index: 'docs-A', query: { match: { q: 'hello' } } })
await tAingest.index({ index: 'docs-A', document: { id: 1, title: 'hi' } })
七、总结
- child client = 共享连接池的“轻量克隆”，非常适合多租户、多业务线的默认配置隔离。
- 记住两条铁律：不改池级别配置、任意一端 close 全家关。
- 配合
headers / requestTimeout / compression / name / opaqueIdPrefix / context，就能在性能不打折的前提下实现清晰的隔离与可观测。