应用于ElasticSearch的C++ API——elasticlient - 教程

文章目录

• Elasticlient API
• • 安装elasticlient
  • • 错误处理
  • Elasticsearch Client 核心组件整理
  • • 1. 核心异常类（Exception Class）
    • 2. 核心客户端类（Core Client Class）
    • 3. 核心枚举（Enums）
    • 4. 配置选项结构体（Client Option Structs）
    • 5. Client 类核心构造函数
    • 6. Client 类核心成员函数
    • 补充说明
  • CPR Response 类使用手册
  • • 类概述
    • 构造函数
    • 核心成员函数
    • 响应数据成员（公开属性）
    • 使用示例
    • 关键特性
  • 新手索引模板
  • • 新手专用索引模板（7.x 适用）
    • 核心字段说明（新手必看）
    • 使用方法

Elasticlient API

因为这个API的版本较老，很久没更新了，所以用起来某些语法是必须要写的，不能完全照搬7.x的版本，比如_doc。但是其优点是用起来简单，接口少，适合入门和简单的任务操作。

安装elasticlient

#依赖库
sudo apt-get install libmicrohttpd-dev
# 克隆代码 
git clone https://github.com/seznam/elasticlient
# 切换目录 
cd elasticlient
# 更新子模块 
git submodule update --init --recursive
# 编译代码 
mkdir build
cd build
cmake ..
make
# 安装 
make install

错误处理

# make 的时候编译出错：这是子模块googletest没有编译安装 
#collect2: error: ld returned 1 exit status 
#make[2]: *** [external/httpmockserver/test/CMakeFiles/test
#server.dir/build.make:105: bin/test-server] Error 1 
#make[1]: *** [CMakeFiles/Makefile2:675: 
#external/httpmockserver/test/CMakeFiles/test-server.dir/all] Error 
#2 
#make: *** [Makefile:146: all] Error 2 
#解决：手动安装子模块 
cd ../external/googletest/
mkdir cmake && cd cmake/
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make && sudo make install

Elasticsearch Client 核心组件整理

1. 核心异常类（Exception Class）

类名	父类	作用	关键参数 / 方法
elasticlient::ConnectionException	std::runtime_error	处理 Elasticsearch 集群连接相关错误（如所有节点均无响应）	- 构造函数：explicit ConnectionException(const std::string &message)- 接收连接错误描述信息，用于抛出时提示具体异常原因

2. 核心客户端类（Core Client Class）

类名	作用	核心成员	关键特性
elasticlient::Client	管理 Elasticsearch 集群连接，提供请求执行接口（搜索、增删改查等）	- 隐藏实现：std::unique_ptr<Implementation> impl（封装底层连接逻辑）- 嵌套枚举 / 结构体：HTTPMethod、ClientOption 等	1. 支持多节点集群（通过节点 URL 列表初始化）2. 支持灵活配置（超时、代理、SSL 等）3. 自动重试（请求失败时遍历节点直到成功）4. 异常安全（移动语义支持，避免资源泄漏）

3. 核心枚举（Enums）

枚举名	所属类	枚举值	作用
HTTPMethod	elasticlient::Client	- GET: HTTP GET 方法- POST: HTTP POST 方法- PUT: HTTP PUT 方法- DELETE: HTTP DELETE 方法- HEAD: HTTP HEAD 方法	定义 performRequest 接口支持的 HTTP 请求类型，用于指定请求方式

4. 配置选项结构体（Client Option Structs）

所有选项均继承自 ClientOption，用于初始化 Client 时配置连接参数（超时、代理、SSL 等）。

