第24章 HTTP客户端

课程目录第24章 HTTP客户端

HTTP客户端：libcurl跨平台封装、REST API调用、HTTPS证书处理

说实话，HTTP客户端封装这件事，我踩过的坑比写过的代码还多。早年做嵌入式项目时，设备需要跟云端通信，那时候我天真地以为直接调socket就完事了。结果呢？HTTP协议头拼错、超时没处理、证书验证失败……那段时间我几乎每天都在跟服务器端同事道歉。

后来我学乖了——别自己造轮子，用libcurl。但libcurl是个C库，接口风格偏底层，直接用在C++项目里总觉得别扭。所以这一章，我就聊聊怎么把libcurl封装成一套优雅的C++接口，顺便把REST API调用和HTTPS证书处理这些头疼的事一并搞定。

为什么选libcurl？

跨平台HTTP库其实不少，但libcurl有几个硬核优势：

平台覆盖广：Windows、Linux、macOS、Android、iOS，甚至各种RTOS都能跑
协议支持全：HTTP/1.1、HTTP/2、HTTPS、FTP、SMTP……你想到的它基本都支持
社区活跃：遇到问题StackOverflow上一搜一大把，而且库本身还在持续更新
许可证友好：MIT许可证，商用无压力

我个人习惯是：能用现成库解决的问题，绝不自己写。libcurl就是那种“你只需要关心业务逻辑，网络细节交给它”的库。

libcurl的C++封装思路

libcurl的C接口长这样：

// 原生libcurl用法
CURL *curl = curl_easy_init();
if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.example.com/data");
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback);
    curl_easy_perform(curl);
    curl_easy_cleanup(curl);
}

嗯，这代码能跑，但每次都要手动管理CURL句柄、设置回调、检查错误……写多了真的烦。我的封装思路是：用RAII管理资源，用回调函数处理数据，用异常处理错误。

下面是我常用的封装骨架：

class HttpClient {
public:
    HttpClient() {
        curl_global_init(CURL_GLOBAL_DEFAULT);
        curl_ = curl_easy_init();
        if (!curl_) {
            throw std::runtime_error("Failed to initialize curl");
        }
    }

    ~HttpClient() {
        if (curl_) {
            curl_easy_cleanup(curl_);
        }
        curl_global_cleanup();
    }

    // 禁止拷贝
    HttpClient(const HttpClient&) = delete;
    HttpClient& operator=(const HttpClient&) = delete;

    // 允许移动
    HttpClient(HttpClient&& other) noexcept : curl_(other.curl_) {
        other.curl_ = nullptr;
    }

    std::string Get(const std::string& url) {
        // 实现GET请求
    }

    std::string Post(const std::string& url, const std::string& body) {
        // 实现POST请求
    }

private:
    CURL *curl_ = nullptr;
};

你看，构造函数里初始化libcurl，析构函数里自动清理。这样就算中间抛出异常，资源也不会泄漏。我在项目中用过这个模式好几年，从来没出过内存泄漏的问题。

REST API调用实战

REST API说白了就是HTTP方法+JSON数据。我封装了一个通用的请求方法：

class RestClient : public HttpClient {
public:
    struct Response {
        int statusCode;
        std::string body;
        std::map<std::string, std::string> headers;
    };

    Response Get(const std::string& endpoint) {
        return Request("GET", endpoint, "");
    }

    Response Post(const std::string& endpoint, const nlohmann::json& data) {
        return Request("POST", endpoint, data.dump());
    }

    Response Put(const std::string& endpoint, const nlohmann::json& data) {
        return Request("PUT", endpoint, data.dump());
    }

    Response Delete(const std::string& endpoint) {
        return Request("DELETE", endpoint, "");
    }

private:
    Response Request(const std::string& method, 
                     const std::string& url, 
                     const std::string& body) {
        // 设置URL
        curl_easy_setopt(curl_, CURLOPT_URL, url.c_str());

        // 设置HTTP方法
        if (method == "POST" || method == "PUT") {
            curl_easy_setopt(curl_, CURLOPT_POSTFIELDS, body.c_str());
            curl_easy_setopt(curl_, CURLOPT_POSTFIELDSIZE, body.size());
        }

        if (method == "PUT") {
            curl_easy_setopt(curl_, CURLOPT_CUSTOMREQUEST, "PUT");
        } else if (method == "DELETE") {
            curl_easy_setopt(curl_, CURLOPT_CUSTOMREQUEST, "DELETE");
        }

        // 设置请求头
        struct curl_slist *headers = nullptr;
        headers = curl_slist_append(headers, "Content-Type: application/json");
        headers = curl_slist_append(headers, "Accept: application/json");
        curl_easy_setopt(curl_, CURLOPT_HTTPHEADER, headers);

        // 执行请求
        Response resp;
        curl_easy_setopt(curl_, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl_, CURLOPT_WRITEDATA, &resp.body);

        CURLcode res = curl_easy_perform(curl_);
        if (res != CURLE_OK) {
            curl_slist_free_all(headers);
            throw std::runtime_error(curl_easy_strerror(res));
        }

        curl_easy_getinfo(curl_, CURLINFO_RESPONSE_CODE, &resp.statusCode);
        curl_slist_free_all(headers);

        return resp;
    }

    static size_t WriteCallback(void *contents, size_t size, 
                                 size_t nmemb, void *userp) {
        size_t totalSize = size * nmemb;
        std::string *output = static_cast<std::string*>(userp);
        output->append(static_cast<char*>(contents), totalSize);
        return totalSize;
    }
};

使用起来就清爽多了：

