用 C++ 写 Web 服务实战（八）：libuvcpp 1.4.0 核心特性与高级模块深度解析
前七篇我们从零搭起了 Web 应用，走完了路由、中间件、上传、WebSocket、推送、SSL/TLS、生产部署、性能调优和测试调试。整个系列围绕“怎么用”展开，但有一个问题始终没有系统回答：libuvcpp 这个库本身到底提供了哪些能力？它的模块边界在哪里？哪些是稳定的、哪些是实验性的？
这篇是实战系列的第八篇，也是承上启下的一篇。我们暂时跳出“写业务代码”的视角，从库的使用者视角，系统梳理 libuvcpp 1.4.0 的模块体系、核心 API 和高级特性。读完这篇，你对这个库的能力全景会有一个完整的认知，后续再深入某个具体模块时知道从哪里查、怎么用。
一、1.4.0 版本概览：模块分层与版本脉络
libuvcpp 的版本演进有一条清晰的脉络：
| v1.1.0 | 核心封装 + Net + Web + WebApp + SSL，API 稳定 |
| v1.2.0 | HTTP/2（nghttp2 + ALPN），调试库，性能优化，六平台预编译 |
| v1.3.0 | 多事件循环横向扩展（set_loops），大量性能与语义修复，十二篇指南 |
| v1.4.0 | 当前版本，1.1.x–1.3.x 全部改动折叠，新增 WSDL/SOAP 模块、JSON 反射、PageHeap 门禁 |
当前源码树就是 1.4.0，UVCPP_VERSION_STRING 报告的就是这个值[reference:0]。v1.0.0 到 v1.4.0 是已打标签的正式发布。
模块分层从下往上：
应用层
┌──────────────┐
│ web (HTTP/WS) │ ← uvcpp_http_client/server, uvcpp_ws_client/server
├──────────────┤
│ http2 │ ← h2 会话/连接层、nghttp2 胶水（UVCPP_ENABLE_NGHTTP2=ON）
├──────────────┤
│ ssl (TLS) │ ← uvcpp_ssl, uvcpp_ssl_context (OpenSSL 封装)
├──────────────┤
│ net │ ← uvcpp_tcp_client/server, uvcpp_udp_client/server
├──────────────┤
│ handle + req │ ← uvcpp_loop, uvcpp_tcp, uvcpp_timer, uvcpp_write, …
├──────────────┤
│ uvcpp core │ ← uvcpp_buf, uvcpp_thread, uvcpp_alloc, …
└──────────────┘
再往上还有 webapp——建在 web 模块之上的应用框架，写业务 handler 就行，不用拼报文[reference:1]。
二、核心模块速查：你手里有哪些牌
2.1 Handle + Req：底层基础设施
libuvcpp 把 libuv 的核心句柄和请求封装为 C++ 类，命名统一为 uvcpp_ 前缀的下划线风格[reference:2]：
| 事件循环 | uvcpp_loop |
| 流式句柄 | uvcpp_tcp, uvcpp_pipe, uvcpp_udp, uvcpp_tty |
| 定时器与钩子 | uvcpp_timer, uvcpp_idle, uvcpp_prepare, uvcpp_check |
| 信号与进程 | uvcpp_signal, uvcpp_process |
| 文件系统 | uvcpp_fs, uvcpp_fs_event, uvcpp_fs_poll |
| 轮询 | uvcpp_poll, uvcpp_async |
| 请求 | uvcpp_write, uvcpp_connect, uvcpp_shutdown, uvcpp_work, uvcpp_getaddrinfo, uvcpp_getnameinfo, uvcpp_udp_send, uvcpp_random |
每个句柄类都遵循 RAII：析构时自动关闭，句柄的生命周期不再需要手动干预。
一个重要的语义修正： 1.3.0 之前 uvcpp_handle 的拷贝构造、拷贝赋值与 clone() 被从公开接口删除——它们的实现其实是 memcpy 一个活着的 uv_handle_t（连着 loop 指针与邻居指针），结果是双重释放，或者把活句柄从自己的循环队列里摘掉。现在被彻底封死了。
2.2 Net 模块（UVCPP_BUILD_NET=ON，默认开启）
| uvcpp_tcp_client | 高级 TCP 客户端，双模式 API（异步回调 / 同步 wait() 带超时） |
| uvcpp_tcp_server | TCP 服务端，bind() + listen(连接回调, backlog) |
| uvcpp_udp_client | UDP 客户端，双模式发送/接收 |
| uvcpp_udp_server | UDP 服务端，bind() / recv_start() |
TCP 服务端有一点值得注意：连接回调是 listen() 的第一个参数，没有单独的 on_connection()。所有连接共用同一个读回调（通过 set_read_callback() 设置），数据、对端关闭、读错误被明确拆成三个事件[reference:3]。
2.3 Web 模块（UVCPP_BUILD_WEB=ON）
| uvcpp_http_client | HTTP 客户端，keep-alive、流式解析、双模式 send() / send_wait()，set_http2_enabled() 开 h2 |
| uvcpp_http_server | HTTP 服务端，路由注册、每连接解析器、Upgrade 检测，set_http2_enabled() 开 h2 |
| uvcpp_http_parser | 流式 HTTP 解析器（封装 llhttp），PIMPL 模式 |
| uvcpp_http_request / uvcpp_http_response | 请求/响应对象，序列化与工厂方法 |
| uvcpp_ws_client | WebSocket 客户端（RFC 6455），解析 ws:// / wss:// |
| uvcpp_ws_server | WebSocket 服务端，通过 on_upgrade() 从 HTTP 自动升级 |
| uvcpp_ws_connection | WebSocket 连接：send_text() / send_binary() / send_ping() / send_close() |
| uvcpp_ws_parser | 流式 WebSocket 帧解析器（RFC 6455），8 状态状态机 |
| uvcpp_ws_frame | 帧结构体，带 opcode、mask、close-code 辅助 |
| uvcpp_http_common | HTTP 方法/状态码枚举、版本枚举（HVER_10/11/20） |
可选特性（需要显式开启，不会自动启用）：
- UVCPP_ENABLE_ZLIB=ON——WebSocket 的 Per-Message Deflate 压缩（RFC 7692）
- UVCPP_ENABLE_OPENSSL=ON——HTTPS（WSS）走 SSL/TLS 模块
- UVCPP_ENABLE_NGHTTP2=ON——HTTP/2（RFC 9113）走 nghttp2 静态链入[reference:4]
2.4 WebApp 框架（UVCPP_BUILD_WEBAPP=ON）
建在 web 模块之上的应用层——写业务 handler 就行，不用拼报文。
| uvcpp_web_app | 应用本体：配置、路由、中间件、生命周期（start / stop / join） |
| uvcpp_web_router | 模式路由——/user/:id 参数、/files/*path 通配，静态 > 参数 > 通配 |
| uvcpp_web_request / uvcpp_web_response | 请求/响应封装：查询串、表单、Cookie、路径参数、chunked、send_file |
| uvcpp_web_context | 每请求上下文：中间件链、post()、hold() / release()、用户数据 |
| uvcpp_web_static | 静态文件服务：ETag、Last-Modified、Range/206/416、LRU 缓存、SPA 回落 |
| uvcpp_web_upload / uvcpp_web_multipart | multipart 流式落盘，随机叶子名 + 六条大小上限 |
| uvcpp_web_stream | 请求体流式接收（on_data / on_end / pause / resume） |
| uvcpp_web_ws | 应用上的 WebSocket 端点（app.websocket("/chat/:room", handler)） |
| uvcpp_web_ws_client | WebSocket 客户端：回调装在客户端上 + 可选自动重连 |
| uvcpp_web_work_limit | 工作线程池准入闸门（uv_queue_work 的背压） |
| uvcpp_log / uvcpp_log_console | 两级日志：等级 + 模块，sink 可插拔 |
| uvcpp_web_json | nlohmann/json 的收口层——不让异常穿透 libuv 回调 |
webapp 模块通过 FetchContent 拉入 nlohmann/json 作为 JSON 后端[reference:5]。
三、高级模块：1.4.0 的增量能力
3.1 HTTP/2：只走 TLS + ALPN 的明确取舍
HTTP/2 基于 nghttp2 静态链入，通过 UVCPP_ENABLE_NGHTTP2=ON 显式开启。UVCPP_ENABLE_NGHTTP2 在 UVCPP_ENABLE_OPENSSL=OFF 时会强制关闭——给一条 warning，而不是留一个根本跑不起来的配置[reference:6]。
设计上的关键取舍：本库的 h2 只走 TLS + ALPN——不做 h2c、不做 prior-knowledge、不做 RFC 8441、不做 :protocol。没有 ALPN 就没有可协商的东西，自动“升级”只能靠猜。
底层的 uvcpp_http_server 需要 set_http2_enabled(true) 并且在 SSL context 上显式设置 set_alpn_select_protos({"h2","http/1.1"})；uvcpp_http_client 只需要 set_http2_enabled(true)（它自己构建 per-connection ALPN 列表）；而 uvcpp_web_app 把这些都替你接好了[reference:7]。
已知的一项待办：流级背压（pause_stream() / resume_stream()、peer_window_size()）已经在协议层实现，但暂无应用层调用方——框架侧没有任何调用点，h2 上“边收边给”的流式请求体因此仍不可达。
3.2 SSL/TLS 模块（UVCPP_ENABLE_OPENSSL=ON）
| uvcpp_ssl_context | SSL/TLS 上下文（封装 SSL_CTX*），证书/密钥加载，自签名证书生成 |
| uvcpp_ssl | 每连接 SSL 封装，handshake() / read() / write() / shutdown() |
| uvcpp_ssl_common | tls_version、tls_mode、tls_verify_mode、tls_cert_info 枚举/结构体 |
TLS 侧有一个安全细节值得强调：tls_verify_mode::PEER_STRICT 在客户端侧真的会校验主机名——connect() 收到的那个名字被钉给证书（数字 IP 字面量走 X509_VERIFY_PARAM_set1_ip_asc()，其余走 set1_host()），名字对不上的对端建立不起来。它此前与 PEER 完全等价（服务端侧至今仍然等价：本库的服务端不发 SNI、也不要求客户端证书，没有可校验的名字）[reference:8]。
3.3 Expand 内存池（默认关闭）
TCMalloc 风格的内存池：页堆、span 分配器、线程缓存、enterprise 分配器。用于降低高频异步场景下的分配开销。
自 v1.1.0 起默认关闭（UVCPP_BUILD_EXPAND=OFF），需要显式传 -DUVCPP_BUILD_EXPAND=ON 才启用。预编译产物是带池发布的；使用者什么都不用传——包里的 uvcpp/uvcpp_config.h 给出这个包实际用的值，自己再定义成别的值会直接 #error，而不是静默的分配器错配[reference:9]。
3.4 WSDL/SOAP 模块（UVCPP_ENABLE_WSDL=ON）
1.4.0 新增的模块，基于 pugixml 静态链入，提供：
- WSDL 文档解析与发布——把 WSDL 1.1 文档解析为模型，按 QName 查找，提供服务或生成文档
- SOAP 信封与分发——1.1 和 1.2 的 Envelope 与 soap:Fault，分发键从 binding 推导，九条拒绝规则
UVCPP_ENABLE_WSDL 在 UVCPP_BUILD_WEBAPP=OFF 时会强制关闭——这个模块建在 webapp 框架之上[reference:10]。
3.5 JSON 反射（doc/json-reflect-guide.md）
用一个宏声明字段表，在读写两个方向上共享：两层拆分、读语义、错误报告，以及 C++11 的代价[reference:11]。
四、多事件循环横向扩展
一条事件循环最多只能占满一个核。set_loops(n) 在同一个进程内起 1 条接受者循环 + n−1 条工作循环：接受这条路留在一个线程上，连接的 I/O 摊到各条工作循环[reference:12]。
#include <webapp/uvcpp_web_app.h>
using namespace uvcpp;
int main() {
uvcpp_web_app app;
app.set_host("0.0.0.0").set_port(8080).set_access_log(false);
// 1 条接受者 + 3 条工作循环。不能链式，且必须在 start()/run() 之前。
const int rc = app.set_loops(4);
if (rc != 0) return 1;
app.get("/json", [](uvcpp_web_request&, uvcpp_web_response& resp,
uvcpp_web_next) {
resp.json_str("{\\"hello\\":\\"world\\"}");
resp.end();
});
app.start(); // n > 1 只能 start()/start_background()，run(md) 会被拒
app.join();
return 0;
}
打开它之前值得知道这几条[reference:13]：
- 在 start() / run() 之前调用。 路由注册也要在 start() 之前——n > 1 时这条从“建议”变成“必须”。
- set_loops 返回 int，所以不能接在 set_host(…).set_port(…) 这条链上。 成功返 0；n 不在 1..64 内返 UV_EINVAL；运行时已经起来过返 UV_EBUSY。
- n == 1 与“从不调用它”逐字节相同——不建格子、不装钩子、不多起线程。档位拧到 1 不付任何代价。
- n > 1 时 run(md) 会被 UV_EINVAL 拒掉。 用 start() / start_background()，收尾用 stop() 与 join()。
- 连接落在哪条循环上是平台属性。 在支持 UV_TCP_REUSEPORT 的平台（Linux）上，每条循环绑定自己的监听 socket 到同一端口——下标 0 也包括在内——内核按 4-tuple 哈希把新连接散到各条循环，所以 connection_count_at(0) 通常非零；在 Windows（以及任何拒绝该 flag 的平台）上，下标 0 是纯接受者，按显式轮转把每条连接交给 1..n-1，它保持为零。loop_count() 报一共有几条循环，connection_count_at(i) 报每格各有多少。
- 要在 Linux 上演练另一条腿，set_handoff_forced(true)（在 set_loops() 之前调用）强制切换为 handoff 形状——一个仅测试用的钩子，用内核 fan-out 换用户态 handoff，不要上线。
五、构建选项全景
| UVCPP_BUILD_TESTS | ON | 构建测试可执行文件 |
| UVCPP_BUILD_FUNCTIONAL | ON | 构建功能测试套件（仅在 UVCPP_BUILD_TESTS=ON 时读取） |
| BUILD_SHARED_LIBS | ON | 构建共享库 |
| UVCPP_BUILD_EXPAND | OFF | 构建 Expand 模块（内存池） |
| UVCPP_BUILD_NET | ON | 构建 net 模块（TCP/UDP 客户端/服务端） |
| UVCPP_BUILD_WEB | OFF | 构建 web 模块（HTTP + WebSocket） |
| UVCPP_BUILD_WEBAPP | OFF | 构建 webapp 框架（路由/中间件/静态/上传/日志）。需要 UVCPP_BUILD_WEB=ON |
| UVCPP_BUILD_EXAMPLES | OFF | 构建 examples/ 中的示例 |
| UVCPP_BUILD_BENCH | OFF | 构建 bench/ 中的压测靶场 |
| UVCPP_ENABLE_ZLIB | OFF | 启用 zlib（WebSocket 压缩） |
| UVCPP_ENABLE_OPENSSL | OFF | 启用 OpenSSL（HTTPS/WSS） |
| UVCPP_ENABLE_NGHTTP2 | OFF | 启用 HTTP/2（nghttp2，静态链入）。需要 UVCPP_ENABLE_OPENSSL=ON 和 UVCPP_BUILD_WEB=ON |
| UVCPP_ENABLE_WSDL | OFF | 启用 WSDL/SOAP 模块（pugixml，静态链入）。需要 UVCPP_BUILD_WEBAPP=ON |
重要提醒： UVCPP_ENABLE_ZLIB 和 UVCPP_ENABLE_OPENSSL 不会在 UVCPP_BUILD_WEB=ON 时自动启用，必须显式 opt-in[reference:14]。
六、每个包都带调试版动态库
每份预编译包里现在同时携带 release 和 debug 两档共享库（uvcppd.dll / libuvcppd.dll / libuvcppd.so），MSVC 那份还带 uvcppd.pdb。方便单步进库内部排查问题。注意它仅用于调试，不可再分发——调试版 CRT 不可再分发且不包含在包内[reference:15]。
链接 debug 版用 -luvcppd。
七、文档体系与三道门禁
1.2.1 起新增十二篇指南：使用者向八篇与贡献者向四篇。并且进了三道文档门禁[reference:16]：
- 构建系统的选项与 README 选项表双向闭合、链接/路径/锚点可解析（check_docs.py）
- 22 篇文档里的 文件:行号 引用能解析且与内容哈希锁一致（check_doc_lines.py）
- 每个 cpp 片段都对着一个已 stage 的包、不加任何 -D 真编译（check_doc_snippets.py）——所以文档里的示例可以照抄
八、PageHeap 门禁：静默的 use-after-free 检测
1.4.0 引入了一个可选的测试门禁：在普通运行中，一个被释放的页仍然映射着、仍然持有旧字节——use-after-free 是静默的。Full PageHeap 会立即取消映射被释放的块，把同样的读取变成访问违规[reference:17]。
它曾经在普通构建、无内存池构建和单元测试层全部绿色的情况下，抓到 8 个 use-after-free 案例。
# 需要 Windows SDK 调试工具中的 gflags.exe（通常需要管理员 shell）
python -u tests/tools/run_pageheap_gate.py –tree build-webapp
它会先跑一遍基线，然后逐个用例“启用 PageHeap → 重读注册表 → 运行 → 禁用 → 重读注册表”，只把“基线绿色、PageHeap 下崩溃”计为捕获。它明显更慢，所以不在默认 ctest 套件中。
九、本篇小结与下一篇预告
这篇覆盖了 libuvcpp 1.4.0 的模块全景和高级特性：
模块分层——handle + req → net → ssl → http2 → web → webapp，逐层向上。
核心 API 速查——TCP/UDP 客户端/服务端、HTTP 客户端/服务端、WebSocket 客户端/服务端/连接/解析器、webapp 的路由/中间件/静态/上传/流式/日志。
高级模块——HTTP/2（只走 TLS + ALPN）、SSL/TLS（PEER_STRICT 客户端侧校验主机名）、Expand 内存池（默认关闭）、WSDL/SOAP（1.4.0 新增）。
多事件循环——set_loops(n) 突破单核天花板，注意返回 int、必须在 start() 前调用、平台差异。
构建选项——15 个 CMake 开关的默认值和依赖关系，注意 UVCPP_ENABLE_ZLIB / UVCPP_ENABLE_OPENSSL 不会自动启用。
测试门禁——PageHeap 门禁能抓到普通测试漏掉的 use-after-free。
下一篇预告： 模块全景讲完了，接下来需要深入具体模块。下一篇会聚焦 HTTP/2 的实战使用——ALPN 协商的完整流程、h2 会话的创建与生命周期、与 HTTP/1.1 的共存策略、以及流级背压的应用层打通进展。如果你在模块使用中遇到问题，欢迎在 GitHub Issues 提出。
