FrameworkBenchmarks 中 Lwan 基准测试实现详解:C 处理器与 Lua 脚本双版本解析

原创2026-10-14 14:35:121,968 阅读
文章标签:性能测试测试质量保障后端示例工程Web框架

FrameworkBenchmarks 中 Lwan 基准测试实现详解:C 处理器与 Lua 脚本双版本解析

本技术指南以 TechEmpower Framework Benchmarks 仓库中 frameworks/C/lwan/README.md 为核心,围绕 Lwan 高性能 Web 服务器在基准测试中的完整接入方案展开:C 版全部测试端点(JSON、Plaintext、DB、Query、Cached Queries、Fortunes)与 Lua 版轻量端点如何实现、如何配置路由与数据库连接,以及如何用 wrk 与测试类型脚本验证结果。读完本文,你将掌握在 FrameworkBenchmarks 体系内理解与复现 Lwan 基准测试所需的全部配置参数、源码细节与运行前提。

一、Lwan 基准测试整体结构

本测试基于 Lwan 目录,并同时提供 C 版本与 Lua 版本两套基准实现:

版本 语言 覆盖测试点 核心文件
C 版 C JSON / Plaintext / DB / Query / Cached Queries / Fortunes src/techempower.c、src/database.c、src/json.c
Lua 版 Lua(LuaJIT) JSON / Plaintext techempower.conf、src/json.lua

两份 Dockerfile 分别对应两种形态:lwan.dockerfile 启用 MySQL 后端(USE_MYSQL=1),lwan-lua.dockerfile 则默认走 SQLite 且不预置数据库环境变量。两个版本的测试配置在 benchmark_config.json 与 config.toml 中被声明为 default 与 lua 两组。

二、C 版本:六个基准测试端点的实现

C 版本的全部六个测试端点均由同一个入口程序 src/techempower.c 实现,且使用同一个配置文件 techempower.conf 完成路由注册。

2.1 路由配置:site 与 handler 的绑定

techempower.conf 是整个 Lwan 基准测试的路由骨架。listener *:8080 声明监听所有网卡地址的 8080 端口;site {} 内使用 &handler /path 语法把 C handler 绑定到 URL,其中 & 前缀表示引用可执行模块:

listener *:8080

site {
    # For main TWFB benchmarks
    &plaintext /plaintext
    &json /json
    &db /db
    &queries /queries
    &cached_queries /cached-queries
    &fortunes /fortunes

    # For test harness
    &quit_lwan /quit-lwan
    &plaintext /hello
}

这里有两个细节值得注意:

  • 除六个正式测试端点外,配置中还注册了 /quit-lwan(对应 src/techempower.c 中的 quit_lwan handler,直接调用 exit(0))和 /hello(Plaintext 的别名),用于测试工具链的控制与验收。
  • 每个 &handler 名称都会在源码中找到同名函数,例如 LWAN_HANDLER(plaintext)、LWAN_HANDLER(json)、LWAN_HANDLER(quit_lwan),Lwan 通过宏把 handler 函数注册进模块系统。

2.2 各端点的访问地址与预期响应

按 frameworks/C/lwan/README.md 的 Test URLs 一节,六个端点的访问方式如下:

测试 地址 预期响应
JSON http://localhost:8080/json {"message":"Hello, World!"}
Plaintext http://localhost:8080/plaintext Hello, World!
DB http://localhost:8080/db 单条 World 记录 {"id":N,"randomNumber":M}
Query http://localhost:8080/query?queries= 长度为 1–500 的 World 记录数组
Cached Queries http://localhost:8080/cached-queries?count= 长度为 1–500 的 World 记录数组
Fortunes http://localhost:8080/fortunes HTML 表格,含 12 条固定数据加 1 条附加数据

注意 README 中 URL 写作 /query?queries= 与 /cached-queries?count=,而在配置文件里实际绑定的路径是 /queries 与 /cached-queries。以 benchmark_config.json 为准,正式声明的 URL 为:

"query_url": "/queries?queries=",
"cached_query_url": "/cached-queries?count=",

2.3 JSON 端点:基于描述符的声明式编码

json handler 使用静态字符串 hello_world("Hello, World!")构造响应。关键在于 Lwan 采用了 Zephyr 项目移植来的声明式 JSON 描述符机制(见 src/json.h):

struct hello_world_json {
    const char *message;
};
static const struct json_obj_descr hello_world_json_desc[] = {
    JSON_OBJ_DESCR_PRIM(struct hello_world_json, message, JSON_TOK_STRING),
};

