五分钟搭起 C++ HTTP 服务：单文件库 cpp-httplib 实战-平芜编程栈

五分钟搭起 C++ HTTP 服务：单文件库 cpp-httplib 实战

【免费下载链接】cpp-httplibA C++ header-only HTTP/HTTPS server and client library项目地址: https://gitcode.com/GitHub_Trending/cp/cpp-httplib

cpp-httplib 是一个单文件、header-only 的 C++11 HTTP/HTTPS 库：Server与Client全部封装在同一个httplib.h里，TLS、WebSocket、SSE、流式传输都有原生支持。不需要 CMake，不需要子模块——把这一个头文件拷进工程，#include之后就能编译运行。

五分钟把服务跑在 8080 端口

获取方式两种：克隆完整仓库（git clone https://gitcode.com/GitHub_Trending/cp/cpp-httplib），或者只把根目录的httplib.h拷进项目。把下面的最小程序存为server.cpp：

#include <httplib.h> using namespace httplib; int main(void) { Server svr; svr.Get("/hi", [](const Request & /*req*/, Response &res) { res.set_content("Hello World!", "text/plain"); }); svr.listen("0.0.0.0", 8080); }

这段代码就是仓库里example/hello.cc的原文。编译运行：

g++ -std=c++11 -pthread -o server server.cpp ./server # 然后 curl http://localhost:8080/hi

-pthread必须带，库内部用线程（即example/Makefile里的编译参数）；Windows 上用 MSVC 则写cl /EHsc /std:c++11 server.cpp。

客户端长什么样？同一个头文件里风格对称：httplib::Client cli("http://localhost:8080")，然后cli.Get("/hi")。返回值是 optional，成功时res->status、res->body就是状态码和响应体，失败时res.error()给出原因。

最值得记住的 4 个功能点

HTTPS 开箱即用，三种 TLS 后端可切换

在包含头文件之前定义宏，就拿到SSLServer/SSLClient这一对：

#define CPPHTTPLIB_OPENSSL_SUPPORT // 或 CPPHTTPLIB_MBEDTLS_SUPPORT / CPPHTTPLIB_WOLFSSL_SUPPORT #include "httplib.h" httplib::SSLServer svr("./cert.pem", "./key.pem"); svr.listen("0.0.0.0", 8443);

Mbed TLS、wolfSSL 通过另两个宏切换，对嵌入式环境更友好；mTLS 只需在SSLServer构造函数里多传一个客户端 CA 路径。

静态文件托管只要一行

svr.set_mount_point("/", "./www")就把/index.html映射到./www/index.html，自带常见扩展名的 MIME 映射表，POSIX 系统还会拒绝通过符号链接逃逸出挂载目录的请求。

WebSocket 与 SSE 内置

svr.WebSocket("/ws", [](const httplib::Request &req, httplib::ws::WebSocket &ws) { std::string msg; while (ws.read(msg)) { ws.send("echo: " + msg); } });

SSE 同样是注册一个路由持续推送事件，前端用标准事件流接收即可；细节看仓库根目录的README-websocket.md、README-sse.md、README-stream.md。

路由前的统一钩子

鉴权、限流、日志放在set_pre_routing_handler：返回Handled直接短路响应，返回Unhandled继续走正常路由。

谁会选它

嵌入式 / IoT 设备的 Web 管理页：设备上跑轻量 HTTP 服务，静态页面做界面，几个/api/*端点控制硬件，是最常见的形态。
给现有 C++ 程序加 REST 接口：内部服务、命令行工具想暴露数据，Server注册几个路由就行，不必引入重型框架。
服务间调用的 HTTP 客户端：Client是阻塞式语义，调用读起来像普通函数，适合编排多个下游服务。

官方文档里有一组从 REST 接口讲到 SSE 流式、再讲到 Web UI 和桌面单二进制的完整教程（docs-src/pages/en/llm-app/），能跑通这条链路，说明它从接口到应用端都够用：

同一个后端也可以直接以网页形态访问，前端就是普通地调 HTTP 接口：

硬边界：选型前先问的三个问题

阻塞式 I/O + 每连接一线程。README 开头就写明：如果你要的是非阻塞 I/O，这不是它。WebSocket 也是同一模型（每连接一条工作线程加一条心跳线程），且不实现 RFC 6455 的扩展（如permessage-deflate）。极致高并发、每连接独立协程的场景，请选异步框架。
只支持 HTTP/1.1。HTTP/2、HTTP/3（QUIC）均未实现，强依赖多路复用或 0-RTT 的链路要另选方案。
32 位平台不受支持。官方明确：32 位目标上可能能编译，但从未做过安全审查，仅影响 32 位平台的安全问题会被直接关闭。

另外三条使用注意：

生产环境务必走 HTTPS，别随手关掉证书校验；
客户端代码要处理if (auto res = cli.Get(...))的失败分支，res.error()给出原因，SSL 场景还能用ssl_error()/ssl_backend_error()拿到底层错误码；
静态文件服务器相关方法不是线程安全的，别在多线程里运行时改挂载点。

学习入口：从哪读起

example/：hello.cc、server.cc、client.cc、wsecho.cc、upload.cc等独立可编译的小例子，照着改最快。
docs-src/pages/en/tour/：按"客户端 → 服务器 → TLS → WebSocket"顺序写的入门教程，适合逐步跟。
docs-src/pages/en/cookbook/：超时、压缩、keep-alive、客户端日志等常见坑的食谱。
README-websocket.md与另外两个特性 README：WebSocket 的心跳、超时、子协议协商细节都在里面；httplib.h的内联注释本身就是一份完整 API 参考。