RestClient client;
auto resp = client.Get("https://api.github.com/repos/curl/curl");
if (resp.statusCode == 200) {
    auto json = nlohmann::json::parse(resp.body);
    std::cout << "Stars: " << json["stargazers_count"] << std::endl;
}

你想想看，如果每次调用API都要手动拼HTTP头、处理回调、解析状态码，那得写多少重复代码？封装之后，一行代码就是一个API调用。

HTTPS证书处理——避坑指南

HTTPS证书处理是HTTP客户端里最容易出问题的地方。我曾经在一个生产环境上遇到过：客户端突然连不上服务器，排查了半天才发现是证书过期了。

libcurl默认会验证服务器证书，这是好事。但有时候你需要处理一些特殊情况：

⚠️ 警告：生产环境中永远不要禁用证书验证！我曾经见过有人为了省事设置 CURLOPT_SSL_VERIFYPEER = 0，结果被中间人攻击，用户数据全部泄露。

正确的做法是：

// 设置CA证书包路径
curl_easy_setopt(curl_, CURLOPT_CAINFO, "/etc/ssl/certs/ca-certificates.crt");

// 或者使用系统默认的CA路径
curl_easy_setopt(curl_, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(curl_, CURLOPT_SSL_VERIFYHOST, 2L);

// 如果需要客户端证书（双向认证）
curl_easy_setopt(curl_, CURLOPT_SSLCERT, "/path/to/client.crt");
curl_easy_setopt(curl_, CURLOPT_SSLCERTTYPE, "PEM");
curl_easy_setopt(curl_, CURLOPT_SSLKEY, "/path/to/client.key");
curl_easy_setopt(curl_, CURLOPT_SSLKEYTYPE, "PEM");

这里有个细节：CURLOPT_SSL_VERIFYHOST设置为2表示严格验证主机名，设置为1在旧版本libcurl中表示不验证主机名（但新版本已经废弃了1这个值）。我建议始终设置为2。

跨平台证书路径处理

不同操作系统下CA证书的存放位置不一样，这是个让人头疼的问题：

操作系统	默认CA证书路径	备注
Linux	/etc/ssl/certs/ca-certificates.crt	Debian/Ubuntu系
Linux	/etc/pki/tls/certs/ca-bundle.crt	RedHat/CentOS系
macOS	/etc/ssl/cert.pem	或使用Keychain
Windows	使用系统证书存储	通过Schannel后端

我的做法是在初始化时自动检测：

void HttpClient::SetupCA() {
    std::vector<std::string> caPaths = {
        "/etc/ssl/certs/ca-certificates.crt",
        "/etc/pki/tls/certs/ca-bundle.crt",
        "/etc/ssl/cert.pem",
        "/usr/local/share/certs/ca-root-nss.crt"
    };

    for (const auto& path : caPaths) {
        if (access(path.c_str(), R_OK) == 0) {
            curl_easy_setopt(curl_, CURLOPT_CAINFO, path.c_str());
            return;
        }
    }

    // 如果都没找到，尝试使用系统默认
    curl_easy_setopt(curl_, CURLOPT_SSL_VERIFYPEER, 1L);
}

在Windows上，如果你用libcurl的Schannel后端，它会自动使用Windows证书存储，不需要手动指定CA路径。但如果你用OpenSSL后端，就得自己处理了。

超时与重试机制

网络请求不可能永远成功，所以超时和重试是必须的。我一般这样设置：

// 设置超时
curl_easy_setopt(curl_, CURLOPT_TIMEOUT, 30L);        // 总超时30秒
curl_easy_setopt(curl_, CURLOPT_CONNECTTIMEOUT, 10L); // 连接超时10秒

// 重试逻辑
int maxRetries = 3;
int retryDelay = 1000; // 毫秒

for (int i = 0; i < maxRetries; ++i) {
    CURLcode res = curl_easy_perform(curl_);
    if (res == CURLE_OK) {
        break;
    }

    // 只对特定错误重试
    if (res == CURLE_OPERATION_TIMEDOUT || 
        res == CURLE_COULDNT_CONNECT ||
        res == CURLE_RECV_ERROR) {
        std::this_thread::sleep_for(std::chrono::milliseconds(retryDelay));
        retryDelay *= 2; // 指数退避
    } else {
        throw std::runtime_error(curl_easy_strerror(res));
    }
}

指数退避这个策略，我在高并发场景下验证过效果很好。如果所有客户端都在失败后立即重试，那服务器可能会被重试请求打垮。加上退避延迟，大家错开时间重试，服务器压力就小多了。

知识体系总览

下面这张图概括了本章的核心内容：

总结

HTTP客户端封装这件事，说白了就是三件事：资源管理、接口抽象、安全处理。libcurl给了你强大的底层能力，但怎么把它用得更顺手，就看封装功夫了。

我个人建议：不要追求大而全的封装。根据你的业务场景，只封装你需要的功能。比如你只调REST API，那就只封装JSON相关的部分；如果你需要文件上传，再加multipart/form-data的支持。这样代码既简洁又容易维护。

最后提醒一句：证书验证永远不要跳过。安全这东西，出事就是大事。

💡 小技巧：调试HTTPS问题时，可以先用 curl -v https://your-api.com 在命令行测试，确认证书没问题再集成到代码里。这能帮你快速区分是网络问题还是代码问题。

📚 课程目录

HTTP客户端：libcurl跨平台封装、REST API调用、HTTPS证书处理

为什么选libcurl？

libcurl的C++封装思路

REST API调用实战

HTTPS证书处理——避坑指南

跨平台证书路径处理

超时与重试机制

知识体系总览

总结