C++ http-server源码拆解：Reactor与HTTP/1.1解析-育师

简介：一份用C++实现的异步HTTP服务器库源码，基于epoll事件循环与C++20协程构建，面向已掌握C++基础、希望深入理解高并发网络编程与协程调度的开发者。包内共50个文件，其中18个h头文件与2个cpp源文件构成服务端核心，14个js脚本配合html、css与ico图标组成前端便笺应用界面，另有txt说明、json配置、md文档及yml工作流配置，压缩包约56KB，体量轻巧却结构完整。资源附带一个便笺共享示例应用，涵盖路由注册、JSON请求体校验、静态资源托管与前后端联调等环节，可直观看到协程如何简化传统异步回调流程。目前已有198人学习下载，适合想从零梳理HTTP服务端骨架、借鉴路由与参数校验设计，或为小型项目寻找轻量服务端方案的读者参考。

1. 一份 C++ 的 http-server 源码包：它替你省掉的是「网络层从零长出来」这一段

解压一个只标着 http-server 的 C++ 源码包，多数人的操作路径都一样：先翻目录找 main，再 cmake 一下，然后 curl 上去收到一个 400，或者干脆连接被重置。这类包的定位需要先明确：它适合把「一个 HTTP 服务怎么从 socket 一层层长出来」完整地展现给你看——epoll 怎么等事件、连接怎么被线程池接管、请求头怎么被状态机逐个解析、静态文件怎么不经过用户态直接发出去。适合两类人：想从业务 CRUD 转到网络编程、需要一个能跑能改能打断点的底座的 C++ 开发者；以及要讲清楚 Reactor 模型却缺一份可运行参考代码的授课者。它解决的主要问题是「服务器内部长什么样」，功能上「有没有服务器」倒在其次。

2. 先认骨架再读代码：Reactor 事件循环与线程模型的文件级定位

拿到网络库的源码，最容易出现的问题是从main.cpp第一行开始向下顺序阅读。读到第三百行发现自己在看一个 Buffer 的扩容逻辑，前面的连接建立流程已经忘了。这类工程的结构高度雷同，正确的读法是先画出一张「谁调用谁」的图，再按调用链顺序看，而不是按文件顺序看。

2.1 目录结构与模块边界：先分类再读代码

教学和中小型生产用的 C++ http-server，目录基本会分成三部分：net/放事件循环、Poller、Channel、Acceptor、Connection；http/放解析器、响应封装、路由和静态文件处理；base/放 Buffer、线程、互斥量、日志、时间戳这些与网络无关的基础件。少数会再拆一个http/static/出来专管 MIME 表和文件发送。

模块	职责	建议阅读顺序
`net/EventLoop`	事件循环主体，持有 epoll fd 和唤醒 fd	3
`net/EpollPoller`	封装 epoll_ctl 的增删改，事件数组分发	4
`net/Channel`	fd 与回调的绑定，负责注册和注销关注事件	5
`net/Acceptor`	listen fd 的封装，处理新连接	2
`net/Connection`	一条 TCP 连接的生命周期与缓冲	6
`http/HttpParser`	请求行、头部、请求体的状态机	7
`http/HttpResponse`	状态码、头部、body、文件发送	8
`base/Buffer`	读写指针 + 预留区 + readv 读入	1
`base/Thread`/`ThreadPool`	线程创建与任务队列	9

先看Buffer是有必要的。后面每一个handleRead()都在跟它打交道，如果不清楚readerIndex、writerIndex、prependable这三段内存的语义，读解析器时会一直怀疑「这个数据到底在哪」。我一般会先在纸上画一条 8 字节的 prependable、一段可读区、一段可写区，然后跟着retrieve()和append()走一遍，再回头去看网络层。

模块边界上有一个地方要特别确认：Channel是否持有 fd 的所有权。有些实现里Channel只是 fd 的观察者，关闭由Connection负责；有些实现里Channel的析构会 close fd。这两种设计的差别在排查 fd 泄漏时是决定性的，读代码时务必在头文件里确认清楚。

2.2 epoll 的 ET 与 LT：事件循环主干和三个必查点

事件循环主干通常长这样，一个 loop 一个 epoll fd，事件数组容量固定，回调只做分派不做业务：

