C++中httplib的使用小结
一、什么是 cpp-httplib？
cpp-httplib 是一个轻量级、单头文件的 C++ HTTP 客户端/服务器库。只需包含一个头文件，即可快速搭建 HTTP 服务或发起 HTTP 请求，无需依赖复杂的第三方库。
核心特性
| 特性 | 说明 |
|---|---|
| 单头文件 | 仅需 #include <httplib.h>，零依赖（除 SSL 外） |
| 跨平台 | 支持 Windows、Linux、macOS |
| HTTP/1.1 | 完整支持持久连接、管道化 |
| SSL/TLS | 可选 OpenSSL 或 mbedTLS 支持 HTTPS |
| 文件上传 | 原生支持 multipart/form-data |
| 正则路由 | 支持正则表达式匹配 URL 路径 |
二、如何安装和引入
1. 获取源码
git clone https://github.com/yhirose/cpp-httplib.git
2. 引入项目
cpp-httplib 是header-only库，只需将 httplib.h 复制到你的项目目录：
#include "httplib.h" // 或者 #include <httplib.h>（如果放在系统路径）
编译时记得链接线程库（Linux）：
g++ -std=c++17 server.cpp -o server -pthread
三、核心类与接口详解
3.1 命名空间与基础类型
namespace httplib
{
// 范围请求（用于断点续传）
using Range = std::pair<ssize_t, ssize_t>;
using Ranges = std::vector<Range>;
// 表单数据（文件上传用）
struct MultipartFormData
{
std::string name; // 表单字段名
std::string content; // 文件内容
std::string filename; // 文件名
std::string content_type;// MIME 类型
};
// 常用容器别名
using MultipartFormDataItems = std::vector<MultipartFormData>;
using Params = std::multimap<std::string, std::string>; // 查询参数
using Headers = std::multimap<std::string, std::string>;// HTTP 头部
} // namespace httplib3.2 Request 结构体：获取请求信息
当客户端发起请求时，cpp-httplib 会将所有信息封装在 Request 对象中：
struct Request
{
std::string method; // HTTP 方法：GET/POST/PUT/DELETE 等
std::string path; // 请求路径（如 /hi）
Headers headers; // 请求头
std::string body; // 请求体（POST 数据等）
Params params; // URL 查询参数（?name=zhangsan&age=18）
MultipartFormDataMap files; // 上传的文件
Ranges ranges; // 范围请求（断点续传）
Match matches; // 正则路由捕获组
};常用字段详解：
| 字段 | 用途 | 示例 |
|---|---|---|
| method | 判断请求类型 | req.method == "POST" |
| path | 获取请求路径 | /api/user/123 |
| params | 获取 URL 参数 | ?name=zhangsan → req.params["name"] |
| headers | 获取请求头 | req.headers["Content-Type"] |
| body | 获取原始请求体 | JSON 字符串或表单数据 |
| matches | 正则匹配结果 | 捕获 URL 中的动态部分 |
3.3 Response 结构体：构建响应
struct Response
{
std::string version; // HTTP 版本
int status = -1; // 状态码：200, 404, 500 等
std::string reason; // 状态描述
Headers headers; // 响应头
std::string body; // 响应体
// 便捷方法
void set_content(const std::string &s, const std::string &content_type);
void set_header(const std::string &key, const std::string &val);
};关键方法说明：
set_content(body, type)：设置响应内容和 MIME 类型
- "text/html" - HTML 页面
- "application/json" - JSON 数据
- "text/plain" - 纯文本
set_header(key, val)：添加自定义响应头（如 CORS 支持）
3.4 Server 类：搭建 HTTP 服务
class Server
{
public:
// 路由注册：支持 GET/POST/PUT/DELETE/PATCH/OPTIONS
Server& Get(const std::string &pattern, Handler handler);
Server& Post(const std::string &pattern, Handler handler);
Server& Put(const std::string &pattern, Handler handler);
Server& Delete(const std::string &pattern, Handler handler);
// 静态文件服务
bool set_mount_point(const std::string &mount_point,
const std::string &dir,
Headers headers = Headers());
// 启动服务器
bool listen(const std::string &host, int port);
private:
using Handler = std::function<void(const Request &, Response &)>;
};路由匹配规则：
- 精确匹配：
"/hi"匹配http://localhost:9000/hi - 正则匹配：
R"(/numbers/(\d+))"匹配/numbers/123并捕获数字
3.5 Client 类：发起 HTTP 请求
class Client
{
public:
explicit Client(const std::string &host, int port);
// GET 请求
Result Get(const std::string &path, const Headers &headers);
Result Get(const std::string &path,
const Params ¶ms,
const Headers &headers,
Progress progress = nullptr);
// POST 请求（多种重载）
Result Post(const std::string &path,
const std::string &body,
const std::string &content_type);
Result Post(const std::string &path, const Params ¶ms);
Result Post(const std::string &path,
const Headers &headers,
const Params ¶ms);
Result Post(const std::string &path,
const MultipartFormDataItems &items); // 文件上传
// PUT/DELETE
Result Put(const std::string &path, ...);
Result Delete(const std::string &path, ...);
};3.6 Result 类：处理响应结果
class Result {
public:
operator bool() const; // 是否请求成功
const Response& value() const; // 获取响应（可能抛出异常）
const Response& operator*() const; // 解引用访问
const Response* operator->() const; // 箭头访问
// 使用示例：
// auto res = client.Get("/api");
// if (res && res->status == 200) { ... }
};四、示例
4.1 搭建基础 HTTP 服务器
#include <httplib.h>
#include <iostream>
// 处理函数：打印请求详情并返回 HTML
void HelloWorld(const httplib::Request &req, httplib::Response &rsp) {
// 打印请求方法
std::cout << "Method: " << req.method << std::endl;
// 打印请求路径
std::cout << "Path: " << req.path << std::endl;
// 打印请求体
std::cout << "Body: " << req.body << std::endl;
// 遍历并打印所有请求头
std::cout << "Headers:" << std::endl;
for (auto &[key, val] : req.headers) {
std::cout << " " << key << " = " << val << std::endl;
}
// 遍历并打印 URL 查询参数
std::cout << "Params:" << std::endl;
for (auto &[key, val] : req.params) {
std::cout << " " << key << " = " << val << std::endl;
}
// 设置响应内容
std::string html_body = "<html><body><h1>Hello World</h1></body></html>";
rsp.set_content(html_body, "text/html");
rsp.status = 200; // HTTP OK
}
int main() {
httplib::Server svr;
// 注册路由：GET /hi
svr.Get("/hi", HelloWorld);
// 正则路由：匹配 /numbers/123 这样的路径
// R"()" 是原始字符串字面量，避免转义
svr.Get(R"(/numbers/(\d+))", [](const httplib::Request &req,
httplib::Response &rsp) {
std::cout << "Matched path: " << req.path << std::endl;
// req.matches[0] 是整个匹配的字符串（如 /numbers/123）
// req.matches[1] 是第一个捕获组（如 123）
std::cout << "Full match: " << req.matches[0] << std::endl;
std::cout << "Captured number: " << req.matches[1] << std::endl;
rsp.set_content("Number received: " + req.matches[1].str(),
"text/plain");
rsp.status = 200;
});
std::cout << "Server starting at http://0.0.0.0:9000" << std::endl;
// 启动服务器（阻塞调用）
svr.listen("0.0.0.0", 9000);
return 0;
}测试命令：
# 基础请求 curl "http://localhost:9000/hi?name=zhangsan&age=18" # 正则路由 curl "http://localhost:9000/numbers/123456"
4.2 HTTP 客户端示例
#include <httplib.h>
#include <iostream>
int main()
{
// 创建客户端，指定服务器地址和端口
httplib::Client client("192.168.65.128", 9000);
// 设置请求头
httplib::Headers headers =
{
{"Connection", "closed"}, // 短连接
{"User-Agent", "cpp-httplib-client"}
};
// 设置查询参数
httplib::Params params =
{
{"name", "lisi"},
{"age", "18"}
};
// 发起 GET 请求
auto rsp = client.Get("/hi", params, headers);
// 检查响应
if (rsp)
{ // 请求成功（网络层）
std::cout << "Status: " << rsp->status << std::endl;
if (rsp->status == 200)
{ // HTTP 成功
std::cout << "Response body:" << std::endl;
std::cout << rsp->body << std::endl;
}
else
{
std::cerr << "HTTP Error: " << rsp->reason << std::endl;
}
}
else
{
std::cerr << "Request failed (network error)" << std::endl;
}
// POST 请求示例（表单数据）
httplib::Params form_data = {
{"username", "admin"},
{"password", "123456"}
};
auto post_res = client.Post("/login", form_data);
// POST JSON 示例
std::string json = R"({"user":"admin","pass":"secret"})";
auto json_res = client.Post("/api/login", json, "application/json");
return 0;
}五、原理图
┌─────────┐ GET /hi?name=zhangsan HTTP/1.1
│ Client │ ───────────────────────────────────────►
└─────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Class Server │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ + get_handlers_ │ │ 路由表 │ │
│ │ + post_handlers_│───►├─────────────┬───────────────────┤ │
│ │ + listen(port) │ │ 路径 │ 回调函数 │ │
│ └─────────────────┘ │ /hi │ HelloWorld │ │
│ │ │ /numbers/(\d+)│ lambda │ │
│ │ └─────────────┴───────────────────┘ │
│ │ │ │
│ └──────────────────────────┘ │
│ 匹配成功，调用回调 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ void HelloWorld(const Request &req, │
│ Response &rsp) { │
│ // 访问 req.method, req.path │
│ // 访问 req.params["name"] │
│ // 设置 rsp.set_content(...) │
│ // 设置 rsp.status = 200 │
│ } │
└─────────────────────────────────────┘
六、实践与注意事项
6.1 线程安全
Server是多线程的，每个请求在独立线程中处理- 不要在处理函数中使用非线程安全的全局变量，如果一定要用则加锁保护
6.2 错误处理
// 始终检查 Result 对象
auto res = client.Get("/api");
if (!res)
{
// 网络错误：连接失败、超时等
std::cerr << "Network error" << std::endl;
return;
}
if (res->status != 200)
{
// HTTP 错误：404, 500 等
std::cerr << "HTTP " << res->status << ": " << res->reason << std::endl;
return;
}6.3 性能优化
// 启用 Keep-Alive（默认已启用）
httplib::Client client("api.example.com", 80);
client.set_keep_alive(true);
// 设置超时
client.set_connection_timeout(5); // 连接超时 5 秒
client.set_read_timeout(10); // 读取超时 10 秒6.4 HTTPS 支持
编译时链接 OpenSSL：
g++：
g++ -std=c++17 server.cpp -o server -pthread -lssl -lcrypto
如果是用CmakeLists，则需要：
#添加CPPHTTPLIB_OPENSSL_SUPPORT target_compile_definitions(testLLM PRIVATE CPPHTTPLIB_OPENSSL_SUPPORT) #链接库 target_link_libraries(OpenSSL::SSL OpenSSL::Crypto)
代码中使用：
httplib::SSLServer svr("./cert.pem", "./key.pem"); // HTTPS 服务器
httplib::SSLClient client("https://example.com"); // HTTPS 客户端到此这篇关于C++中httplib的使用小结的文章就介绍到这了,更多相关C++ httplib使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
这篇文章主要介绍了C++ 中类对象类型的转化的实例详解的相关资料,这里提供实例帮助大家学习理解这部分内容，需要的朋友可以参考下2017-08-08
QT工程的pro文件，在创建工程时由QTCreater自动创建，我们可以往里面添加内容，增加库文件的声明，包含路径、预处理器定义，生成目录，输出中间目录等等设置，本文就来介绍一下2022-04-04
这篇文章主要介绍了C++模拟实现stack和Queue的操作示例,文中通过代码示例给大家介绍的非常详细,对大家的学习或工作有一定的帮助,需要的朋友可以参考下2024-06-06
这篇文章主要介绍了c++验证哥德巴赫猜想，哥德巴赫猜想就是任一大于2的偶数，都可表示成两个素数之和,需要的朋友可以参考下2014-04-04
stack是C++标准模板库(STL)中的容器适配器,它提供后进先出(LIFO)的数据结构功能,接下来通过本文给大家讲解C++中的stack容器的相关知识,感兴趣的朋友跟随小编一起看看吧2026-02-02
在C++中初始化和赋值语句是两种不同的语法结构,本文主要介绍了C++ struct 初始化与赋值的实现,具有一定的参考价值,感兴趣的可以了解一下2025-03-03
visual studio 2013中配置opencv图文教程 Opencv2.4.9安装配置教程
这篇文章主要为大家详细介绍了Opencv2.4.9安装教程，以及在visualstudio 2013中opencv的配置步骤，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2017-04-04
C C++算法题解LeetCode1408数组中的字符串匹配
这篇文章主要为大家介绍了C C++算法题解LeetCode1408数组中的字符串匹配示例详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪2022-10-10
本文主要介绍了QT实现年会抽奖小软件的示例代码，文中通过示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2022-01-01
如果一个变量已经被声明成常变量，则只能用指向常变量的指针变量指向它，而不能用一般的（非const型的）指针变量指向它2013-10-10
最新评论