Basolato(Nim)框架在 TechEmpower Framework Benchmarks 中的六项基准测试实现解析

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

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 非常精简,核心信息是:六项测试的全部实现源码都集中在同一个控制器文件中:

测试类型 实现源码(仓库相对路径)
JSON app/http/controllers/benchmark_controller.nim
PLAINTEXT app/http/controllers/benchmark_controller.nim
DB app/http/controllers/benchmark_controller.nim
QUERY app/http/controllers/benchmark_controller.nim
UPDATE app/http/controllers/benchmark_controller.nim
FORTUNES app/http/controllers/benchmark_controller.nim

从 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
  1. 通过 choosenim 安装指定版本的 Nim 工具链(默认 2.0.2,与 basolato.nimble 中 requires "nim >= 2.0.0" 匹配);
  2. nimble install -y 拉取全部依赖,其中框架本体锁定为 itsumura-h/nim-basolato == 0.15.0,ORM 锁定为 allographer == 0.29.1(basolato.nimble);
  3. 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 本地复现步骤

仓库是只读的,但你可以在自己的环境中按相同顺序复现:

  1. 安装 Nim ≥ 2.0.0,并执行 nimble install -y 安装 basolato.nimble 声明的依赖(basolato、allographer、interface_implements、bcrypt、cligen、redis、sass);
  2. 按 config.nims 配置 PostgreSQL 开关与 HOST=0.0.0.0;
  3. 参照 config/database.nim 的环境变量要求,预先导出 DB_DATABASE、DB_USER、DB_PASSWORD、DB_HOST、DB_PORT 等;
  4. 以 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 标记,后续迭代时可参照本文第二节的校验规则逐项排查。

登录后查看全文
FrameworkBenchmarks