// EventLoop 主干：等待事件 -> 分派回调 -> 执行跨线程任务 int epfd = ::epoll_create1(EPOLL_CLOEXEC); epoll_event evs[1024]; while (!quit_) { int n = ::epoll_wait(epfd, evs, 1024, timeout_ms_); if (n < 0) { if (errno == EINTR) continue; // 被信号打断属于正常现象，重来即可 break; // 其它错误说明 epoll fd 已不可用 } for (int i = 0; i < n; ++i) { auto* ch = static_cast<Channel*>(evs[i].data.ptr); uint32_t re = evs[i].events; if (re & (EPOLLHUP | EPOLLERR)) { ch->handleError(); continue; } // 先处理错误 if (re & EPOLLRDHUP) { ch->handleClose(); continue; } // 对端半关闭 if (re & EPOLLIN) ch->handleRead(); // 可读：可能是新连接也可能是数据 if (re & EPOLLOUT) ch->handleWrite(); // 可写：通常是发缓冲区满了在等 } doPendingFunctors(); // 其它线程投递过来的任务，必须在本 loop 线程执行 }

EPOLL_CLOEXEC不能省，否则 fork 出去的进程会继承这个 fd。timeout_ms_一般取 1000 或者干脆用-1，但如果工程里有时轮或定时器需要处理，就必须给一个有限的超时值，否则定时任务永远不会被触发。EPOLLRDHUP需要注册时显式加上，不然客户端正常关闭你只能等到下一次read()返回 0 才知道，中间的窗口期内这条连接仍算活跃连接。

水平触发（LT）和边缘触发（ET）的选择是读这类代码时第一个分水岭。LT 的语义是只要缓冲区里还有数据，epoll_wait就会一直返回可读，写起来省心，但一个慢客户端可能让同一个 fd 反复出现在事件数组里。ET 只在状态变化时通知一次，性能好，代价是必须一次把数据读干净，也就是循环read()直到返回-1且errno == EAGAIN。很多实现默认走 ET，你在handleRead()里如果只看到一次read()调用而没有 while 循环，基本可以断定这是一个隐藏的 bug 点。

提示：判断 ET 还是 LT，最快的办法是在注册事件的那一行看有没有EPOLLET，别去猜。

2.3 线程池与 one loop per thread：连接该交给谁

线程模型上，这类工程绝大多数用「主从 Reactor + one loop per thread」：主线程只跑一个 loop 负责accept，accept 到的 fd 按轮询分给若干个 sub loop，每个 sub loop 独占一个线程，连接上所有读写和业务回调都在它所属的 loop 线程里执行。这样做的好处是单条连接天然没有并发问题，跨连接共享的状态才需要加锁。

// 主线程：只 accept，不处理业务；连接按轮询交给 sub loop EventLoop* pickLoop() { static std::atomic<size_t> next{0}; return subLoops_[next.fetch_add(1) % subLoops_.size()]; } void onNewConnection(int connfd) { setNonBlocking(connfd); // 必须在跨线程传递之前设置，否则其它线程读会阻塞 setTcpNoDelay(connfd); // 关闭 Nagle，小响应包场景下延迟差别很明显 EventLoop* loop = pickLoop(); loop->runInLoop([loop, connfd] { auto conn = std::make_shared<Connection>(loop, connfd); conn->start(); // 内部注册 EPOLLIN | EPOLLET | EPOLLRDHUP }); }

setNonBlocking那一行是血泪经验换来的顺序。如果先投递任务、再在主线程里设置非阻塞，中间这段窗口里 sub loop 可能已经开始读一个阻塞 fd，最坏情况是整个 loop 线程卡死在read()上，表现为「服务还在但所有连接都不响应」。setTcpNoDelay在小包场景下能把响应延迟从毫秒级压下来，压测时p99的差别肉眼可见。

runInLoop的实现要点是：如果当前线程就是 loop 所属线程，直接执行；否则把任务塞进队列，然后往一个 eventfd 里写 8 个字节，让epoll_wait立刻返回去执行队列里的任务。eventfd 的写端要设成非阻塞，队列满了丢弃只会导致延迟，不会导致死锁。读 eventfd 时务必把 8 字节读出来，不读掉的话 ET 模式下不会再有下一次通知——这类问题在压测里表现为「跑一会儿就不动了」，但单条 curl 完全正常。