JSON_OBJ_DESCR_PRIM 通过 offsetof 计算字段偏移、用 __alignof__ 记录对齐,让编码器无需反射即可直接读写结构体;json_response_obj() 再调用 json_obj_encode_full() 把数据编码进响应缓冲区并设置 application/json 的 MIME 类型。编码器在 src/json.c 中实现,包含基于 has_zero()/has_value() 位运算技巧的转义检测,以及对描述符中键名的"预拼引号+冒号"优化,减少每次编码时的间接调用(见 src/json.c 中 encode_key() 的注释)。

2.4 Plaintext 端点:零拷贝静态字符串

plaintext handler 是最极端的性能路径,直接用 lwan_strbuf_set_static() 把 hello_world 字符串的静态内存引用赋给响应缓冲区,完全避免复制与堆分配,并设置 text/plain MIME 类型:

LWAN_HANDLER(plaintext)
{
    lwan_strbuf_set_static(response->buffer, hello_world,
                           sizeof(hello_world) - 1);
    response->mime_type = "text/plain";
    return HTTP_OK;
}

2.5 DB 与 Query 端点:随机 World 记录查询

DB 与 Query 共用同一条 SQL 预编译语句(random_number_query),通过 db_prepare_stmt() 准备、db_query() 执行:

static const char random_number_query[] =
    "SELECT randomNumber, id FROM world WHERE id=?";
  • db handler:执行单次查询,随机键为 rand() % 10000,返回单条 JSON 对象。
  • queries handler:解析 queries 参数并做边界裁剪,LWAN_MIN(500, LWAN_MAX(1, parse_long(queries_str, -1))) 保证取值在 1–500 之间;随后循环查询并填充 struct queries_json 数组(最多 500 个元素),再用 json_response_arr() 编码成 JSON 数组。代码注释指出每条响应约 32 字节,因此预先 lwan_strbuf_grow_to(response->buffer, 32 * queries) 以避免构建过程中的重分配与拷贝。

参数边界与测试工具的对应关系

测试工具 toolset/test_types/query/query.py 会依次请求 queries 取值为 2、0、foo、501、空串的情况,并期望:

  • 正常整数值返回等长数组;
  • 超过 500 被截断为 500,低于 1 被提升为 1;
  • 非数值参数在当前轮次仅告警(warn),未来轮次将升级为失败(见 toolset/test_types/verifications.py 中 verify_query_cases() 的注释)。Lwan 的 parse_long() 对非数字返回 -1,再被钳制到 1,恰好满足该规则。

2.6 Cached Queries 端点:缓存条目的协程安全访问

cached_queries handler 将随机键对应的 World 记录缓存在 Lwan 的通用缓存 struct cache 中(创建于 src/techempower.c 的 main(),缓存有效期 3600 秒即 1 小时)。每次请求先 rand() % 10000 生成键,再从缓存取出 db_json_cached 条目并拷贝到结果数组。

为了在协程上下文中安全地取缓存引用,源码自定义了 my_cache_coro_get_and_ref_entry():它刻意不调用 coro_defer(),理由是当缓存元素过多时,coro_defer 数组会发生重分配、把内联存储"降级"到堆上,同时大量间接调用也会拖慢每次请求的处理(见 src/techempower.c 中该函数的详细注释)。该函数最多重试 64 次,遇 EWOULDBLOCK 时先 coro_yield 让出协程、再按重试次数递减地 lwan_request_sleep。

2.7 Fortunes 端点:协程驱动模板渲染