结构体名	父类	作用	关键参数 / 方法
Client::ClientOption	-	配置选项抽象基类	- 纯虚方法：virtual void accept(Implementation &) const = 0（子类需实现具体配置逻辑）
Client::ClientOptionValue<T>	ClientOption	带值的配置选项模板（封装通用值存储逻辑）	- 成员变量：T value（存储配置值）- 方法：T getValue() const（获取配置值）- 支持移动语义（默认移动构造）
Client::TimeoutOption	ClientOptionValue<std::int32_t>	配置客户端请求超时时间（毫秒）	- 构造函数：explicit TimeoutOption(std::int32_t timeoutMs)- 超时单位：毫秒（默认构造 Client 时超时为 6000ms）
Client::ConnectTimeoutOption	ClientOptionValue<std::int32_t>	配置客户端连接超时时间（毫秒）	- 构造函数：explicit ConnectTimeoutOption(std::int32_t timeoutMs)- 区别于 TimeoutOption：仅控制 “连接建立” 阶段超时
Client::ProxiesOption	ClientOption	配置客户端 HTTP 代理	- 隐藏实现：std::unique_ptr<ProxiesOptionImplementation> impl- 构造函数：explicit ProxiesOption(const std::initializer_list<std::pair<const std::string, std::string>> &proxies)（接收 <协议, 代理URL> 列表，如 {"http", "http://127.0.0.1:8080"}）
Client::SSLOption	ClientOption	配置客户端 SSL 连接（证书、验证等）	- 隐藏实现：std::unique_ptr<SSLOptionImplementation> impl- 支持移动语义（SSLOption(SSLOption &&)）- 核心方法：void setSslOption(const SSLOptionType &)（设置具体 SSL 子选项）
Client::SSLOption::SSLOptionType	-	SSL 子选项抽象基类（SSLOption 的嵌套类）	- 纯虚方法：virtual void accept(SSLOptionImplementation &) const = 0（子类实现具体 SSL 配置）
Client::SSLOption::CertFile	SSLOptionType	配置 SSL 证书文件路径	- 成员变量：std::string path（证书文件路径）- 构造函数：explicit CertFile(std::string path)
Client::SSLOption::KeyFile	SSLOptionType	配置 SSL 证书密钥文件路径及密码	- 成员变量：std::string path（密钥路径）、std::string password（密钥密码，可选）- 构造函数：explicit KeyFile(std::string path, std::string password = {})
Client::SSLOption::CaInfo	SSLOptionType	配置自定义 CA 证书 bundle 路径	- 成员变量：std::string path（CA 文件路径）- 构造函数：explicit CaInfo(std::string path)
Client::SSLOption::VerifyHost	SSLOptionType	配置是否验证 SSL 主机名	- 成员变量：bool verify（true 验证，false 跳过）- 构造函数：explicit VerifyHost(bool verify)
Client::SSLOption::VerifyPeer	SSLOptionType	配置是否验证 SSL 对等端证书	- 成员变量：bool verify（true 验证，false 跳过）- 构造函数：explicit VerifyPeer(bool verify)

5. Client 类核心构造函数

构造函数签名	作用	关键参数说明	适用场景
explicit Client(const std::vector<std::string> &hostUrlList, std::int32_t timeout = 6000)	基础构造：初始化集群节点 + 请求超时	- hostUrlList：Elasticsearch 节点 URL 列表（每个 URL 需以 / 结尾）- timeout：请求超时（默认 6000ms）	简单集群连接（无代理、无 SSL）
explicit Client(const std::vector<std::string> &hostUrlList, std::int32_t timeout, const std::initializer_list<std::pair<const std::string, std::string>>& proxyUrlList)	带代理构造：基础配置 + 代理	- proxyUrlList：代理列表（<协议, 代理URL>）	需要通过代理连接集群的场景
template <typename... Opts> Client(const std::vector<std::string> &hostUrlList, Opts&&... opts)	可变参数构造：支持多类型配置选项	- opts：任意 ClientOption 子类实例（如 TimeoutOption、SSLOption 等）- 特性：后传入的同类型选项覆盖前一个	复杂配置场景（需同时设置超时、SSL、代理等）
Client(Client &&)	移动构造	- 转移 impl 所有权，避免资源拷贝	客户端对象移动（如函数返回、容器存储）

6. Client 类核心成员函数

函数签名	作用	关键参数	返回值	异常抛出
void setClientOption(const ClientOption &opt)	动态设置客户端配置（构造后补充配置）	- opt：任意 ClientOption 子类实例（如超时、SSL）	无	无（参数非法时可能间接抛出）
cpr::Response performRequest(HTTPMethod method, const std::string &urlPath, const std::string &body)	通用请求接口：发送任意 HTTP 请求到集群	- method：HTTP 方法（HTTPMethod 枚举）- urlPath：URL 路径（节点 URL 后追加部分，如 _search）- body：请求体（JSON 格式字符串）	cpr::Response（包含响应状态、 headers、body）	ConnectionException（所有节点请求失败）
cpr::Response search(const std::string &indexName, const std::string &docType, const std::string &body, const std::string &routing = std::string())	搜索接口：封装 Elasticsearch 搜索请求	- indexName：索引名（如 my_index）- docType：文档类型（Elasticsearch 7+ 废弃，传空）- body：搜索条件（JSON，如 {"query":{"match_all":{}}}）- routing：路由键（可选，用于分片路由）	cpr::Response（搜索结果）	ConnectionException（所有节点失败）
cpr::Response get(const std::string &indexName, const std::string &docType, const std::string &id = std::string(), const std::string &routing = std::string())	读取接口：获取指定 ID 的文档	- id：文档 ID（必传，空则报错）- 其他参数同 search	cpr::Response（文档内容）	ConnectionException
cpr::Response index(const std::string &indexName, const std::string &docType, const std::string &id, const std::string &body, const std::string &routing = std::string())	写入接口：索引（新增 / 更新）文档	- id：文档 ID（空则由 ES 自动生成）- body：文档内容（JSON）- 其他参数同 search	cpr::Response（索引结果，含 ID、版本）	ConnectionException
cpr::Response remove(const std::string &indexName, const std::string &docType, const std::string &id, const std::string &routing = std::string())	删除接口：删除指定 ID 的文档	- id：文档 ID（必传）- 其他参数同 search	cpr::Response（删除结果，含是否成功、版本）	ConnectionException

