【C++】cpp-httplib基础使用

白藏y2026-03-29 10:23

目录

[一、什么是 cpp-httplib？](#一、什么是 cpp-httplib？)

核心特性

二、如何安装和引入

[1. 获取源码](#1. 获取源码)

[2. 引入项目](#2. 引入项目)

三、核心类与接口详解

[3.1 命名空间与基础类型](#3.1 命名空间与基础类型)

[3.2 Request 结构体：获取请求信息](#3.2 Request 结构体：获取请求信息)

[3.3 Response 结构体：构建响应](#3.3 Response 结构体：构建响应)

[3.4 Server 类：搭建 HTTP 服务](#3.4 Server 类：搭建 HTTP 服务)

[3.5 Client 类：发起 HTTP 请求](#3.5 Client 类：发起 HTTP 请求)

[3.6 Result 类：处理响应结果](#3.6 Result 类：处理响应结果)

四、示例

[4.1 搭建基础 HTTP 服务器](#4.1 搭建基础 HTTP 服务器)

[4.2 HTTP 客户端示例](#4.2 HTTP 客户端示例)

五、原理图

六、实践与注意事项

[6.1 线程安全](#6.1 线程安全)

[6.2 错误处理](#6.2 错误处理)

[6.3 性能优化](#6.3 性能优化)

[6.4 HTTPS 支持](#6.4 HTTPS 支持)

一、什么是 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. 获取源码

bash 复制代码 
git clone https://github.com/yhirose/cpp-httplib.git

2. 引入项目

cpp-httplib 是header-only 库，只需将 httplib.h 复制到你的项目目录：

cpp 复制代码 
#include "httplib.h"  // 或者 #include <httplib.h>（如果放在系统路径）

编译时记得链接线程库（Linux）：

bash 复制代码 
g++ -std=c++17 server.cpp -o server -pthread

三、核心类与接口详解

3.1 命名空间与基础类型

cpp 复制代码 
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 httplib

3.2 Request 结构体：获取请求信息

当客户端发起请求时，cpp-httplib 会将所有信息封装在 Request 对象中：

cpp 复制代码 
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 结构体：构建响应

cpp 复制代码 
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 服务

cpp 复制代码 
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 请求

cpp 复制代码 
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 &params,
               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 &params);
    Result Post(const std::string &path,
                const Headers &headers,
                const Params &params);
    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 类：处理响应结果

cpp 复制代码 
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 服务器

cpp 复制代码 
#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;
}

测试命令：

cpp 复制代码 
# 基础请求
curl "http://localhost:9000/hi?name=zhangsan&age=18"

# 正则路由
curl "http://localhost:9000/numbers/123456"

4.2 HTTP 客户端示例

cpp 复制代码 
#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;
}

五、原理图

cpp 复制代码 
┌─────────┐     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 错误处理

cpp 复制代码 
// 始终检查 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 性能优化

cpp 复制代码 
// 启用 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++：

bash 复制代码 
g++ -std=c++17 server.cpp -o server -pthread -lssl -lcrypto

如果是用CmakeLists，则需要：

cpp 复制代码 
#添加CPPHTTPLIB_OPENSSL_SUPPORT
target_compile_definitions(testLLM PRIVATE CPPHTTPLIB_OPENSSL_SUPPORT)

#链接库
target_link_libraries(OpenSSL::SSL OpenSSL::Crypto)

代码中使用：

cpp 复制代码 
httplib::SSLServer svr("./cert.pem", "./key.pem");  // HTTPS 服务器
httplib::SSLClient client("https://example.com");    // HTTPS 客户端

感谢阅读，本文如有错漏之处，烦请斧正。

相关推荐
Fortune792 小时前
自定义类型转换机制
开发语言·c++·算法
2301_814590252 小时前
实时音频处理C++实现
开发语言·c++·算法
第二只羽毛2 小时前
C++ 高并发内存池2
大数据·开发语言·jvm·c++·c#
小此方2 小时前
算法实战论01（双指针篇一）：双指针的核心思想与应用场景总结
c++·算法·力扣
IT从业者张某某2 小时前
基于DEVC++实现一个控制台的赛车游戏-01-背景知识
c++·游戏
2401_878530212 小时前
C++与FPGA协同设计
开发语言·c++·算法
2301_814590252 小时前
C++中的装饰器模式实战
开发语言·c++·算法
2301_804215413 小时前
模板元编程应用场景
开发语言·c++·算法
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09中国象棋-html版本10Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南