推荐cpp-consul（无Boost依赖、C++11即可编译），避免已弃用的consul-cpp；需手动处理健康实例筛选、阻塞式KV长轮询及配置原子更新。
Consul C++ 客户端选哪个？别碰 consul-cpp（已弃用）
目前没有官方维护的 C++ Consul SDK，社区主流选择是 cpp-consul（GitHub 上 star 最多、仍在更新）或基于 HTTP 手撸。但要注意：consul-cpp 项目早在 2018 年就归档了，CMakeLists 里还硬编码了过时的 Boost 版本，编译会直接报 error: ‘shared_ptr’ is not a member of ‘boost’。除非你愿意花半天修依赖，否则跳过它。
推荐直接用 cpp-consul（https://github.com/abedra/cpp-consul），它封装了 /v1/health/service/{name} 和 /v1/kv/ 接口，底层用 libcurl + jsoncpp，无 Boost 依赖，C++11 即可编译。
- 确认你的构建系统能链接
libcurl和jsoncpp（Ubuntu 上装libcurl4-openssl-dev和libjsoncpp-dev） - git clone 后用
make install装到系统路径，或 CMake 中用find_package(consul REQUIRED) - 如果公司禁用外部库，就别强求 SDK——Consul HTTP API 本身足够简单，手写
curl_easy_perform+jsoncpp::Value解析更可控
服务发现：怎么查健康实例并自动重试？
cpp-consul 的 Consul::Health::service 默认只返回所有节点，不筛健康状态。你得手动加 passing=true 参数，否则可能拿到已下线的服务地址，导致连接超时。
实操时建议封装一层：
立即学习“C++免费学习笔记（深入）”；
Consul::Health health("http://127.0.0.1:8500");
auto res = health.service("user-service", true); // 第二个参数是 passing_only
if (!res.success()) {
// 别直接退出！Consul 可能临时不可达，应退避重试（比如指数退避 1s → 2s → 4s）
std::this_thread::sleep_for(std::chrono::seconds(1));
}
std::vector<Consul::Health::Node> nodes = res.nodes();
// 过滤出 Passing 状态（res.nodes() 已含 passing=true，但保险起见再 check status）
for (const auto& n : nodes) {
if (n.status == "passing") {
use_endpoint(n.address, n.service_port);
}
}
- 不要信任单次查询结果，Consul 健康检查有延迟（默认 10s），需配合本地缓存 + TTL 刷新逻辑
- 避免在主线程阻塞调用，尤其高并发场景——把查询放到独立线程或异步任务队列里
- 注意
Node.port是服务注册时填的ServicePort，不是 Consul Agent 端口（8500）
动态配置拉取：KV 读取要带 index 实现长轮询
直接 GET /v1/kv/config/app.json 只能拿当前值，无法感知变更。必须用 Consul 的阻塞查询（Blocking Query）机制：传 index 参数，服务端会 hold 连接直到有更新或超时（默认 10 分钟）。
用 cpp-consul 需手动拼 URL，它没封装 blocking 参数：
// 第一次读取，获取初始 index CURL *curl = curl_easy_init(); std::string url = "http://127.0.0.1:8500/v1/kv/config/app.json"; curl_easy_setopt(curl, CURLOPT_URL, url.c_str()); // ... 执行后从响应头 X-Consul-Index 拿到 index long last_index = get_index_from_header(response_headers); // 下次请求带上 index，阻塞等待变更 url += "?index=" + std::to_string(last_index) + "&wait=60s";
- wait 时间建议设为 60s，太短增加 Consul 压力，太长导致配置生效延迟
- 响应体为空（HTTP 200）表示超时未变，不是错误，要继续下一轮轮询
- 如果 KV 值是 JSON 字符串，注意 Consul 返回的是 base64 编码的
Value字段，需解码后再 parse
配置热更新怎么不崩服务？别直接改全局变量
收到新配置后，直接赋值给全局 std::string g_db_host 是危险的——其他线程可能正在读，造成数据竞争或解析一半的 JSON。
正确做法是用原子指针交换配置结构体：
struct Config {
std::string db_host;
int db_port;
bool enable_cache;
};
std::atomic<Config*> g_config{nullptr};
void on_kv_update(const std::string& json_str) {
auto new_cfg = std::make_unique<Config>();
// 解析 json_str 到 new_cfg，失败则 return
if (!parse_json(json_str, *new_cfg)) return;
auto old = g_config.exchange(new_cfg.release());
delete old; // 旧配置由上一轮 exchange 返回，安全释放
}
- 所有读配置的地方统一用
g_config.load()，确保看到的是完整、已解析好的结构体 - 不要在信号处理函数里更新配置——
curl和jsoncpp都不是 async-signal-safe - 如果配置项影响连接池等重型资源，更新后应触发 graceful reload（如关闭旧连接、新建连接池），而非立即切换
Consul 的 index 机制和配置结构体原子替换这两点，最容易被跳过，但恰恰是线上不抖动的关键。
