C++ REST SDK(cpprestsdk)完全指南:异步 HTTP/JSON/WebSocket 客户端与服务端开发实战

原创2026-10-13 19:39:372,296 阅读
文章标签:后端网络异步编程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 的三大要点:

  1. URI 构建:uri_builder(...).append_query(...) 负责把含空格等特殊字符的搜索词正确编码,避免手拼查询串导致请求失败;
  2. 异步流对接:response.body().read_to_end(*fileBuffer) 把响应流直接灌入文件 streambuf,全程异步、无需手动缓冲整个响应体;
  3. 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 需设置 scope wl.basic);
  • BlackJack(含 服务端 与 客户端):一个完整的 HTTP 服务端 + 客户端联调游戏示例。服务端演示了 http_listener 的四种方法分发(handle_get/put/post/delete)、uri_builder 路径拼接以及命令行指定监听端口(默认 34568)。

测试体系与质量保障

仓库内建了完整的测试基础设施,可为其 API 行为提供验证参考:

结语

cpprestsdk 以「异步优先」的 API 设计统一了 HTTP、JSON、URI、流、WebSocket 与 OAuth 等云服务开发的核心能力,其 PPL Tasks 组合模型与跨平台实现矩阵(WinHTTP/HTTP.sys、Boost.Asio、WinRT)至今仍在大量存量系统中稳定运行。无论你是需要在既有 C++ 工程中快速接入 REST 服务,还是希望借鉴其异步库设计思想,本文覆盖的安装、CMake 集成、核心组件与实战示例,都能作为一份可靠的参考资料;同时也请牢记 README 的提醒——新项目启动前,务必先评估该库的维护模式定位是否契合你的长期技术选型。

登录后查看全文
cpprestsdk