基于 Boost 的 HTTP 服务器:项目工程化

基于 Boost 的 HTTP 服务器:项目工程化

测试、CI、容器、部署——工程化的目的就是可重复的验证

改动可重复验证、构建可重复验证、部署可复现


140 个测试的体系

分层设计:单元 + 集成

测试分几层?为什么不能只有一个测试文件?

测试分两层,动机各不相同:

层 目标 覆盖 定位
单元 logger / utils / router / config / dynamic_api 模块逻辑 逻辑对错
集成 test_integration 系统行为 端到端正确

单元测试:编译期直接链接模块源码,不经过网络——
utils 的 Range 解析、ETag 弱比较、router 的精确/前缀匹配、
config 的三级优先级、dynamic_api 的 Allow 头构造,均可单测断言。
优点:快、准、可隔离——失败即定位到模块

集成测试:真实进程端到端——真实网络栈、真实线程模型、真实报文读写。
“用客户端的眼睛验证服务器”

CMake 组织与自动化

1
2
3
4
5
6
7
8
9
# test/CMakeLists.txt
add_executable(test_integration test_integration.cpp)
target_compile_definitions(test_integration PRIVATE
SERVER_BINARY="${CMAKE_BINARY_DIR}/src/http_server"
DOC_ROOT="${PROJECT_SOURCE_DIR}/app"
)
...
include(GoogleTest)
gtest_discover_tests(test_integration)
  • gtest_discover_tests 自动发现用例并注册到 ctest
  • SERVER_BINARY / DOC_ROOT 编译定义注入——测试不硬编码路径,跨环境可用
  • project_warnings / project_defs 与主程序共享编译纪律

集成测试:fork 真实服务器进程

测试怎么启动服务器?——不能进程内调用,要 fork 真实进程

SetUpTestSuite 中 fork + execl 拉起真实服务器:

1
2
3
4
5
6
7
8
9
10
11
12
// test/test_integration.cpp
server_pid_ = fork();
if (server_pid_ == 0) {
execl(bin_path.c_str(), bin_path.c_str(),
"--port", port_str.c_str(), // TEST_PORT = 19876
"--doc_root", doc_root_str.c_str(),
"--threads", "2",
"--timeout_seconds", "10",
"--cache_ttl_seconds", "1",
static_cast<char*>(nullptr));
_exit(127);
}

三个关键设计:

  • 就绪探测:fork 是异步的,服务器监听就绪前无法连接——
    try_connect 轮询(50 次 * 100ms)等待就绪,避免竞态
  • 测试专用配置:独立端口 19876、TTL 1s——测试不被默认配置绑死,
    也能覆盖”缓存过期”这类时序场景
  • 收尾即验证:TearDownTestSuite 发 SIGTERM——服务器走优雅关闭路径
    退出(未正常退出则兜底 SIGKILL + waitpid)。收尾本身就在验证优雅关闭

为什么 fork 而不是进程内调用:进程内调用会共享地址空间——
测试与服务器同进程,无法覆盖并发、套接字、解析器在真实线程模型下的行为。
fork 真实进程,测试即是独立客户端

测试即文档:304 条件请求、206 Range、gzip 协商、405/OPTIONS、
HEAD 无 body——协议篇讲的每个语义,集成测试里都有用例落点


工程细节

路径穿越防护:双重校验

请求 GET /../../etc/passwd 会发生什么?

第一重:轻量检查(utils.cpp)

1
2
3
4
5
6
7
8
9
10
11
// src/utils.cpp
is_safe_path(beast::string_view path)
{
if(path.empty() ||
path[0] != '/' ||
path.find("..") != beast::string_view::npos)
{
return false;
}
return true;
}

非空、/ 开头、不含 ..——零系统调用,挡住绝大部分恶意输入。
该检查与路径解析缓存协同:恶意请求在缓存命中路径即被拒绝

第二重:weakly_canonical 规范化后的保障(utils.cpp)

1
2
// src/utils.cpp
normalized_full_path = fs::weakly_canonical(full_path);

符号链接、/a/./b 这类路径别名在规范化后现形——
校验规范化结果仍在 doc_root 内,语义级绕过被拦截

为什么双重:轻量检查挡 99% 恶意输入(快速路径、零开销),保证了速度与正确性

CI 流水线

GitHub Actions,双构建矩阵:

配置 内容
触发 push / PR main + 手动 workflow_dispatch
产物 Debug / Release * g++,fail-fast: false
环境 ubuntu-24.04

设计要点:

  • fail-fast: false:两种构建配置都必须出结果——Debug 挂掉不影响 Release 结论
  • GTest 源码编译安装:Ubuntu 的 libgtest-dev 仅含源码,需先 cmake 构建安装,
    find_package(GTest CONFIG) 才能找到
  • ccache 缓存:按 build_type + sha 作 key,命中跳过重编译
  • 防 OOM:CMAKE_BUILD_PARALLEL_LEVEL=2——Actions 环境内存有限,
    并行编译数不设限会内存耗尽
  • ctest 自动发现:gtest_discover_tests 注册的用例一键启动

Docker 多阶段构建

1
2
3
4
5
6
7
8
9
10
11
12
13
# 构建阶段:编译依赖 + Release 构建
FROM ubuntu:24.04 AS builder
...
RUN cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
&& cmake --build . --parallel $(nproc)

# 运行阶段:仅运行时库
FROM ubuntu:24.04
...
COPY --from=builder /src/build/src/http_server /usr/local/bin/http_server
RUN useradd -m -s /bin/bash http_server_user \
&& chown -R http_server_user:http_server_user /srv
USER http_server_user
  • 镜像约 99MB(运行阶段只装运行时库,编译工具不进镜像)
  • 非 root 用户运行——容器逃逸风险收窄
  • APT_MIRROR 构建参数——国内网络可切清华源,绕过不稳定代理

公网验证:协议与网络环境问题

本地 curl 正常,公网验证暴露的是环境问题

用 cloudflared 临时隧道将本机容器暴露为公网 HTTPS URL,
实测(移动宽带 + IPv4 edge):根路径 200、404 透传、连续 10 次全 200、100 并发全 200

两个排查经验:

  • 530(边缘连不上隧道):运营商拦截 cloudflared 的 7844 端口/IPv6——
    加 --edge-ip-version 4 --protocol http2 强制 IPv4 + TCP 443 绕过
  • 502(隧道通但够不到服务):origin 写 localhost 被解析成 ::1,
    容器只监听 IPv4——显式写 http://127.0.0.1:8080

这两个问题都是协议/网络环境问题,不是服务器代码问题——
但只有真实公网验证才会暴露

SELinux 平台适配

开发平台 Fedora 默认 SELinux enforcing,容器运行需正确的容器标签适配


小结

工程化的闭环:改动 -> 140 测试 -> 双配置矩阵 -> 容器镜像 -> 公网实测

每一环都是可重复的验证:测试可重复(ctest)、构建可重复(CI workflow)、
部署可复现(多阶段镜像 + 实测记录)。
工程化的价值不仅仅在于工具本身,而在于任何一次改动都能走完这条链,结论不依赖”当时的手感”,
而是一套可测试,能复现的项目流程


END