Fortunes 是最复杂的端点,采用 Lwan 模板引擎 + 协程迭代器的组合:

  1. 模板编译:main() 中调用 lwan_tpl_compile_string_full() 编译硬编码的 HTML 模板字符串 fortunes_template_str(含 {{#item}}…{{/item}} 序列块)。
  2. 协程生成器:fortune_list_generator() 以协程函数形式工作——它用 SELECT * FROM Fortune 查询全部数据,逐行 coro_strdup 复制消息、追加到 fortune_array,再补充一条固定文本 "Additional fortune added at request time.",最后按消息字典序 fortune_array_sort 排序,并通过 coro_yield 逐条产出。
  3. 描述符绑定:模板通过 fortune_desc 与 struct Fortune 绑定,其中 TPL_VAR_STR_ESCAPE(item.message) 负责 HTML 转义,TPL_VAR_SEQUENCE 指定序列生成器。

响应 Content-Type 为 text/html; charset=UTF-8,缓冲区预先扩到 1500 字节。

测试侧对 Fortunes 的 HTML 结构有严格比对: toolset/test_types/fortune/fortune_html_parser.py 内置了 valid_fortune 标准串(12 条固定数据 + Additional fortune added at request time.),并忽略 <meta>、<link>、<script>、<thead>、<tbody> 等不影响语义的标签。

三、数据库抽象层:MySQL 与 SQLite 双后端

基准测试的数据库访问由 src/database.c 统一抽象,对外只暴露 struct db(disconnect / prepare 两个函数指针)与 struct db_stmt(bind / step / finalize 三个函数指针),上层业务代码完全不感知后端差异。

3.1 后端的切换逻辑

src/techempower.c 的 main() 通过环境变量 USE_MYSQL 决定连接方式:

  • MySQL 分支:读取 MYSQL_USER、MYSQL_PASS、MYSQL_HOST、MYSQL_DB 四个环境变量,任一缺失即 lwan_status_critical() 终止;调用 db_connect_mysql(),内部使用 mysql_real_connect() 连接并 mysql_set_character_set(con, "utf8")。
  • SQLite 分支(默认):连接 techempower.db,并执行三个 PRAGMA 以逼近 MySQL 的读写性能形态:
static const char *pragmas[] = {"PRAGMA mmap_size=44040192",
                                "PRAGMA journal_mode=OFF",
                                "PRAGMA locking_mode=EXCLUSIVE", NULL};

其中 mmap_size 约 42 MiB 启用内存映射,journal_mode=OFF 关闭 WAL 日志,locking_mode=EXCLUSIVE 锁定单连接独占访问。

3.2 线程本地连接与签名式结果绑定

连接实例以线程本地存储(static __thread struct db *database)缓存在 get_db() 中,每个线程首次访问时才懒连接。语句结果读取采用"签名串"约定:db_stmt_step(stmt, "ii", &random_number, &id) 中,'i' 表示整型列、's' 表示字符串列(字符串还需附带缓冲区长度参数)。MySQL 后端据此动态构建 MYSQL_BIND 数组并 mysql_stmt_bind_result,SQLite 后端则按签名调用 sqlite3_column_int/text。参数绑定同样按 's'/'i' 映射到 MYSQL_TYPE_STRING/MYSQL_TYPE_LONG 或 sqlite3_bind_text/int。

该层对迁移到其他数据库(如 PostgreSQL)非常友好:只需新增一组 bind/step/finalize 实现并接入 struct db 的函数指针表即可,业务 handler 无需改动。

四、Lua 版本:模块化脚本端点

Lua 版本复用同一个 techempower.conf,通过 lua 模块暴露 /lua. 前缀的脚本化路由,并提供两个 handler:

lua /lua. {
    default_type = text/plain
    cache period = 1h
    script='''local json = require "src/json"

            function handle_get_plaintext(req)
                req:set_response("Hello, World!")
                return nil
            end

            function handle_get_json(req)
                req:set_headers({['Content-Type']='application/json'})
                req:set_response(json.encode({message="Hello, World!"}))
                return nil
            end'''
}
  • 访问 http://localhost:8080/lua.plaintext 时,handle_get_plaintext() 直接返回纯文本 Hello, World!;
  • 访问 http://localhost:8080/lua.json 时,handle_get_json() 先设置 JSON Content-Type,再通过 src/json.lua 的 json.encode 输出 {"message":"Hello, World!"}。

default_type = text/plain 声明未显式指定类型的默认 MIME;cache period = 1h 说明脚本与路由结果可缓存 1 小时。Lua JSON 编解码器采用 rxi 的 src/json.lua(版本 0.1.2),支持编码/解码对象、数组、字面量、Unicode 与代理对转义,并内置循环引用与稀疏数组检测。

五、构建与运行环境

5.1 编译参数

Makefile 展示了针对基准的激进编译优化:

CFLAGS = -mtune=native -march=native -O3 -fno-plt -flto -ffat-lto-objects -DNDEBUG \
    -falign-functions=32 -malign-data=abi \
    -include /lwan/build/lwan-build-config.h \
    -I /lwan/src/lib \
    $(shell pkg-config mariadb --cflags) \
    $(shell pkg-config sqlite3 --cflags) \
    $(shell pkg-config luajit --cflags)
  • -march=native -mtune=native:按宿主机 CPU 指令集优化(仅适合测试专用容器,不能跨机移植二进制);
  • -flto -ffat-lto-objects:链接期优化;-fno-plt 减少 PLT 间接跳转;
  • -falign-functions=32、-malign-data=abi 与 -include lwan-build-config.h 对齐 Lwan 的构建配置;
  • 链接时 -Wl,-whole-archive 静态并入 liblwan.a,并链接 mariadb、sqlite3、luajit、pthread、zlib。

5.2 Docker 镜像构建

lwan.dockerfile 以 ubuntu:22.04 为基础,分四步完成构建:

  1. 安装 git pkg-config build-essential cmake zlib1g-dev libsqlite3-dev libmariadb-dev wget libluajit-5.1-dev;
  2. 拉取并编译 mimalloc(-DMI_SECURE=OFF,CFLAGS="-flto -ffat-lto-objects");
  3. 拉取 Lwan 指定版本源码,cmake -DCMAKE_BUILD_TYPE=Release -DUSE_ALTERNATIVE_MALLOC=mimalloc 后构建 lwan-static;
  4. 执行 make clean && make 编译本测试程序,产出 techempower 可执行文件。

运行期环境变量(MySQL 版)如下:

ENV LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
ENV USE_MYSQL=1
ENV MYSQL_USER=benchmarkdbuser
ENV MYSQL_PASS=benchmarkdbpass
ENV MYSQL_DB=hello_world
ENV MYSQL_HOST=tfb-database
ENV LD_PRELOAD=/usr/local/lib/libmimalloc.so
CMD ["./techempower"]

LD_PRELOAD 预加载 mimalloc,替换系统分配器;MySQL 主机名指向测试编排网络中的 tfb-database。Lua 版 lwan-lua.dockerfile 不设置 USE_MYSQL 等变量,因此默认走 SQLite(techempower.db)。

5.3 元数据声明

benchmark_config.json 把测试声明为两类:

  • default(C 版):database: mysql,approach: Realistic,classification: Micro,orm: Raw,language: C;
  • lua(Lua 版):URL 为 /lua.json 与 /lua.plaintext,language: Lua,flavor: Lua。

config.toml 与之对应地按 [main] 与 [lua] 两组声明了相同的信息,供新版测试工具链读取。

六、测试流程:从 URL 到 wrk 压测

6.1 测试类型与验证逻辑

仓库在 toolset/test_types 下为每个测试点定义了验证器,与 Lwan 六个端点一一对应:

  • json:校验 {"message":"Hello, World!"}(键值大小写不敏感,多余字段与多余字节数仅告警,见 verifications.py 的 verify_helloworld_object());
  • plaintext:要求响应包含 hello, world!(大小写不敏感),多余字节告警;
  • db:校验 id 在 1–10000、randomNumber 为正整数,并额外统计数据库实际执行的查询数;
  • query 与 cached-query:按 2 / 0 / foo / 501 / 空 五组参数请求,通过 verify_query_cases() 校验数组长度与每个元素的键值类型;
  • fortune:用 FortuneHTMLParser 对 HTML 做归一化后与标准串逐行 diff。

此外 verifications.py 的 verify_headers() 会强制检查 Server、Date、Content-Type 头、Content-Length/Transfer-Encoding 大小头,并验证连续两次请求的 Date 头不同(防响应缓存),Content-Type 必须匹配 application/json、text/html; charset=UTF-8 或 text/plain 的正则。

6.2 wrk 压测脚本

压测由 toolset/wrk/query.sh(Query/Cached Queries)与 toolset/wrk/pipeline.sh(Plaintext 流水线)执行,流程分三步:Primer(-d 5 -c 8 -t 8 预热连接)→ Warmup(全并发跑一个完整时长)→ 正式测量(按多个并发级别逐档压测并记录 STARTTIME/ENDTIME)。Plaintext 使用 pipeline.lua 脚本模拟请求流水线(每个连接多请求在途)。

七、验证清单:一键确认服务就绪

按 README 提供的地址,可用 curl 快速自检全部端点(前提:8080 端口服务已通过 ./techempower 启动,且按后端需要配置 MySQL 环境变量或准备 techempower.db):

curl -v http://localhost:8080/json
curl -v http://localhost:8080/plaintext
curl -v http://localhost:8080/db
curl -v "http://localhost:8080/queries?queries=5"
curl -v "http://localhost:8080/cached-queries?count=5"
curl -v http://localhost:8080/fortunes
curl -v http://localhost:8080/lua.json
curl -v http://localhost:8080/lua.plaintext

可重点观察响应头是否包含 Content-Type: application/json / text/plain / text/html; charset=UTF-8 与正确的 Content-Length,这正是 toolset/test_types/verifications.py 的通过条件。若用 Docker 运行,可用 docker build -f frameworks/C/lwan/lwan.dockerfile -t tfb-lwan frameworks/C/lwan 构建镜像,再以 -e 传入 USE_MYSQL、MYSQL_HOST 等环境变量并按 benchmark_config.json 的端口声明映射 -p 8080:8080 运行。

八、总结

Lwan 基准测试是理解"如何把一款零拷贝、协程驱动的 C Web 服务器接入标准化基准体系"的典型样例:六个 C handler 覆盖了从静态字符串(Plaintext)、声明式 JSON 编码(JSON/DB/Query)到缓存条目读取(Cached Queries)、协程模板渲染(Fortunes)的全部性能路径;数据库抽象层通过函数指针表把 MySQL/SQLite 的差异隔离在 src/database.c 内部;Lua 版本则展示了基于 LuaJIT 的模块化轻量实现。阅读时建议以 src/techempower.c 为入口,对照 techempower.conf 的路由声明与 toolset/test_types 的验证逻辑,即可完整串起"路由 → 处理 → 响应 → 验收"的整条链路。

登录后查看全文
FrameworkBenchmarks