线程数怎么定？经验值是min(CPU 核数, 8)，IO 密集型可以再加一点，纯静态文件服务加线程收益不大，瓶颈在网卡和 sendfile。如果配置里把线程数开到 32 而机器只有 4 核，上下文切换的损耗会直接反映在wrk的 QPS 上。

3. 把工程跑起来：CMake 构建、配置参数与三条冒烟命令

读懂了骨架，下一步是让它真的跑起来。这一步卡住的人往往不是不懂 C++，而是被依赖和编译选项绊住：-pthread忘了加、C++ 标准版本和代码里的std::string_view对不上、Debug 构建下性能差十倍误以为代码有问题。花十分钟把构建脚本理清楚，比后面拿 gdb 定位更划算。

3.1 CMake 拉起工程：编译选项与标准版本

这类工程的构建脚本一般很朴素，没有第三方依赖，只需要 pthread。下面这份是我通常在原包基础上整理出来的形态：

cmake_minimum_required(VERSION 3.10) project(http_server CXX) set(CMAKE_CXX_STANDARD 14) # 代码里若用了 string_view / optional 需改 17 set(CMAKE_CXX_STANDARD_REQUIRED ON) if (NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) # 不指定时默认 Release，避免误测出低性能 endif() add_compile_options(-Wall -Wextra -O2 -g -pthread) # -g 保留符号，方便 perf 和 gdb add_executable(http_server src/main.cpp src/net/EventLoop.cpp src/net/EpollPoller.cpp src/http/HttpParser.cpp src/http/HttpResponse.cpp ) target_include_directories(http_server PRIVATE ${CMAKE_SOURCE_DIR}/include)

-O2 -g同时开是刻意的：性能测试必须用优化后的二进制，但调试符号要留着，否则perf top出来的全是一堆地址，等于让性能分析过程无法进行。CMAKE_BUILD_TYPE不写默认值是个常见疏漏，很多人cmake ..之后直接make，拿到的是无优化的二进制，测出来 QPS 只有真实值的三分之一，然后开始怀疑代码里的锁写得不对。

