第69章 cURL

课程目录第69章 cURL

第69例：cURL：集成libcurl进行网络请求

网络请求，说白了就是让你的程序能跟远端的服务器说上话。C++标准库在这方面几乎是空白，所以libcurl就成了事实上的标准。我个人习惯把它叫做「C++程序员的HTTP工具箱」——你想想看，从简单的GET到复杂的FTP上传，它全包了。

为什么选libcurl？

我刚开始做项目时，也想过自己封装socket。后来发现，光是处理HTTP的chunked编码、重定向、SSL握手这些细节，就能让你写上千行代码。libcurl把这些脏活累活全干了，而且跨平台——Windows、Linux、macOS，一套API通吃。

嗯，这里要注意：libcurl是C语言写的，但C++项目集成它毫无压力。你只需要在CMake里把它找出来，然后链接上就行。

CMake集成libcurl

集成方式有两种：系统安装的libcurl，或者用FetchContent自动下载。我个人更推荐后者，尤其是团队协作时，能保证版本一致。

方式一：找系统安装的libcurl

find_package(CURL REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE CURL::libcurl)

就这么简单。CMake的FindCURL模块会帮你搞定头文件路径和库文件。我在项目中遇到过一个问题：有些Linux发行版把libcurl拆成了多个包，比如libcurl4-openssl-dev和libcurl4-gnutls-dev，选哪个取决于你用的SSL库。如果编译报错找不到头文件，八成是没装-dev包。

方式二：FetchContent自动下载

include(FetchContent)
FetchContent_Declare(
    curl
    GIT_REPOSITORY https://github.com/curl/curl.git
    GIT_TAG curl-8_9_1
)
FetchContent_MakeAvailable(curl)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE CURL::libcurl)

这种方式的好处是「开箱即用」。你想想看，新人拉下代码，cmake一跑，所有依赖自动搞定，多省心。不过要注意：第一次构建会花点时间编译libcurl，大概两三分钟吧。

libcurl的核心概念

libcurl的使用模式很固定，说白了就三步：

创建一个easy handle（可以理解成一个请求会话）
设置各种选项（URL、超时、回调函数等）
执行请求，然后清理

我画了张图，帮你理清这个流程：

实战：一个完整的GET请求

光说不练假把式。我们写一个完整的例子，从GitHub API获取仓库信息：

#include <iostream>
#include <string>
#include <curl/curl.h>

// 回调函数：libcurl收到数据后会调用它
static size_t WriteCallback(void* contents, size_t size, 
                            size_t nmemb, void* userp) {
    size_t totalSize = size * nmemb;
    std::string* str = static_cast<std::string*>(userp);
    str->append(static_cast<char*>(contents), totalSize);
    return totalSize;
}

int main() {
    CURL* curl = curl_easy_init();
    if (!curl) {
        std::cerr << "初始化失败" << std::endl;
        return 1;
    }

    std::string response;
    
    curl_easy_setopt(curl, CURLOPT_URL, 
                     "https://api.github.com/repos/curl/curl");
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
    curl_easy_setopt(curl, CURLOPT_USERAGENT, "MyApp/1.0");
    curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L);
    curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);

    CURLcode res = curl_easy_perform(curl);
    if (res != CURLE_OK) {
        std::cerr << "请求失败: " << curl_easy_strerror(res) 
                  << std::endl;
    } else {
        std::cout << "响应内容:\n" << response << std::endl;
    }

    curl_easy_cleanup(curl);
    return 0;
}

关键点解析：

WriteCallback：libcurl不会自动把数据存到std::string里，你得自己写回调。这个模式一开始可能觉得别扭，但好处是你可以控制内存怎么分配。
CURLOPT_USERAGENT：很多API会检查User-Agent，不设置可能被拒绝。我遇到过GitHub API直接返回403，就是因为没设这个。
CURLOPT_FOLLOWLOCATION：自动跟随重定向。有些URL会301跳转，不设这个你就只能拿到空响应。

POST请求与表单数据

POST请求也很常见。比如提交JSON数据：

struct curl_slist* headers = nullptr;
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

const char* jsonData = R"({"name": "test", "value": 42})";
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonData);
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, strlen(jsonData));

CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);

嗯，这里要注意：CURLOPT_POSTFIELDS设置的数据不会被libcurl复制，它只是保存指针。所以你要确保jsonData在请求执行期间一直有效。我曾经犯过这个错——把数据放在局部作用域里，结果请求还没发出去，数据就被销毁了。

错误处理与调试

网络请求不可能永远成功。超时、DNS解析失败、SSL证书问题，这些都得处理。我的经验是：

错误码	含义	常见原因
CURLE_COULDNT_CONNECT	连接失败	服务器宕机、防火墙拦截
CURLE_OPERATION_TIMEDOUT	操作超时	网络慢、服务器响应慢
CURLE_SSL_CONNECT_ERROR	SSL连接错误	证书过期、CA证书未配置
CURLE_HTTP_RETURNED_ERROR	HTTP返回错误	4xx或5xx状态码

调试小技巧：设置CURLOPT_VERBOSE为1L，libcurl会把请求和响应的详细信息打印到stderr。包括DNS解析、SSL握手、请求头、响应头等。调试阶段强烈建议开启。

避坑指南：我曾经在生产环境遇到过一个问题——libcurl默认会验证SSL证书，但有些内网环境用的是自签名证书。这时候请求会直接失败。解决方案有两个：要么用CURLOPT_CAINFO指定CA证书路径，要么（不推荐）设置CURLOPT_SSL_VERIFYPEER为0L跳过验证。我个人建议前者，安全第一。

多请求与连接复用

如果你需要同时发起多个请求，libcurl提供了multi接口。不过对于大多数场景，单线程的easy接口已经够用了。我只有在做爬虫或者批量API调用时才会用到multi接口。

另外，libcurl默认会复用HTTP/1.1的连接。如果你连续请求同一个服务器，它会自动保持连接，减少握手开销。这个特性是默认开启的，你不需要额外配置。

总结

libcurl的集成其实不复杂。CMake里几行代码就能搞定，C++代码里也就几个核心函数。但真正用好它，需要理解它的回调机制和选项系统。我建议你从最简单的GET请求开始，慢慢加上POST、自定义头、超时控制，一步步来。

嗯，最后提醒一句：别忘了在CMakeLists.txt里加上find_package(CURL)，不然链接时会报一堆undefined reference错误。这个坑我踩过不止一次。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

第69例：cURL：集成libcurl进行网络请求

为什么选libcurl？

CMake集成libcurl

方式一：找系统安装的libcurl

方式二：FetchContent自动下载

libcurl的核心概念

实战：一个完整的GET请求

POST请求与表单数据

错误处理与调试

多请求与连接复用

总结