补充说明

1. 隐藏实现（Pimpl 模式）：Client 及 ProxiesOption/SSLOption 使用 std::unique_ptr<Implementation> 封装底层逻辑，降低接口耦合，便于版本迭代。
2. 模板与泛型：ClientOptionValue<T>、可变参数构造函数等使用模板，支持灵活扩展配置类型（无需修改原有代码即可新增选项）。
3. 依赖项：依赖 cpr 库（HTTP 客户端），cpr::Response 为第三方类型，包含响应状态码（status_code）、响应体（text）等字段。

CPR Response 类使用手册

类概述

类别	说明
类名	cpr::Response
功能	封装 HTTP 请求的响应数据
命名空间	cpr
头文件	#include "cpr/response.h"

---

构造函数

函数签名	参数说明	作用描述
Response()	无参数	创建空的响应对象
Response(std::shared_ptr<CurlHolder> curl, std::string&& p_text, std::string&& p_header_string, Cookies&& p_cookies, Error&& p_error)	curl: CURL 句柄 p_text: 响应正文 p_header_string: 原始响应头 p_cookies: Cookies 数据 p_error: 错误信息	使用已有数据构造响应对象

---

核心成员函数

函数名	参数	返回值	作用描述
GetCertInfo()	无	std::vector<std::string>	获取 SSL 证书信息
operator=(Response&&)	old: 右值引用	Response&	移动赋值运算符
operator=(const Response&)	other: 常量引用	Response&	拷贝赋值运算符

---

响应数据成员（公开属性）

成员变量	类型	说明
status_code	long	HTTP 状态码 (如 200, 404, 500)
text	std::string	响应正文内容
header	Header	解析后的响应头 (键值对形式)
url	Url	最终请求的 URL (考虑重定向)
elapsed	double	请求耗时 (秒)
cookies	Cookies	服务器返回的 Cookies
error	Error	错误信息 (请求失败时使用)
raw_header	std::string	原始响应头字符串
status_line	std::string	HTTP 状态行
reason	std::string	状态码原因短语
uploaded_bytes	cpr_off_t	上传字节数
downloaded_bytes	cpr_off_t	下载字节数
redirect_count	long	重定向次数

---

使用示例

#include "cpr/cpr.h"
int main() {
// 发送 GET 请求
cpr::Response r = cpr::Get(cpr::Url{"https://httpbin.org/get"});
// 检查响应状态
if (r.status_code == 200) {
// 访问响应数据
std::cout << "Status: " << r.status_code << std::endl;
std::cout << "Body: " << r.text << std::endl;
std::cout << "Content-Type: " << r.header["Content-Type"] << std::endl;
std::cout << "Elapsed time: " << r.elapsed << "s" << std::endl;
} else {
std::cout << "Request failed: " << r.error.message << std::endl;
}
return 0;
}

关键特性

• 自动资源管理: 使用智能指针管理 CURL 资源
• 移动语义支持: 支持移动构造和移动赋值，提高性能
• 完整响应信息: 提供 HTTP 响应的所有关键信息
• 错误处理: 通过 error 成员提供详细的错误信息
• SSL 支持: 可通过 GetCertInfo() 获取证书信息

新手索引模板

新手专用索引模板（7.x 适用）

