10分钟跑通第一个 C++ API：零配置上手 cpp-httplib 单头文件 HTTP 库

10分钟跑通第一个 C++ API：零配置上手 cpp-httplib 单头文件 HTTP 库

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

手写过 socket 的人都懂那种痛：客户端发来 chunked 编码，得一行行解析；浏览器突然塞一个Expect: 100-continue，你不知道它想干嘛；再想加 TLS，证书校验顺序又是一堆事。cpp-httplib 就是把这些脏活全干掉的单头文件 C++ HTTP 库，完整的 HTTP/HTTPS 服务器和客户端，就一个头文件，零依赖。

这篇文章直接给你做判断：它适合什么场景、能力边界在哪、上生产前要盯哪几个参数。

它到底是个什么东西

一句话定位：单头文件的 C++ HTTP 库，服务器和客户端都在里面，#include "httplib.h"就是全部接入成本。它的生态位要靠对比来看：

对比对象	它负责什么	和 cpp-httplib 的差别
手写 socket	底层字节流收发	HTTP 报文解析、chunked、multipart 全帮你做了
curl	单向发起请求的工具	自带完整 Server，服务端代码也能写
Boost.Beast	低层 HTTP 原语	不用自己组装执行模型，一行 listen 直接出服务

同时把"它不是什么"说清楚。它不是高并发网关，I/O 模型是一连接一线程的阻塞式；也不是全功能 Web 框架，没有依赖注入、ORM、模板引擎那套。它最适配的场景只有一类：你想在自己的 C++ 程序里"顺便"加几个 HTTP 接口。

📦 把 httplib.h 丢进项目，10 分钟跑通第一个 API

把httplib.h拷到项目目录就行，不需要 CMake，不需要拉依赖。代码不长，直接上：

#include "httplib.h" int main() { httplib::Server svr; // 服务端对象，所有接口挂在它上面 svr.Get("/", [](const httplib::Request&, httplib::Response& res) { res.set_content("Hello from cpp-httplib!", "text/plain"); }); // JSON 接口，字符串直接塞进去 svr.Get("/api/info", [](const httplib::Request&, httplib::Response& res) { res.set_content(R"({"name":"demo"})", "application/json"); }); svr.listen("0.0.0.0", 8080); // 阻塞式开始监听 return 0; }

编译就两行：

# Linux / macOS g++ -std=c++11 -pthread -o server server.cpp # Windows cl /EHsc /std:c++11 server.cpp

跑起来后浏览器打开http://localhost:8080/api/info，JSON 直接吐出来了。想系统一点，可以从官方入门文档接着看。它撑得起真应用，比如官方教程用它搭了一个翻译应用的后端：

⚡ 三个让人上头的特性

路径参数路由

一行声明:id，不用自己写正则拆路径，参数直接从请求对象里拿。

svr.Get("/users/:id", [](const httplib::Request& req, httplib::Response& res) { auto uid = req.path_params.at("id"); // 取出路径参数 res.set_content("user id: " + uid, "text/plain"); });

WebSocket 升级

别被名字吓到，握手、掩码、分帧全在库内部，你的回调只写业务。

svr.WebSocket("/ws", [](const httplib::Request&, httplib::ws::WebSocket& ws) { std::string msg; while (ws.read(msg)) { ws.send("echo: " + msg); // 把收到的消息原样回显 } });

一个 C++ WebSocket 服务器到这就齐了，仓库的示例目录里有带完整前端的 echo demo 可以直接抄。

HTTPS 一行开启

用 OpenSSL 的话，把Server换成SSLServer，证书和私钥路径传进去就完事：

#define CPPHTTPLIB_OPENSSL_SUPPORT // 必须在 include 前定义 #include "httplib.h" httplib::SSLServer svr("./cert.pem", "./key.pem"); svr.listen("0.0.0.0", 8443);

同一套接口换个壳就能进嵌入式桌面应用，比如官方把 REST API 包成了桌面翻译工具：

🚫 什么时候别用它

• 做扛万级 QPS 的 API 网关：一连接一线程的阻塞模型，连接数就是天花板，这个量级请上专用网关。
• 强依赖异步 I/O 的高性能中间件：没有事件循环模型，硬套等于重写它的核心。
• 团队已标准化 gRPC 微服务：它只讲 HTTP，protobuf 和 gRPC 得再引别的库，不如统一掉。

说白了就是：用它给自己程序加接口，别拿它当公共基础设施。

⚙️ 上生产前必须知道的 3 件事

1. 线程池别吃默认值：线程数默认和 CPU 核数相关，阻塞 I/O 意味着连接数上限≈线程数。按 QPS × 平均处理时长算清楚再上线，不够就改默认值重新编译，别猜。
2. 证书是运维问题不是编码问题：内部自签够用，生产上 CA 签发的证书并记下续期日期；客户端要校验对端时用set_ca_cert_path指定信任根，别在每台机器上散养 CA bundle。
3. 超时参数必须显式设：set_read_timeout/set_write_timeout防慢连接长期占线程，客户端同样要设连接和读写超时，默认值只适合本地调试。

适合的人群很明确：想在 C++ 程序里加 HTTP / WebSocket 接口，又不想引入一整个框架体系的开发者。把httplib.h拷进项目目录，下一个 commit 你的第一个 API 就活了。

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