C++ REST SDK(cpprestsdk)完全指南:异步 HTTP/JSON/WebSocket 客户端与服务端开发实战
C++ REST SDK(cpprestsdk)完全指南:异步 HTTP/JSON/WebSocket 客户端与服务端开发实战
导读
cpprestsdk(C++ REST SDK)是微软推出的、面向云原生客户端-服务器通信的原生 C++ 异步库,它以现代 C++ 异步 API 设计为核心,帮助 C++ 开发者以统一的编程模型对接 RESTful 服务。本文以仓库根目录 README.md 为骨架,结合仓库内真实源码与示例,完整覆盖各平台安装方式、CMake 集成、HTTP 客户端/服务端、JSON、URI、异步流、WebSocket 与 OAuth 等核心组件,并给出可直接运行的入门代码,助你快速掌握这一经典库的工程化用法。
项目定位与当前状态
cpprestsdk 当前处于维护模式(maintenance mode),官方不建议在新项目中使用,但仍会持续修复关键缺陷与安全问题。
这是 README.md 开篇的明确声明。作为项目使用前的第一认知,这一点至关重要:对于已有大量历史代码的存量系统,cpprestsdk 仍然是一个稳定、可长期依赖的通信底座;而对于全新项目,则建议评估其维护状态后谨慎选型。
该库的本质定位是:面向云计算的客户端-服务器通信库,运行于原生代码环境,采用现代异步 C++ API 设计,目标用户是需要从 C++ 连接并与各类服务(REST API、WebSocket、OAuth 认证服务等)交互的开发者。
从仓库版本信息看,当前发布版本为 2.10.19(见 Release/include/cpprest/version.h,CPPREST_VERSION_MAJOR=2、CPPREST_VERSION_MINOR=10、CPPREST_VERSION_REVISION=19)。
各平台快速安装
README 给出了覆盖主流包管理器的安装方式。以下命令均来自 README.md,可直接复制使用:
| 平台 | 包管理器 | 安装命令 |
|---|---|---|
| Windows | vcpkg | PS> vcpkg install cpprestsdk cpprestsdk:x64-windows |
| Debian/Ubuntu | apt-get | $ sudo apt-get install libcpprest-dev |
| Fedora | dnf | $ sudo dnf install cpprest-devel |
| OS X | Homebrew | $ brew install cpprestsdk |
| Windows(Android 目标) | NuGet | PM> Install-Package cpprestsdk.android |
几点补充说明:
- vcpkg 双目标写法:
cpprestsdk cpprestsdk:x64-windows分别表示“默认 triplet 安装”与“显式 x64-windows triplet 安装”,这种写法确保同时获得默认与指定架构的构建产物。 - Android 场景:Windows 上通过 NuGet 包
cpprestsdk.android安装,仓库同时提供 Android 的 OpenSSL 补丁与构建脚本(见 Build_android/configure.sh 及 Build_android/openssl/ 下针对 openssl-1.0.2k 至 1.1.0j 各版本的 patch)。 - iOS 场景:仓库提供专用构建脚本 Build_iOS/configure.sh 与配套 Build_iOS/CMakeLists.txt。
其余平台、更多安装选项以及从源码构建的细节,README 指向官方 Wiki(Documentation 一节)。
从 CMake 集成 cpprestsdk
README 提供了标准 CMake 集成片段(当前仓库的 CMakeLists.txt 亦要求 CMake ≥ 3.9):
cmake_minimum_required(VERSION 3.9)
project(main)
find_package(cpprestsdk REQUIRED)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE cpprestsdk::cpprest)
底层依赖解析机制
find_package(cpprestsdk) 实际加载的是安装时由 CMake 生成的配置文件,其依赖解析逻辑见 Release/cmake/cpprestsdk-config.in.cmake:
- 在 Unix 上通过
find_dependency(Boost COMPONENTS random system thread filesystem chrono atomic date_time regex)定位 Boost(Windows 上仅需system date_time regex); - 按需定位 ZLIB(压缩支持)、OpenSSL(TLS/HTTPS)、Brotli(若未排除)与 WINHTTPPAL(Windows HTTP 兼容层)。
这些依赖是否被启用,取决于库构建时的实际配置(见下文“构建期组件开关”)。
目标名与命名空间
导出的 CMake 目标带 cpprestsdk:: 命名空间(见 Release/src/CMakeLists.txt 中 install(EXPORT cpprestsdk-targets ... NAMESPACE cpprestsdk::)),因此消费方使用 cpprestsdk::cpprest;同时它还会导出内部依赖目标 cpprestsdk_boost_internal、cpprestsdk_openssl_internal 等,便于传递链接。
SDK 功能全景
README 的 "What's in the SDK" 一节勾勒了五个核心能力维度,下面结合仓库源码逐一展开。
1. 网络协议层:HTTP 客户端 / 服务端
- HTTP 客户端:核心类为
web::http::client::http_client,定义于 Release/include/cpprest/http_client.h。构造函数要求 base URI 必须以http://或https://开头;提供request(...)系列重载,支持直接以 method、path、JSON body、字符串 body 发起请求,且所有请求均返回pplx::task<http_response>。 - HTTP 服务端:
web::http::experimental::listener::http_listener,定义于 Release/include/cpprest/http_listener.h(API 仍标注为 beta/experimental)。它通过support(...)注册回调处理入站请求,配合open()/close()启停监听。
2. JSON 解析与序列化
web::json::value 提供完整的 JSON 数据模型(number、boolean、string、object、array、null),定义于 Release/include/cpprest/json.h;解析与序列化实现位于 Release/src/json/(json.cpp、json_parsing.cpp、json_serialization.cpp)。通过 value::parse() 解析字符串、extract_json() 从 HTTP 响应中提取 JSON,并可与 http_client 无缝衔接。
3. URI 构建与解析
web::uri 与 web::uri_builder 定义于 Release/include/cpprest/uri.h 与 Release/include/cpprest/uri_builder.h,实现位于 Release/src/uri/。uri_builder 支持逐段追加 path、query、fragment,并自动完成百分号编码,是拼接 REST 请求路径的推荐工具。
4. 异步流(Async Streams)
concurrency::streams 命名空间提供基于 streambuf 的异步流抽象,覆盖文件流(Release/include/cpprest/filestream.h)、内存流(Release/include/cpprest/containerstream.h)、生产者消费者流(Release/include/cpprest/producerconsumerstream.h)等,用于流式收发请求/响应体、读写文件,避免整包缓冲内存。
5. WebSocket 客户端 与 OAuth
- WebSocket:
web::websockets::client::websocket_client(见 Release/include/cpprest/ws_client.h),支持连接、收发消息、关闭及代理。 - OAuth:
web::http::oauth1::experimental::oauth1_config与web::http::oauth2::experimental::oauth2_config(见 Release/include/cpprest/oauth1.h、[Release/include/cpprest/oauth2.h)),可注入http_client_config,让 HTTP 客户端自动携带认证信息。
6. PPL Tasks:异步编排模型
README 特别强调 PPL Tasks 是“基于 C++11 特性构建异步操作的强大组合模型”。其核心类型 pplx::task<T>、task_completion_event、cancellation_token 等定义于 Release/include/pplx/(pplxtasks.h、pplxcancellation_token.h、pplx.h 等),跨平台实现位于 Release/src/pplx/(Linux 使用 pplxlinux.cpp,Apple 使用 pplxapple.cpp,Windows 使用 pplxwin.cpp)。.then() 链式续延、task_completion_event 跨线程完成、cancellation_token 协作式取消,构成了整个 SDK 的异步骨架——所有 HTTP 请求、流读写都返回 task。
7. 平台覆盖与实现选择
README 声明支持的平台包括:Windows desktop、Windows Store(UWP)、Linux、OS X、Unix、iOS 与 Android,并支持 Visual Studio 2015/2017 及调试器可视化器。
仓库 Release/CMakeLists.txt 中的内部实现选择逻辑印证了这一矩阵(CPPREST_*_IMPL 系列缓存变量):
| 平台 | HTTP 客户端 | HTTP 服务端 | 文件 IO | PPLX |
|---|---|---|---|---|
| Windows Desktop | winhttp | httpsys | win32 | win |
| Windows Store/Phone | winrt | none | winrt | winrt |
| Linux/Android 等 Unix | asio(Boost.Asio) | asio | posix | linux |
| Apple(含 iOS) | asio | asio | posix | apple |
相应地,Release/src/CMakeLists.txt 会按上述选择编译对应的实现文件(如 http_client_asio.cpp、http_client_winhttp.cpp、http_client_winrt.cpp;http_server_asio.cpp、http_server_httpsys.cpp),并按需链接 Boost、OpenSSL、Winhttp、httpapi 等库。
构建期组件开关
从 Release/CMakeLists.txt 可以看出,源码构建时可通过 CMake 缓存变量裁剪功能:
| 变量 | 默认值 | 含义 |
|---|---|---|
WERROR |
ON | 将警告视为错误 |
CPPREST_EXCLUDE_WEBSOCKETS |
OFF | 排除 WebSocket 功能 |
CPPREST_EXCLUDE_COMPRESSION |
OFF | 排除压缩功能 |
CPPREST_EXCLUDE_BROTLI |
ON | 排除 Brotli 压缩(需先启用 compression) |
CPPREST_INSTALL_HEADERS |
ON | 安装头文件 |
CPPREST_INSTALL |
ON | 生成安装规则 |
BUILD_TESTS / BUILD_SAMPLES |
桌面平台 ON,iOS/Android/UWP OFF | 是否构建测试与示例 |
此外,Windows 上库的 ABI 会带工具集与版本标签(CPPREST_ABI_TAG,形如 ${TOOLSET}_2_10),Unix 下设置 SOVERSION 2.10。
第一个实战项目:发起一次 HTTP GET 请求
README 建议的入门路径是:拿到库之后,参照教程用 http_client 搭建第一个项目并完成一次基本 HTTP 请求。仓库中的 Release/samples/BingRequest/bingrequest.cpp 正是这样一份“最小但完整”的示范——它向 Bing 发起搜索 GET 请求并把 HTML 响应体写入文件。核心流程如下:
#include <cpprest/filestream.h>
#include <cpprest/http_client.h>
using namespace utility;
using namespace web::http;
using namespace web::http::client;
using namespace concurrency::streams;
int main(int argc, char* args[])
{
const string_t searchTerm = args[1];
const string_t outputFileName = args[2];
auto fileBuffer = std::make_shared<streambuf<uint8_t>>();
file_buffer<uint8_t>::open(outputFileName, std::ios::out)
.then(= -> pplx::task<http_response> {
*fileBuffer = outFile;
// 创建 HTTP 客户端,并用 uri_builder 拼接带查询串的路径
http_client client(U("http://www.bing.com/"));
return client.request(
methods::GET,
uri_builder(U("/search")).append_query(U("q"), searchTerm).to_string());
})
.then(= -> pplx::task<size_t> {
printf("Response status code %u returned.\n", response.status_code());
return response.body().read_to_end(*fileBuffer); // 将响应体异步写入文件
})
.then(= { return fileBuffer->close(); })
.wait();
return 0;
}
该示例浓缩了 SDK 的三大要点:
- URI 构建:
uri_builder(...).append_query(...)负责把含空格等特殊字符的搜索词正确编码,避免手拼查询串导致请求失败; - 异步流对接:
response.body().read_to_end(*fileBuffer)把响应流直接灌入文件streambuf,全程异步、无需手动缓冲整个响应体; - Task 链式编排:四个
.then()依次完成“打开文件 → 发请求 → 写文件 → 关文件”,最后.wait()阻塞到全部完成——这正是 PPL Tasks 组合模型的典型用法。
示例中还展示了代理配置的工程实践:通过环境变量 http_proxy 注入代理(http://192.1.8.1:8080 形式),并支持 auto 值触发 web::web_proxy::use_auto_discovery 自动发现。
http_client_config:请求行为调优
在实际项目中,http_client 常常需要第二个参数 http_client_config 进行调优。从 Release/include/cpprest/http_client.h 的类定义可以整理出以下核心配置项:
| 配置项 | 默认值 | 说明 |
|---|---|---|
set_timeout(...) |
30 秒(std::chrono::seconds(30)) |
每次发送/接收操作的超时时间 |
set_chunksize(size) |
0(即 64KB,64 * 1024) |
收发数据的内部缓冲块大小(仅作提示,实现可忽略) |
set_max_redirects(size) |
10 | 自动跟随重定向的最大次数,0 表示不自动跟随 |
set_https_to_http_redirects(bool) |
false | 是否允许自动跟随 HTTPS→HTTP 的重定向 |
set_validate_certificates(bool) |
true | 是否校验服务器证书(忽略校验有安全风险,需谨慎) |
set_request_compressed_response(bool) |
false | 是否请求 Content-Encoding 压缩响应(目前仅 Windows 与 OSX 支持,且有拷贝开销) |
set_proxy(web_proxy) |
— | 设置代理 |
set_credentials(credentials) |
— | 设置客户端凭据 |
set_oauth1(...) / set_oauth2(...) |
— | 注入 OAuth 1.0/2.0 配置 |
set_nativehandle_options(callback) |
— | 平台原生句柄自定义回调(WinHTTP 的 HINTERNET、WinRT 的 IXMLHTTPRequest2*、Asio 的 socket/SSL stream 指针) |
set_ssl_context_callback(callback) |
— | 非 Windows 平台上定制 boost::asio::ssl::context(如指定 CA、客户端证书) |
set_tlsext_sni_enabled(bool) |
true | 启用 TLS SNI(虚拟主机场景通常必须开启) |
注意:
set_guarantee_order已被标记为 deprecated(“混淆的 API 将在未来版本移除,如需保证请求顺序请使用 task continuations”),新代码应避免使用。
更进一步:从示例看完整应用形态
仓库 Release/samples/ 提供了覆盖各功能的可编译示例(通过 Release/samples/CMakeLists.txt 纳入构建),是深入学习的最佳素材:
- BingRequest:上文已剖析的 HTTP GET + 文件流示例;
- SearchFile:基于异步流的文件内容搜索工具,演示
file_stream、container_buffer、producer_consumer_buffer的组合使用,以及自定义type_parser从流中提取结构化结果; - Oauth1Client:OAuth 1.0 授权码流程(LinkedIn、Twitter),用本地
http_listener捕获重定向回 URI 并换发 access token,再通过注入oauth1_config的客户端访问 API; - Oauth2Client:OAuth 2.0 授权码流程(Dropbox、LinkedIn、Microsoft Live),核心套路与 OAuth1 一致:
build_authorization_uri()唤起浏览器 →oauth2_code_listener用token_from_redirected_uri()取码 →m_http_config.set_oauth2(...)注入后续请求。示例同时演示了不同服务商的差异适配(如 LinkedIn 需set_bearer_auth(false)、自定义 access token 字段名oauth2_access_token;Live 需设置 scopewl.basic); - BlackJack(含 服务端 与 客户端):一个完整的 HTTP 服务端 + 客户端联调游戏示例。服务端演示了
http_listener的四种方法分发(handle_get/put/post/delete)、uri_builder路径拼接以及命令行指定监听端口(默认 34568)。
测试体系与质量保障
仓库内建了完整的测试基础设施,可为其 API 行为提供验证参考:
- 单元测试框架使用第三方 UnitTest++(Release/tests/common/UnitTestpp/),测试运行器见 Release/tests/common/TestRunner/;
- 功能测试按模块组织:Release/tests/functional/http/client/(认证、重定向、代理、压缩、连接池、管线等)、Release/tests/functional/http/listener/、Release/tests/functional/json/(含
negative_parsing_tests负向解析与fuzz_tests)、Release/tests/functional/streams/、Release/tests/functional/uri/(含encoding_tests)、Release/tests/functional/pplx/、Release/tests/functional/websockets/client/ 等; - 构建与测试可通过 CMake 的
enable_testing()与BUILD_TESTS开关控制(见 Release/CMakeLists.txt)。
结语
cpprestsdk 以「异步优先」的 API 设计统一了 HTTP、JSON、URI、流、WebSocket 与 OAuth 等云服务开发的核心能力,其 PPL Tasks 组合模型与跨平台实现矩阵(WinHTTP/HTTP.sys、Boost.Asio、WinRT)至今仍在大量存量系统中稳定运行。无论你是需要在既有 C++ 工程中快速接入 REST 服务,还是希望借鉴其异步库设计思想,本文覆盖的安装、CMake 集成、核心组件与实战示例,都能作为一份可靠的参考资料;同时也请牢记 README 的提醒——新项目启动前,务必先评估该库的维护模式定位是否契合你的长期技术选型。