# 创建一个名为 "basic_template" 的索引模板
PUT _template/basic_template
{
# 1. 匹配的索引名称模式（必填）
"index_patterns": ["my-index-*"],  // 所有以 "my-index-" 开头的索引会应用此模板
// 必要性：必须填写，否则模板不知道作用于哪些索引
// 格式：数组形式，支持通配符 *（如 ["log-*", "data-*"]）
# 2. 模板优先级（可选，默认0）
"order": 1,  // 当多个模板匹配同一索引时，order 大的覆盖小的（7.x 用 order，8.x 后改 priority）
// 必要性：可选，只有多个模板冲突时才需要
// 格式：整数（如 1、10，数字越大优先级越高）
# 3. 索引的核心配置（必填，模板的核心内容）
"settings": {  // 配置索引的分片、副本、刷新频率等
# 主分片数量（非常重要）
"number_of_shards": 1,  // 每个索引的主分片数（7.x 默认1，创建后不可修改！）
// 必要性：建议显式指定，避免默认值不满足需求
// 新手建议：数据量小时填1，数据量大了提前规划（如3-5）
# 副本分片数量（影响可用性和查询性能）
"number_of_replicas": 0,  // 每个主分片的副本数（默认1，可随时动态修改）
// 必要性：建议指定，单节点环境必须设为0（否则分片分配失败）
// 作用：副本用于故障恢复和负载均衡，生产环境建议1-2
# 刷新频率（可选，影响实时性和性能）
"refresh_interval": "5s"  // 索引数据刷新到可搜索状态的间隔（默认1s）
// 必要性：可选，对实时性要求不高时调大（如5s）可提升写入性能
"analysis" : {
"analyzer" : {
"ik" : {
"tokenizer" : "ik_max_word"
}
}
}
},
# 4. 字段映射（定义数据结构，非常重要）
"mappings": {  // 7.x 移除了 "type"（默认只有 _doc 类型），直接配置 mappings
# 动态映射开关（控制是否自动创建未定义的字段）
"dynamic": "false",  // false：忽略未定义的字段；true：自动创建；strict：禁止并报错
// 必要性：建议显式指定，新手推荐 false（避免字段类型自动推断错误）
# 预定义字段（核心！必须根据自己的数据结构定义）
"properties": {
# 示例1：时间字段（日志/事件类数据必选）
"create_time": {
"type": "date",  // 类型：日期（支持格式化字符串或时间戳）
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"  // 支持的日期格式
// 必要性：如果数据有时间，必须定义，否则会被当成文本
},
# 示例2：文本字段（需要分词查询的内容，如标题、描述）
"title": {
"type": "text",  // 类型：文本（会被分词，支持模糊查询）
"analyzer": "ik_max_word"  // 分词器（需提前安装IK插件，否则用默认standard）
// 必要性：可选，默认用standard分词器（英文友好，中文差）
},
# 示例3：关键字字段（精确匹配/聚合，如状态、ID）
"status": {
"type": "keyword"  // 类型：关键字（不分词，支持精确匹配、排序、聚合）
// 必要性：枚举值（如状态、类型）必须用keyword，否则无法精确查询
},
# 示例4：数字字段（整数/小数）
"count": {
"type": "integer"  // 类型：整数（其他可选：long（大整数）、float/double（小数））
// 必要性：数字必须定义类型，否则会被当成文本，无法做范围查询
},
# 示例5：布尔字段（true/false）
"is_active": {
"type": "boolean"  // 类型：布尔（只能存true/false）
// 必要性：布尔值必须定义，否则可能被当成文本
}
}
},
# 5. 索引别名（可选，方便查询）
"aliases": {
"my-index-all": {}  // 为匹配的索引自动创建别名，后续可通过别名查询所有匹配的索引
// 必要性：可选，适合需要批量查询多个索引的场景（如按日期划分的日志）
}
}

核心字段说明（新手必看）

1. index_patterns

   • 决定模板作用于哪些索引（如 my-index-* 匹配 my-index-1、my-index-2023 等）。
   • 格式固定为数组，支持通配符 *。

2. settings

   • number_of_shards：创建后不能改，新手单节点环境填 1 即可，多节点可根据数据量增加（如 3）。
   • number_of_replicas：单节点必须设为 0（否则分片无法分配），多节点建议 1（保证可用性）。

3. mappings

   • dynamic: false：避免 Elasticsearch 自动推断字段类型（比如把数字当文本）。
   • properties：必须根据自己的实际数据定义字段！比如你的数据有 name、age，就必须在这里声明它们的类型（text/keyword/integer 等）。

4. 字段类型选择指南

   数据类型	对应 Elasticsearch 类型	用途示例	必要性
   时间	date	创建时间、日志时间	有时间数据则必须
   可分词的文本	text	标题、描述、内容	需模糊查询则必须
   不可分词的文本	keyword	状态（success/error）、ID	需精确匹配则必须
   整数	integer/long	数量、年龄	数字必须，否则无法计算
   小数	float/double	价格、分数	同上
   布尔值	boolean	是否启用、是否删除	布尔值必须

使用方法

1. 把上述模板中的 my-index-* 改成你需要的索引前缀（如 user-*、log-*）。
2. 在 properties 里删掉示例字段，换成你自己的数据字段（比如你的数据有 username、age、register_time，就定义这三个字段）。
3. 通过 Kibana Dev Tools 或 Postman 执行上述请求，创建模板。
4. 之后创建匹配前缀的索引（如 my-index-1）时，会自动应用模板配置。