1. 为什么选择libhv来构建你的HTTP服务端？
如果你正在寻找一个能让你在C++世界里快速搭建HTTP服务的“瑞士军刀”，那libhv绝对值得你花时间了解一下。我最早接触它，是因为厌倦了在项目里为了一个简单的内部管理后台，就得把Nginx、Apache或者一些庞大的Web框架搬出来，配置起来繁琐不说，依赖也多。后来在GitHub上闲逛发现了libhv，试用之后发现，它真的把“轻量”和“高性能”结合得相当不错。
简单来说，libhv是一个用纯C++编写的跨平台网络库，它封装了底层像epoll、kqueue、IOCP这些高性能I/O模型，给我们提供了一个非常清晰、易用的接口。它的目标很明确：让你用最少的代码，构建出性能足够强悍的网络应用，尤其是HTTP/HTTPS服务。对于需要快速开发一个内部工具、微服务原型，或者是一个对性能有要求的API网关中间件，libhv都是一个非常顺手的选择。
我自己的体会是，它的学习曲线非常平缓。你不需要先去啃一堆复杂的设计模式或者抽象概念，它的API设计得很直观，基本上你看完一个示例就能照猫画虎地跑起来一个服务。这对于我们日常开发中的“快速验证想法”场景来说，效率提升是巨大的。而且，它的性能表现也让我印象深刻，在常规的硬件上，单线程轻松处理几万QPS（每秒查询率）是家常便饭，这对于很多内部系统或者中小型对外服务来说，性能完全过剩了。
所以，无论你是一个想摆脱庞大框架束缚的C++后端开发者，还是一个需要为智能硬件设备编写一个轻量级控制服务的嵌入式工程师，libhv都能提供一个直接从代码层面掌控网络通信的爽快体验。接下来，我就带你从零开始，一步步用libhv构建一个功能齐全的HTTP服务端。
2. 五分钟快速上手：你的第一个HTTP服务
光说不练假把式，我们直接动手写代码。搭建一个最基本的、能响应请求的HTTP服务，用libhv只需要不到20行代码。我建议你跟着我一起敲，感受一下它的简洁。
首先，你需要准备好开发环境。libhv是跨平台的，在Linux、macOS和Windows上都能编译运行。最快捷的方式是从GitHub上克隆源码：
git clone https://github.com/ithewei/libhv.git cd libhv # 编译库和示例 make编译完成后，在bin目录下你会看到生成的可执行文件，比如httpd就是一个功能完整的示例服务端。但我们不直接用它，我们要自己从头写。
现在，创建一个新的C++源文件，比如叫my_first_server.cpp。我们需要包含核心的头文件，并实现main函数。
#include "hv/HttpServer.h" int main() { // 1. 创建路由服务，这是处理HTTP请求的核心 HttpService router; // 2. 注册一个最简单的路由：GET /ping router.GET("/ping", [](HttpRequest* req, HttpResponse* resp) { resp->String("pong"); return 200; // HTTP状态码 200 OK }); // 3. 配置并启动服务器 http_server_t server; server.port = 8080; // 监听8080端口 server.service = &router; // 关联我们的路由 // 4. 运行服务器（阻塞当前线程） http_server_run(&server); return 0; }代码是不是简单得有点出乎意料？我来拆解一下：
HttpService对象router是我们的请求路由器，所有URL路径到处理函数的映射都在这里定义。- 我们通过
router.GET注册了一个处理函数。当用户用浏览器或curl访问http://你的IP:8080/ping时，这个Lambda函数就会被调用。它接收请求对象req和响应对象resp，我们调用resp->String("pong")设置响应体为文本“pong”，然后返回状态码200。 - 我们配置了一个
http_server_t结构体，指定服务端口和路由。 http_server_run(&server)是启动服务的函数，它会进入事件循环，持续监听端口上的连接。
编译这个程序（假设你在libhv源码目录下）：
g++ -std=c++11 -I. my_first_server.cpp -o my_first_server -lhv -lpthread然后运行它：
./my_first_server现在，打开另一个终端，用curl测试一下：
curl -v http://127.0.0.1:8080/ping你应该会看到类似下面的输出，说明你的服务已经成功运行并响应了！
> GET /ping HTTP/1.1 > Host: 127.0.0.1:8080 ... < HTTP/1.1 200 OK < Content-Type: text/plain ... pong一个重要的细节：关于线程模型上面代码中，http_server_run(&server)会阻塞主线程。这意味着你的程序会一直停在这里处理网络请求，直到你中断它（比如按Ctrl+C）。这是一种简单的模式，适合大部分场景。
但有些时候，你可能希望服务器在后台运行，主线程还能做别的事情。libhv提供了非阻塞模式：http_server_run(&server, 0)。这个调用会立即返回，服务器在内部创建的线程中运行。但是，这里有个“坑”我踩过：如果你用了非阻塞模式，那么router和server这两个对象必须是全局生命周期（比如全局变量、静态变量或堆上分配），不能是main函数里的局部变量。因为主函数退出时局部变量会被销毁，而后台线程还在使用它们，会导致程序崩溃。所以，对于新手，我强烈建议先用阻塞模式，更简单安全。
3. 核心功能实战：路由、静态文件与API
一个只会说“pong”的服务显然不够用。一个实用的后端服务，通常要处理静态文件（比如前端页面）、定义复杂的RESTful API，甚至还能做请求转发。下面我就把这些核心功能一一实现给你看。
3.1 托管静态文件：打造一个简易文件服务器
很多时候，我们的服务需要提供一些前端HTML、JS、CSS文件，或者让用户下载一些资源。libhv一行代码就能搞定。
// 在刚才的router定义后添加 // 将根路径 "/" 映射到本地 `./public` 目录 router.Static("/", "./public");这行代码的意思是：当访问路径以/开头时（比如/index.html,/js/app.js），libhv会自动去./public目录下寻找对应的文件并返回。如果访问/本身，它会尝试返回./public/index.html。
你需要提前创建好public目录，并在里面放点东西，比如一个index.html：
<!DOCTYPE html> <html> <head><title>My Libhv Server</title></head> <body><h1>Hello from libhv!</h1></body> </html>重启服务后，用浏览器访问http://127.0.0.1:8080/，就能看到这个页面了。这对于部署一个前后端分离项目的前端包，或者做一个简单的内部文档站点，非常方便。
3.2 构建RESTful API：处理JSON和URL参数
现在我们来点动态的。假设我们要为用户管理系统创建几个API。
获取用户信息（带路径参数）：
// GET /user/123 router.GET("/user/{id}", [](const HttpContextPtr& ctx) { // 使用新的HttpContext接口，更简洁 hv::Json resp; resp["user_id"] = ctx->param("id"); // 获取路径参数 {id} resp["name"] = "Alice"; resp["status"] = "active"; return ctx->send(resp.dump(2)); // 发送格式化的JSON });这里用了{id}这种占位符来匹配路径，这是RESTful API的常见写法。ctx->param("id")就能取出URL中的实际值，比如对于/user/123，取出的就是"123"。
处理查询参数和JSON请求体：
// GET /search?keyword=libhv&page=1 router.GET("/search", [](const HttpContextPtr& ctx) { auto& query = ctx->params(); // 获取所有查询参数 std::string keyword = ctx->param("keyword"); int page = ctx->get<int>("page", 1); // 带默认值的获取 hv::Json result; result["keyword"] = keyword; result["page"] = page; result["results"] = hv::Json::array(); // ... 这里可以添加查询逻辑 return ctx->send(result); }); // POST /api/login router.POST("/api/login", [](const HttpContextPtr& ctx) { // 自动解析 application/json 请求体 const hv::Json& req_json = ctx->json(); std::string username = req_json["username"]; std::string password = req_json["password"]; hv::Json resp_json; if (username == "admin" && password == "123456") { resp_json["code"] = 0; resp_json["message"] = "登录成功"; resp_json["token"] = "fake_jwt_token_here"; } else { resp_json["code"] = 1; resp_json["message"] = "用户名或密码错误"; } ctx->setContentType(APPLICATION_JSON); return ctx->send(resp_json.dump()); });HttpContext这个新接口用起来非常顺手。ctx->json()直接拿到了解析好的JSON对象，ctx->get<T>(“key”, default)能智能地根据类型获取查询参数或表单数据，省去了很多手动解析的麻烦。
3.3 实现请求代理与转发
有时候，我们的服务需要作为中间层，将某些请求转发到另一个后端服务，比如做请求聚合、鉴权或调试。libhv内置了简单的代理功能。
// 将所有以 /proxy/ 开头的请求，转发到 httpbin.org router.Proxy("/proxy/", "http://httpbin.org/");启动服务后，当你访问http://127.0.0.1:8080/proxy/get，libhv会帮你把请求转发到http://httpbin.org/get，并将响应原样返回给你。这在开发阶段模拟后端接口，或者构建一个网关时非常有用。
3.4 处理文件上传
文件上传是Web服务中的常见需求。libhv处理multipart/form-data格式的上传也很简单。
#include "hv/MultiPart.h" // 如果需要处理文件 router.POST("/upload", [](const HttpContextPtr& ctx) { if (ctx->is(MULTIPART_FORM_DATA)) { const hv::MultiPart& parts = ctx->form(); for (auto& part : parts) { if (part.filename.empty()) { // 这是普通的表单字段 std::cout << "Field: " << part.name << " = " << part.content << std::endl; } else { // 这是上传的文件 std::cout << "File: " << part.filename << ", size: " << part.content.size() << std::endl; // 你可以将 part.content 保存到磁盘 std::ofstream fout("./uploads/" + part.filename, std::ios::binary); fout.write(part.content.data(), part.content.size()); } } return ctx->sendString("Upload success!"); } return 400; // Bad Request });这段代码演示了如何接收上传的文件和字段。在实际项目中，你还需要考虑文件大小限制、保存路径的安全性、文件名防冲突等问题。
4. 深入性能与高级配置
服务跑起来之后，我们肯定会关心它的性能怎么样，能扛住多少压力，以及如何根据实际场景进行调优。libhv在这方面提供了不少灵活的配置选项。
4.1 同步 vs. 异步：如何选择请求处理模式？
这是libhv设计上一个非常关键的点，它提供了三种处理函数（handler）签名，对应不同的处理模式。选对了模式，对性能影响很大。
同步Handler (http_sync_handler)： 这是最直接的模式，就像我们最开始写
/ping那样。处理函数在I/O线程中同步执行，必须立刻返回响应。router.GET("/fast", [](HttpRequest* req, HttpResponse* resp) { // 快速处理一些内存计算或简单查询 resp->Json({{"status", "ok"}}); return 200; });适用场景：处理逻辑非常快，比如读缓存、简单的数据校验。注意：如果在这个函数里执行了耗时的操作（比如访问慢速的数据库、调用外部API），会阻塞当前I/O线程，导致它无法处理其他连接，严重影响并发能力。
异步Handler (http_async_handler)： 处理函数会立刻被投递到一个全局的线程池中执行，I/O线程不会被阻塞，可以立刻去处理下一个请求。
router.POST("/slow-task", [](const HttpRequestPtr& req, const HttpResponseWriterPtr& writer) { // 将耗时操作放到另一个线程 hv::async([req, writer]() { std::this_thread::sleep_for(std::chrono::seconds(2)); // 模拟耗时操作 hv::Json result; result["task_id"] = 123; result["status"] = "completed"; writer->Begin(); writer->WriteStatus(HTTP_STATUS_OK); writer->WriteHeader("Content-Type", "application/json"); writer->WriteBody(result.dump()); writer->End(); }); });适用场景：请求处理需要较长时间（如超过100毫秒），例如图像处理、复杂报表生成、调用链较长的外部服务。
上下文Handler (http_ctx_handler) - 推荐使用： 这是新版本的推荐写法，它统一了前两种模式。你在函数里可以自己决定是同步处理还是异步处理。
router.GET("/flexible", [](const HttpContextPtr& ctx) { // 判断是否需要异步处理 if (needAsyncProcess(ctx)) { hv::async([ctx]() { // ... 异步耗时操作 ctx->sendJson({{"msg", "async done"}}); }); return 0; // 返回0表示已接管，后续会异步发送响应 } else { // 快速同步处理 return ctx->sendString("quick response"); } });这种模式最灵活，也是我现在最常用的。
HttpContext对象提供了非常丰富的方法来操作请求和响应，代码写起来很流畅。
我的经验：对于大部分CRUD操作，如果数据库速度够快，用同步Handler配合多工作线程（下面会讲）就够了，代码最简单。一旦某个接口的耗时可能波动很大，或者明确要做一些重计算，果断用异步Handler或者将耗时部分丢到自己的业务线程池里。
4.2 关键配置调优：线程、端口与超时
服务器的性能和行为可以通过http_server_t的成员和HttpService的配置来调整。
http_server_t server; server.port = 8080; server.host = "0.0.0.0"; // 监听所有网络接口 // 性能相关关键配置 server.worker_threads = 4; // 工作线程数，通常设置为CPU核心数 server.max_connections = 10000; // 最大连接数 server.max_request_body_size = 10 * 1024 * 1024; // 最大请求体10MB // 超时设置（单位：秒） server.keepalive_timeout = 75; // Keep-Alive连接超时 server.request_timeout = 30; // 请求读取超时 server.idle_timeout = 180; // 连接空闲超时 // 启用HTTPS (需要证书文件) // server.https_port = 8443; // server.ssl_cert_file = "./server.crt"; // server.ssl_key_file = "./server.key"; http_server_run(&server);- worker_threads：这是最重要的参数之一。它决定了有多少个线程在同时处理请求。如果全是同步Handler，这个数就相当于并发处理请求的“车道”数。我一般设为和CPU逻辑核心数相同或稍多。
- max_connections：限制服务器的并发连接数，防止资源被耗尽。
- 请求体大小：根据业务需要设置，防止恶意的大文件上传攻击。
- 超时设置：合理的超时设置能及时释放僵死连接占用的资源。
keepalive_timeout对于HTTP长连接复用很重要。
4.3 压力测试与性能观测
服务写好了，到底性能如何？我们不能靠猜，得用工具压测一下。wrk是一个现代的高性能HTTP压测工具，用法很简单。
首先安装wrk（以Ubuntu为例）：
sudo apt install wrk然后对我们刚写的服务进行压测，模拟100个并发连接，持续压测10秒：
wrk -c 100 -t 4 -d 10s http://127.0.0.1:8080/ping输出结果大概长这样：
Running 10s test @ http://127.0.0.1:8080/ping 4 threads and 100 connections Thread Stats Avg Stdev Max +/- Stdev Latency 1.20ms 200.15us 15.33ms 90.21% Req/Sec 20.87k 1.68k 23.85k 69.00% 832456 requests in 10.01s, 103.37MB read Requests/sec: 83168.34 Transfer/sec: 10.33MB重点关注Requests/sec (QPS)，也就是每秒处理的请求数。在我的一台普通开发机上，一个简单的“pong”接口，QPS能达到8万以上。这个性能对于绝大多数应用场景都是绰绰有余的。你可以对比测试一下静态文件接口和复杂的数据库查询接口，就能直观看出不同逻辑对性能的影响。
压测时，也可以用top或htop命令观察服务器的CPU和内存占用情况，确保资源使用在正常范围内。
5. 构建一个生产可用的服务：配置、日志与守护进程
到现在为止，我们都在终端里直接运行./my_server。这对于开发调试没问题，但对于一个需要长期运行的生产环境服务，这还不够。我们需要考虑配置化管理、日志记录和进程守护。
5.1 使用配置文件管理参数
把端口、线程数这些参数硬编码在代码里很不灵活。libhv支持从类似INI格式的配置文件中读取配置。
我们可以创建一个my_server.conf配置文件：
[server] port = 8080 host = 0.0.0.0 worker_threads = 4 max_connections = 10000 log_file = my_server.log log_level = INFO然后在代码中这样加载配置：
#include "hv/iniparser.h" int main() { // 加载配置文件 IniParser ini; if (ini.LoadFromFile("my_server.conf") != 0) { fprintf(stderr, "Load config file failed!\n"); return -1; } http_server_t server; // 从配置文件中读取值，并提供默认值 server.port = ini.Get<int>("server.port", 8080); server.host = ini.Get<std::string>("server.host", "0.0.0.0").c_str(); server.worker_threads = ini.Get<int>("server.worker_threads", 4); // ... 后续路由注册和服务启动代码不变 HttpService router; router.GET("/ping", [](HttpRequest* req, HttpResponse* resp) { resp->String("pong"); return 200; }); server.service = &router; // 启动前，可以设置日志级别和输出文件 hlog_set_file(ini.Get<std::string>("server.log_file", "").c_str()); hlog_set_level_by_str(ini.Get<std::string>("server.log_level", "INFO").c_str()); printf("Server starting on http://%s:%d ...\n", server.host, server.port); http_server_run(&server); return 0; }这样，要修改端口或线程数，只需要改配置文件，无需重新编译代码。
5.2 集成日志系统
libhv内置了一个轻量级的日志库，可以直接使用。它支持不同的日志级别（DEBUG, INFO, WARN, ERROR, FATAL）和输出到文件。
在上面的配置加载后，我们已经设置了日志。在代码中，可以这样打日志：
#include "hv/logger.h" router.GET("/api/data", [](const HttpContextPtr& ctx) { std::string client_ip = ctx->ip(); hlogi("Request from %s for path %s", client_ip.c_str(), ctx->path().c_str()); // INFO级别日志 // ... 处理逻辑 if (some_error) { hloge("Failed to process request from %s", client_ip.c_str()); // ERROR级别日志 return ctx->sendString("Internal Error", HTTP_STATUS_INTERNAL_SERVER_ERROR); } hlogd("Processing completed for %s", client_ip.c_str()); // DEBUG级别日志 return ctx->sendJson(some_data); });日志会自动带上时间戳、级别和文件名行号，输出到控制台和/或你指定的日志文件中，非常便于问题排查和运行监控。
5.3 以守护进程方式运行
在Linux生产环境中，我们通常希望服务在后台运行，并且能在系统启动时自动拉起。这就需要以“守护进程”的方式运行。
libhv的示例程序httpd自带-d参数可以以守护进程模式运行。我们自己实现也不复杂，核心是调用daemon(1, 1)函数（在<unistd.h>中），并管理好PID文件。
一个更生产级的做法是使用系统级的进程管理工具，比如systemd。我们可以为服务编写一个systemd service文件（例如/etc/systemd/system/my-server.service）：
[Unit] Description=My High-Performance HTTP Server After=network.target [Service] Type=simple User=nobody Group=nogroup WorkingDirectory=/path/to/your/app ExecStart=/path/to/your/app/my_server -c /path/to/your/app/my_server.conf Restart=always RestartSec=5 StandardOutput=syslog StandardError=syslog SyslogIdentifier=my-http-server [Install] WantedBy=multi-user.target然后通过systemctl start my-server启动，systemctl enable my-server设置开机自启。systemd会帮我们管理进程的生命周期、自动重启、收集日志等，是更可靠的选择。
走到这一步，你已经拥有了一个配置灵活、有日志、能稳定运行在后台的HTTP服务了。libhv就像一套精心打造的工具，它没有过度设计，而是把最常用的网络服务功能以最直接的方式提供给你。从最初几行代码的“pong”服务，到一个功能完备的后端应用，整个过程你会发现，复杂度是随着你的业务需求自然增长的，而不是被框架本身强加的。这种“按需取用”的感觉，正是我在很多项目中选择libhv的原因。