编译期报undefined reference to pthread_create就是-pthread没加到位，注意要加在add_compile_options或target_link_libraries，而不是只写在某个源文件的编译命令里。如果源文件列表里的路径和实际目录对不上，直接用file(GLOB_RECURSE SRCS src/*.cpp)先跑通，再回头把显式列表补上——GLOB 的缺点是新增文件不会触发重新配置，长期维护会出问题。

3.2 启动参数与配置文件：六个真正影响行为的字段

配置文件通常是简化的key = value格式，逐行解析，#开头为注释。参数看着多，真正会改变运行行为的其实就六个：

字段	典型值	影响	调错的后果
`port`	8080	listen 端口	被占用时直接退出，注意看日志
`threads`	4	sub loop 数量	超过核数太多会拉低 QPS
`root`	./www	静态文件根目录	相对路径依赖启动目录，容易 404
`keepalive_timeout`	60	空闲连接回收秒数	设 0 表示不回收，FD 会持续涨
`max_connections`	10000	连接数上限保护	需小于`ulimit -n`
`log_level`	info	日志详细程度	压测时开 debug 会拖慢一倍

解析代码本身没什么技术含量，但有一个细节值得看：root用相对路径时，服务从哪个目录启动决定了它指向哪里。我一般会在启动时把root转成绝对路径打到日志第一行，后面排查 404 时一眼就能看出是不是路径问题。

// 启动时把关键配置打出来，省掉后面一半的猜测 std::string root = cfg.get("root", "./www"); char resolved[PATH_MAX]; if (::realpath(root.c_str(), resolved)) root = resolved; // 转绝对路径 LOG_INFO("listen=%s root=%s threads=%d", cfg.get("port").c_str(), root.c_str(), threads);

realpath在目录不存在时返回空，此时要保留原值并打一条 warning，而不是让root变成空字符串——空字符串拼接出来的路径是/index.html，表现是「访问什么都是 404 且看不出原因」。

3.3 用 curl 和 wrk 做冒烟验证

构建完先别急着上浏览器，三条命令足够判断这个二进制是不是健康的：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build -j"$(nproc)" ./build/http_server -c conf/server.conf # 前台启动，先别 daemon curl -v http://127.0.0.1:8080/index.html # 1. 正常 GET，看状态行和响应头 curl -I http://127.0.0.1:8080/index.html # 2. HEAD，验证不返回 body 但头正确 curl -v --http1.1 -H "Connection: keep-alive" \ http://127.0.0.1:8080/ -o /dev/null # 3. 长连接，看是否一次 TCP 复用多条请求

第一条的-v输出里要确认三件事：状态行是HTTP/1.1 200 OK而不是HTTP/1.0；Content-Length与实际文件大小一致；Content-Type是text/html而不是application/octet-stream。第三条用--http1.1加 keep-alive，在-v里连发两个 URL 可以看到Re-using existing connection的字样，没有这句说明服务端在响应头里回了Connection: close，长连接没生效。

压测放在冒烟之后：

wrk -t4 -c200 -d10s --latency http://127.0.0.1:8080/index.html

关注三个数：Requests/sec是吞吐，Latency的 p99 是尾部延迟，Socket errors必须是 0。200 并发下如果出现connect errors，先去看ulimit -n和max_connections，别急着改代码。压测期间用top -H -p <pid>看线程分布，如果只有一个线程在 100% 而其它线程空转，说明 accept 之后的分派没生效，连接全堆在主线程上了。

4. HTTP/1.1 解析这块硬骨头：状态机、keep-alive 与静态文件零拷贝

网络层跑通之后，真正的复杂度全在http/目录里。HTTP/1.1 的坑集中在三处：请求可能分多次到达（半个请求行、半个头部），一个 TCP 包里可能有多个请求（pipelining），以及 body 的长度判定有两套规则（Content-Length和chunked）。任何一处处理不好，都会表现成「偶尔 400」或者「偶尔卡死」，而且极难复现。

4.1 请求行与头部的增量解析状态机

正确的做法是状态机而不是一次性strstr("\r\n")。每次handleRead()把数据 append 进 Buffer，然后让解析器从当前状态继续吃，吃到数据不够就停下等下一次：

enum class State { RequestLine, Headers, Body, ChunkSize, ChunkData, Done, Error }; // 返回 false 表示数据不够，需要等下一次可读事件；抛错则直接回 400 bool HttpParser::parse(Buffer* buf) { while (state_ != State::Done) { if (state_ == State::RequestLine || state_ == State::Headers) { const char* crlf = buf->findCRLF(); // 在可读区里找 \r\n if (!crlf) return false; // 半个头部，等下一包 std::string_view line(buf->peek(), crlf - buf->peek()); if (state_ == State::RequestLine) parseRequestLine(line); // METHOD SP URI SP VERSION else if (line.empty()) state_ = State::Body; // 空行表示头部结束 else parseHeaderLine(line); // key: value，注意 value 前的空格要跳过 buf->retrieve(line.size() + 2); // 连同 \r\n 一起消费掉 } else { if (bodyRemain_ > buf->readableBytes()) return false; // body 没到齐 body_.append(buf->peek(), bodyRemain_); buf->retrieve(bodyRemain_); state_ = State::Done; } } return true; }

findCRLF只应该在可读区里找，不能越过writerIndex去扫内存——那样会读到上一轮残留的旧数据，表现是解析出莫名其妙的头部。头部行解析时 value 前面的空格要跳过，但 value 内部的空格必须保留，User-Agent: a b被截成a这种问题在浏览器上不一定暴露，在带自定义头的接口调用上就会炸。

状态机还有一个必须处理的边界：请求行/头部总长度要有上限。常见值是 8KB，超过直接回431并关连接。没有这个上限，一个构造出来的超长头部就能把内存吃掉，这类问题在公网暴露几分钟内就会被人扫到。

4.2 keep-alive、Content-Length 与 chunked 的三条判定规则

一条连接处理完一个请求之后要不要关，取决于三个条件同时成立：客户端没说Connection: close、服务端没主动要求关、并且请求的 body 已经被完整消费。第三点最容易被忽略——如果解析器只读了头部就回响应，剩下的 body 字节还留在 Buffer 里，下一条请求解析时就会把这些 body 当成请求行，直接 400。

Content-Length和chunked是互斥的。有Transfer-Encoding: chunked时忽略Content-Length，按「读长度行 → 读数据 → 读 CRLF」循环，直到读到长度为 0 的块。两个头同时出现属于请求走私的经典场景，稳妥做法是直接回 400 并断开，别试图兼容。

// 决定这条连接是否复用：三个条件缺一不可 bool keepAlive = req.wantsKeepAlive() // HTTP/1.1 默认 true，除非显式 close && !resp.forceClose() // 出错或业务要求关闭 && parser.bodyConsumed(); // body 必须读完，否则污染下一条请求 resp.setHeader("Connection", keepAlive ? "keep-alive" : "close"); if (!keepAlive) conn->shutdownAfterWrite(); // 注意：发完再关，别发一半就 close

shutdownAfterWrite这个语义很重要。很多实现直接在响应回调末尾close(fd)，如果响应体还在内核缓冲区里没发完，客户端会收到RST而不是完整响应，浏览器上的表现是「下载到一半失败」。正确做法是标记一个closing_状态，等EPOLLOUT把剩余数据写完、或者写返回 0 之后再close。

4.3 静态文件发送：sendfile 的正确用法

小文件直接read到用户态再write无所谓，几百 KB 以上的静态资源用sendfile能省掉一次拷贝，差别在压测里非常明显。但它有两个必须处理好的点：偏移量要跨多次调用递增，以及发送缓冲区满时不能丢数据。

// 静态文件发送：off 用成员变量保存，跨 EPOLLOUT 继续推进 while (remain_ > 0) { ssize_t n = ::sendfile(connfd_, filefd_, &off_, remain_); if (n > 0) { remain_ -= n; continue; } // 部分写，继续 if (n < 0 && (errno == EAGAIN || errno == EWOULDBLOCK)) { enableWriting(); // 内核缓冲满，等可写 return; } if (n < 0 && errno == EINTR) continue; // 被信号打断，重试 handleError(); // 其它错误，关连接 return; } closeFile(); // 发完记得关文件 fd

off_必须是成员变量。写成局部变量off_t off = 0的版本在本地测试永远正常，一上压测就出现「文件内容错乱」——因为每次EPOLLOUT回来都从文件头重新发，客户端拼出来的文件是乱的。remain_同理，不递减会死循环。

还有一个容易踩的点：sendfile要求 socket 是非阻塞的，否则内核缓冲满时会阻塞整个 loop 线程。另外大文件传输期间如果有keepalive_timeout的定时器在跑，要记得续期，不然一个 2GB 的文件传到一半连接被自己的超时机制关掉。MIME 表按扩展名查，查不到给application/octet-stream并带上Content-Disposition: attachment，让浏览器直接下载而不是尝试渲染。

5. 排查现场：五个导致服务故障或变慢的问题

下面这五条是我在拆这类工程时真实撞过的，症状、根因、改法都写清楚，遇到了可以对照着查。

5.1 压测几秒后进程 CPU 100% 但 QPS 掉到个位数

现象：wrk一开始能跑出几万 QPS，两三秒后 QPS 断崖式下跌，top显示某几个线程满核，strace追上去全是epoll_wait立刻返回。原因：ET 模式下handleRead()只read()了一次，缓冲区里还有数据没读干净，ET 不会再次通知，但EPOLLIN这个状态一直是「就绪」的，导致循环空转。解决：handleRead()里改成循环读，直到read()返回-1且errno == EAGAIN才退出；accept同理，主线程也要循环 accept 到EAGAIN。

5.2 单条 curl 正常，浏览器打开页面却一直转圈

现象：命令行访问任意 URL 秒回，浏览器访问首页卡住十几秒然后超时。原因：首页会并发发起多条请求，而服务端的accept循环里只 accept 了一个连接就返回了，后面排队的连接在 backlog 里等；在 ET 模式下这个问题的表现尤其明显，因为 listen fd 的可读事件只通知一次。解决：Acceptor::handleRead()里用while ((connfd = accept(...)) > 0)循环取，取到EAGAIN为止；同时检查listen(fd, backlog)的 backlog 是否给得太小，1024 是个合理的起点。

5.3 传大文件传到一半连接被重置

现象：几十 MB 的文件下载到 60% 左右失败，curl报connection reset by peer，日志里没有任何错误。原因：sendfile遇到EAGAIN后直接close(fd)了，因为代码把「没发完」当成了「发完了」；或者remain_算错，发送长度超过实际文件大小。解决：把EAGAIN分支明确区分出来，注册EPOLLOUT后返回，等可写事件继续；同时在文件打开后用fstat拿真实大小，remain_初始值取它而不是Content-Length头里的值。

5.4 跑一晚上内存涨到几个 G

现象：RES内存单调上涨，重启后归零，valgrind跑短时间又看不出泄漏。原因：Connection和Channel互相持有shared_ptr，形成循环引用，连接关闭时谁都不会析构；或者Channel从 epoll 里注销时只做了EPOLL_CTL_DEL却没有从「fd → Channel」的 map 里 erase，map 无限增长。解决：把其中一个方向改成weak_ptr，或者在Connection::close()里显式解绑回调；关闭流程统一走「先epoll_ctl DEL、再从 map erase、最后close(fd)」这个顺序，顺序反了会出现 fd 被复用时旧 Channel 还在收事件的问题。

5.5 压测时出现大量 400，日志里请求行是乱码

现象：低并发完全正常，200 并发下 400 的比例大概百分之几，日志里打出来的请求行像是被截断或拼接过的。原因：多个线程同时往同一个 Buffer 里append，或者解析器没有在读完一条请求后重置状态就处理下一条。另一类常见原因是 keep-alive 下上一条请求的 body 没读完就复用了连接，残留字节被当成新请求的开头。解决：Buffer 只允许所属 loop 线程访问，跨线程投递数据必须拷贝一份再入队；解析完成后调用reset()把状态、body_、bodyRemain_全部归零；在bodyConsumed()为 false 时强制Connection: close。

注意：这五条里有四条在单连接测试下完全不出现，必须用wrk -c200以上才有复现概率，别用 curl 循环当压测。

6. 二次开发与验证：加一条路由，再用压测把改动固定下来

让这个 http-server 从「能跑的 Demo」变成「能用的小服务」，第一步通常是加业务路由。工程里如果有Router，改法很简单：

// 注册一条健康检查路由，注意回调在 loop 线程执行，别在里面做阻塞 IO router_.get("/api/health", [](const Request& req, Response* resp) { resp->setStatus(200); resp->setHeader("Content-Type", "application/json"); resp->setBody(R"({"ok":true})"); }); // POST 需要在解析器里确保 body 读完再进回调，否则拿到的 body_ 是半截 router_.post("/api/echo", [](const Request& req, Response* resp) { resp->setBody(req.body()); // 原样回显，用来验证 body 解析 resp->setHeader("Content-Length", std::to_string(req.body().size())); });

如果没有Router，就在Connection的 onRequest 回调里按req.path()做一次if/else，功能一样，代价是新增接口要改动网络层文件。我倾向于先补一个极简 Router（一张unordered_map<string, handler>加一次前缀匹配），把业务和网络彻底分开，后面加接口就不用碰Connection了。

路由加完，验证不能只看浏览器能不能打开。我一般跑三步：先用curl -X POST -d 'hello'确认 body 完整回显；再用wrk -t4 -c200 -d30s --latency对比改动前后的 QPS 和 p99，波动超过 10% 就要查是不是回调里加了锁或者日志；最后用一个脚本连发 1000 次 keep-alive 请求，检查ss -s里的连接数是否稳定——稳态下连接数应该等于并发数，涨上去就是回收逻辑没生效。

改动	验证点	期望结果
新增 GET 路由	`curl -v`状态行	200，Content-Length 正确
新增 POST 路由	`curl -d`回显	body 完整，无截断
回调里加日志	`wrk`前后 QPS	掉幅 < 10%
改线程数	`top -H`线程分布	各 loop 线程负载接近
改 keepalive_timeout	`ss -s`连接数	稳态等于并发数