Basolato(Nim)框架在 TechEmpower Framework Benchmarks 中的六项基准测试实现解析
Basolato(Nim)框架在 TechEmpower Framework Benchmarks 中的六项基准测试实现解析
Basolato 是 Nim 语言的全栈 Web 框架,在本仓库中被用于参与 TechEmpower Framework Benchmarks(TFB)基准测试。本文以 frameworks/Nim/basolato/README.md 为主线,完整梳理 Basolato 需要实现的 JSON、PLAINTEXT、DB、QUERY、UPDATE、FORTUNES 六项测试的接入方式与访问 URL,并结合控制器源码、数据库连接配置、Dockerfile 构建流程与 TFB 工具集的校验脚本,深入讲解每一项测试的底层实现原理。读完本文,你将掌握如何阅读并复现一个 TFB 框架实现,也能够在本地起服务、用 wrk 与 TFB 校验器验证各测试点的正确性。
一、测试实现概览:单一控制器承载六类测试
Basolato 的基准测试 README 非常精简,核心信息是:六项测试的全部实现源码都集中在同一个控制器文件中:
从 benchmark_config.json 的元数据可以看出该实现的定位:
- approach:
Realistic(真实应用场景) - classification:
Fullstack(全栈框架) - database:
postgres - orm:
Full(使用完整 ORM——allographer) - platform:
asynchttpserver(Nim 标准库异步 HTTP 服务器) - webserver:
None(不挂载外部 Web 服务器) - display_name:
Basolato - versus:
httpbeast, prologue(同属 Nim 语言候选框架) - tags: 含
broken标记,说明该实现曾在验证/运行环节存在问题,阅读源码时应注意区分"规范要求"与"实际运行状态"
二、六项测试的访问 URL 与响应校验要点
README 中给出了全部测试 URL,服务默认监听 8080 端口。这些 URL 与 TFB 工具集 toolset/test_types 中各校验器的 *_url 配置一一对应:
2.1 JSON
http://localhost:8080/json
返回 {"message":"Hello, World!"}。校验器 toolset/test_types/json/json.py 要求响应为合法的 JSON 对象。
2.2 PLAINTEXT
http://localhost:8080/plaintext
返回纯文本 Hello, World!,Content-Type 应为 text/plain。校验器 toolset/test_types/plaintext/plaintext.py 会做大小写不敏感匹配(body.lower() 后查找 hello, world!),并警告响应是否多返回了多余字节("Server is returning N more bytes than are required"),提示多余字节会拖累基准成绩。
2.3 DB
http://localhost:8080/db
随机取一条 World 记录,返回 JSON 对象 {"id": N, "randomNumber": N}。校验器 toolset/test_types/db/db.py 通过 verify_randomnumber_object 校验 id 与 randomNumber 均为整数键,并统计数据库查询次数是否符合预期(每次请求恰好 1 次查询)。
2.4 QUERY
http://localhost:8080/queries?queries=1
queries 参数指定要随机查询的记录条数,返回 JSON 数组。校验器 toolset/test_types/query/query.py 定义了多组边界用例:2(正常)、0(非法)、foo(非法)、501(超上限警告)、空值(非法),并要求数组元素含 id 与 randomNumber 整数键。
2.5 UPDATE
http://localhost:8080/updates?queries=1
读取随机记录后更新其 randomNumber 字段,返回更新后的 JSON 数组。校验器 toolset/test_types/update/update.py 与 QUERY 共用同一组边界用例,并额外要求返回字段反映更新后的随机数。
2.6 FORTUNES
http://localhost:8080/fortunes
查询 Fortune 表全部数据,注入一条 Additional fortune added at request time. 后按 message 排序,渲染 HTML 表格。校验器 toolset/test_types/fortune/fortune.py 使用 FortuneHTMLParser 对 HTML 结构做严格比对,并统计预期的行数(12 行 × 请求数)。
三、源码级实现:路由注册与六个处理器
3.1 入口与路由表
main.nim 是应用入口:导入 basolato 框架与控制器,声明路由表后调用 serve(routes) 启动 asynchttpserver:
import basolato
import ./app/http/controllers/benchmark_controller
let routes = @[
Route.get("/plaintext", benchmark_controller.plainText),
Route.get("/json", benchmark_controller.json),
Route.get("/db", benchmark_controller.db),
Route.get("/queries", benchmark_controller.query),
Route.get("/fortunes", benchmark_controller.fortune),
Route.get("/updates", benchmark_controller.update),
]
serve(routes)
六个路由全部为 GET 方法,与 README 中的测试 URL 完全对应。注意 main 是构建产物的可执行文件(仓库中已附带编译产物),serve 是 Basolato 框架对外暴露的启动入口。
3.2 预编译 SQL 与常量
benchmark_controller.nim 开头定义了基准测试的关键常量与预编译语句:
const range1_10000 = 1..10000
let getFirstPrepare = stdRdb.prepare("getFirst", sql""" SELECT * FROM "World" WHERE id = $1 LIMIT 1 """, 1)
let getFortunePrepare = stdRdb.prepare("getFortunes", sql""" SELECT * FROM "Fortune" ORDER BY message ASC """, 0)
range1_10000:随机 id 的取值范围(World表共 10000 行);getFirstPrepare:按主键取单行,prepare的第三个参数为占位符数量(1 个);getFortunePrepare:一次取回全部Fortune并按message升序(0 个占位符),这也是 FORTUNES 测试"排序"要求的一部分。
3.3 PLAINTEXT 与 JSON:纯内存响应
proc plaintext*(context:Context, params:Params):Future[Response] {.async.} =
let headers = newHttpHeaders()
headers.add("Content-Type", "text/plain; charset=UTF-8")
return render("Hello, World!", headers)
proc json*(context:Context, params:Params):Future[Response] {.async.} =
return render(%*{"message":"Hello, World!"})
两个处理器均不访问数据库。PLAINTEXT 手动指定 text/plain; charset=UTF-8 响应头;JSON 直接使用 Nim 标准库 std/json 的 %* 构造字面量并交给 render 序列化。所有控制器统一签名 (context:Context, params:Params),返回 Future[Response],符合 Basolato 的异步处理器约定。
3.4 DB 与 QUERY:预编译语句 + 随机读取
proc db*(context:Context, params:Params):Future[Response] {.async.} =
let i = rand(1..10000)
let res = stdRdb.getRow(getFirstPrepare, i)
return render(%*{"id": res[0].parseInt, "randomNumber": res[1].parseInt})
DB 测试只做一次随机查询;QUERY 测试则把逻辑放进循环:
proc query*(context:Context, params:Params):Future[Response] {.async.} =
var countNum =
try:
params.getInt("queries")
except:
1
if countNum < 1:
countNum = 1
elif countNum > 500:
countNum = 500
...
这里实现了 TFB 对 QUERY/UPDATE 的两个硬性要求:参数缺失/非法时默认 1,合法范围限制在 1~500(超 500 截断)。之后按 countNum 循环调用 stdRdb.getRow(getFirstPrepare, n) 并 map 成 JSON 数组返回。注意 QUERY 的并发模型是"逐条串行"读取,并未像 UPDATE 那样使用 all(futures).await 并行化,这是实现层面的一个可优化点。
3.5 UPDATE:异步并行更新
proc update*(context:Context, params:Params):Future[Response] {.async.} =
...
var response = newSeqJsonNode
var futures = newSeq[Future[void]](countNum)
for i in 1..countNum:
let index = rand(range1_10000)
let number = rand(range1_10000)
response[i-1] = %*{"id": index, "randomNumber": number}
futures[i-1] = (
proc():Future[void] {.async.} =
discard stdRdb.getRow(getFirstPrepare, i)
rdb.raw(""" UPDATE "World" SET "randomnumber" = ? WHERE id = ? """, %*[number, index]).exec()
)()
all(futures).await
return render(%response)
UPDATE 的关键设计是:为每条记录构造一个 async 闭包,内部先 getRow(满足"先读再改"的规范),再通过 allographer 的 rdb.raw(...).exec() 执行参数化 UPDATE,最后用 all(futures).await 等待全部协程完成。响应数组在进入循环前就已按序占位,避免并发写回时的竞态。
3.6 FORTUNES:模型 + 模板视图
处理器将查询结果映射为 Fortune 对象,追加测试要求的额外条目,再按 message 排序后交给视图渲染:
var rows = results.map(
proc(x:seq[string]):Fortune =
return Fortune(id: x[0].parseInt, message: x[1])
)
rows.add(Fortune(id: 0, message: "Additional fortune added at request time."))
rows = rows.sortedByIt(it.message)
return render(fortuneScfView(rows).await)
数据模型定义在 app/models/fortune.nim,仅含 id:int 与 message:string 两个字段。视图 app/http/views/pages/fortune_scf_view.nim 使用 stdtmpl 模板语法(文件头 #? stdtmpl(toString="toString") | standard):模板声明接收 seq[Fortune] 参数,#for row in rows: 循环输出 <tr>,${row.id} / ${row.message} 完成插值,最终生成符合 TFB FORTUNES 校验器要求的 HTML 表格(<title>Fortunes</title>、<th>id</th>、<th>message</th> 等结构均与 toolset/test_types/fortune/fortune.py 的解析器对齐)。
四、数据库层:双连接抽象的设计
config/database.nim 是连接配置的核心,它同时创建了两个数据库句柄,分别服务于两种不同的访问路径:
let rdb* = dbopen(
PostgreSQL,
getEnv("DB_DATABASE"),
getEnv("DB_USER"),
getEnv("DB_PASSWORD"),
getEnv("DB_HOST"),
getEnv("DB_PORT").parseInt,
maxConnections,
getEnv("DB_TIMEOUT").parseInt,
getEnv("LOG_IS_DISPLAY").parseBool,
getEnv("LOG_IS_FILE").parseBool,
getEnv("LOG_DIR"),
)
let stdRdb* = open(getEnv("DB_HOST"), getEnv("DB_USER"), getEnv("DB_PASSWORD"), getEnv("DB_DATABASE"))
rdb:allographer(Nim 的 ORM/Query Builder 库)的dbopen连接,带连接池能力,用于 UPDATE 的raw执行;stdRdb:直接使用db_connector/db_postgres标准驱动的open,配合prepare/getRow/getAllRows完成预编译语句的高效查询。
两者的环境变量完全一致,均来自 Docker 运行时注入。allographer 支持的数据库类型在注释中列出:SQLite3 / MySQL / MariaDB / PostgreSQL,本实现选用 PostgreSQL。
连接池大小的动态计算是本文件的一个细节:在 release 构建下,maxConnections 由环境变量 DB_MAX_CONNECTION 除以 CPU 核数后再减 2 得到:
let maxConnections =
when defined(release):
(getEnv("DB_MAX_CONNECTION").parseInt div countProcessors()) - 2
else:
95
echo "maxConnections: ", maxConnections
when defined(release) 是 Nim 的编译期条件分支——调试构建固定为 95,发布构建则按 CPU 数均摊连接配额,避免多进程抢占连接。该文件编译期 echo 输出的 maxConnections 可用于启动时人工核对。
框架层面的环境开关由 config.nims 控制,它通过 putEnv 声明宿主与数据库类型:
putEnv("HOST", "0.0.0.0")
putEnv("DB_POSTGRES", $true)
putEnv("SESSION_TYPE", "file")
putEnv("SESSION_DB_PATH", "./session.db")
putEnv("LIBSASS", $false)
config.nims 以注释形式给出可切换项:DB_SQLITE、DB_MYSQL、DB_MARIADB、SESSION_TYPE(file 或 redis)等,方便针对不同数据库后端改造。
五、构建与运行:Dockerfile 多阶段流程与全部环境变量
5.1 构建阶段
basolato.dockerfile 采用两阶段构建。build 阶段基于 ubuntu:22.04,依次执行:
ARG VERSION="2.0.2"
RUN curl https://nim-lang.org/choosenim/init.sh -o init.sh
RUN sh init.sh -y
ENV PATH $PATH:/root/.nimble/bin
RUN choosenim ${VERSION}
...
RUN nimble install -y
RUN ducere build -p:8080 -o:speed
- 通过
choosenim安装指定版本的 Nim 工具链(默认2.0.2,与 basolato.nimble 中requires "nim >= 2.0.0"匹配); nimble install -y拉取全部依赖,其中框架本体锁定为itsumura-h/nim-basolato == 0.15.0,ORM 锁定为allographer == 0.29.1(basolato.nimble);ducere build -p:8080 -o:speed以 8080 端口、速度优先的优化选项编译出main可执行文件。
5.2 运行阶段
runtime 阶段只拷贝编译产物与启动脚本(startServer.sh),并注入全套运行时环境变量:
| 环境变量 | 值 | 说明 |
|---|---|---|
SECRET_KEY |
长随机串 | 框架会话加密密钥 |
DB_DATABASE |
hello_world |
数据库名 |
DB_USER |
benchmarkdbuser |
TFB 标准测试账号 |
DB_PASSWORD |
benchmarkdbpass |
TFB 标准测试密码 |
DB_HOST |
tfb-database |
TFB 编排环境中的数据库主机名 |
DB_PORT |
5432 |
PostgreSQL 端口 |
DB_MAX_CONNECTION |
2000 |
连接池上限(构建期除以 CPU 数) |
DB_TIMEOUT |
30 |
数据库超时(秒) |
LOG_IS_DISPLAY / LOG_IS_FILE |
false |
关闭显示/文件日志 |
SESSION_TIME |
20160 |
会话时长(分钟) |
LOCALE |
en |
语言环境 |
容器最后执行 CMD ./startServer.sh 并 EXPOSE 8080,DB_HOST 指向 TFB 编排中名为 tfb-database 的数据库容器。
5.3 本地复现步骤
仓库是只读的,但你可以在自己的环境中按相同顺序复现:
- 安装 Nim ≥ 2.0.0,并执行
nimble install -y安装 basolato.nimble 声明的依赖(basolato、allographer、interface_implements、bcrypt、cligen、redis、sass); - 按 config.nims 配置 PostgreSQL 开关与
HOST=0.0.0.0; - 参照 config/database.nim 的环境变量要求,预先导出
DB_DATABASE、DB_USER、DB_PASSWORD、DB_HOST、DB_PORT等; - 以
release模式编译并运行main,然后逐一访问 README 中的六个 URL 验证响应。
六、如何用 TFB 工具集验证测试点
TFB 工具集为每个测试类型提供了独立的校验器(toolset/test_types/*/verify),它们是判断实现是否合规的"裁判",也可在本地直接复用:
- 查询边界:QUERY/UPDATE 要求参数在 1~500 之间,非法参数(
0、foo、空值)应回退为 1 或报错、501应截断为 500。Basolato 在 benchmark_controller.nim 中通过try/except+ 上下限分支实现了这套逻辑; - 响应头:JSON/DB 类要求
application/json,PLAINTEXT 要求text/plain,FORTUNES 要求text/html,分别对应verify_headers(..., should_be=...)断言; - 行数与查询次数:DB 每次请求应恰好 1 次查询,FORTUNES 每响应 12 行,校验器通过
verify_queries_count在请求结束后核对数据库查询计数; - 压测脚本:负载测试由 toolset/wrk/concurrency.sh(DB/JSON/FORTUNES)、toolset/wrk/query.sh(QUERY/UPDATE)与 toolset/wrk/pipeline.sh(PLAINTEXT 流水线)驱动,均以
wrk按 Primer → Warmup → 正式分级压测的流程执行;QUERY 类还可用 toolset/wrk/pipeline.lua 调整请求流水线深度。
七、小结
Basolato 的 TFB 实现是一个非常典型的"Nim 全栈框架接入基准测试"样本:README 用一张表与一组 URL 圈定了全部验收点;benchmark_controller.nim 用六个 async 处理器覆盖六项测试,并通过预编译语句、参数化 UPDATE、协程并行与 stdtmpl 模板,展示了 Basolato 的异步路由、allographer ORM 与模板视图的协作方式;basolato.dockerfile 与 config/database.nim 则完整呈现了从编译优化到数据库连接池调优的落地细节。需要留意的是,benchmark_config.json 中该实现仍带有 broken 标记,后续迭代时可参照本文第二节的校验规则逐项排查。