FrameworkBenchmarks 中 SimpleW(C/.NET)框架基准测试接入指南:plaintext 与 json 测试实现解析

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

FrameworkBenchmarks 中 SimpleW(C#/.NET)框架基准测试接入指南:plaintext 与 json 测试实现解析

本篇技术指南以 TechEmpower FrameworkBenchmarks 仓库中 SimpleW 基准测试文档 为主体,结合 Program.cs 入口实现、项目文件 Benchmarks.csproj、镜像构建文件 simplew.dockerfile 与 benchmark_config.json 等仓库资源,系统讲解 SimpleW 如何以 C# 13 与 .NET 8/9 为基础接入 FrameworkBenchmarks,实现 /api/plaintext 与 /api/json 两个基准测试端点。读完本文,你将理解该框架接入的目录结构、路由与响应构造方式、构建与运行流程,以及 Toolset 如何验证并压测这两条测试路径。

一、文档背景:SimpleW 在 FrameworkBenchmarks 中的定位

frameworks/CSharp/simplew/README.md 是 SimpleW 参与 TechEmpower Framework Benchmarks 时的测试说明文件,篇幅精炼但信息明确,其核心内容可归纳为三点:

  • 技术栈版本:语言为 C# 13.0,平台为 .NET 8/9;
  • 测试路径与源码对应关系:
    • Plaintext 测试 → /api/plaintext,实现在 Benchmarks/Program.cs;
    • JSON 测试 → /api/json,实现在 Benchmarks/Tests/JsonResource.cs(注:仓库当前实际将两个端点都写在 Program.cs 中,README 中的路径指示以仓库源码为准);
  • 官方文档链接:文档末尾指向 SimpleW 项目官网(README 中给出的网站地址),可作为阅读本文时的延伸参考。

需要说明的是,README 只覆盖了 FrameworkBenchmarks 全部 14 类测试(见 run-tests.py 中 --type 可选值)中的两个:plaintext 与 json。这一点在 benchmark_config.json 的 notes 字段中有明确记录:"Only plaintext and JSON benchmarks implemented yet"(目前仅实现了 plaintext 与 JSON 基准测试),说明 SimpleW 的接入属于"最小可用"状态——先打通两条无数据库、无 ORM 的纯 HTTP 测试路径。

二、目录结构与文件职责

SimpleW 测试位于 frameworks/CSharp/simplew/ 目录,顶层文件与 Benchmarks/ 子目录共同构成了一个可构建、可运行、可基准测试的完整框架单元:

文件 职责
README.md 测试说明:语言/平台版本、测试路径与源码映射
Benchmarks/Program.cs 服务器启动、路由注册与两个测试端点实现
Benchmarks/Benchmarks.csproj .NET 9 项目配置:目标框架、SimpleW 包引用、运行时与 GC 优化参数
simplew.dockerfile 多阶段构建镜像:SDK 编译 + runtime-deps 精简运行
benchmark_config.json FrameworkBenchmarks 识别的测试元数据(端口、URL、分类)
config.toml 面向 Toolset 的等效配置(TOML 格式)

其中 benchmark_config.json 与 config.toml 是同一份元数据的两种载体:前者是 FrameworkBenchmarks 主工具集读取的标准格式,后者供 Toolset 相关工具使用,字段一一对应。

三、测试元数据:FrameworkBenchmarks 如何"认识"SimpleW

3.1 benchmark_config.json 关键字段

FrameworkBenchmarks 通过 benchmark_config.json 获取测试的 URL、端口与分类信息,SimpleW 的配置如下:

  • framework: "simplew" —— 框架标识,也是框架目录名;
  • tests.default.plaintext_url: /api/plaintext —— plaintext 测试路径;
  • tests.default.json_url: /api/json —— JSON 测试路径;
  • tests.default.port: 8080 —— 服务器监听端口,与 Program.cs 中 new SimpleWServer(IPAddress.Any, 8080) 一致;
  • tests.default.approach: "Realistic" —— 测试方法论分类,指采用接近真实部署的配置;
  • tests.default.classification: "Fullstack" —— 框架分类为全栈(自带 Web 服务器与业务处理);
  • tests.default.database: "None"、orm: "None" —— 无数据库、无 ORM,与本测试集只含纯 HTTP 端点的事实吻合;
  • tests.default.platform: ".NET"、language: "C#";
  • tests.default.webserver: "Netcoreserver" —— 运行时 Web 服务器类型;
  • tests.default.os / database_os: "Linux";
  • tests.default.display_name: "SimpleW";
  • tests.default.notes: 说明目前仅实现 plaintext 与 JSON。

3.2 config.toml 的对应关系

config.toml 以 [framework] 与 [main] 两个段落承载相同信息:urls.plaintext、urls.json 分别对应两条测试路径,approach、classification、os、database_os、orm、platform、webserver 等字段与 JSON 配置逐项对应,versus = "None" 表示无对照基准。

四、源码实现:两条测试路径的完整逻辑

4.1 服务器启动与路由注册

Program.cs 的 Main 入口代码简洁清晰:

var server = new SimpleWServer(IPAddress.Any, 8080);
server.AddDynamicContent("/api");
server.Start();

await Task.Delay(-1);

关键点拆解:

  • SimpleWServer(IPAddress.Any, 8080):绑定所有 IPv4 网卡地址,端口 8080,与 benchmark 配置中的 port 字段一致;
  • AddDynamicContent("/api"):注册 /api 前缀的动态内容路由,后续 Controller 中声明的相对路由(/json、/plaintext)会被组合成完整路径 /api/json、/api/plaintext;
  • Start():启动服务器进入监听状态;
  • await Task.Delay(-1):无限挂起主协程,防止进程退出——这是基准测试场景中"服务器常驻"的典型写法。

4.2 JSON 端点

BenchmarksController 中的 Json() 方法(Program.cs L21-L32)实现了 JSON 测试:

[Route("GET", "/json")]
public object Json() {
    return Response.MakeResponse(
        new { message = "Hello, World!" }, // object will be serialized
        addHeaders: new Dictionary<string, string>()
        {
            { "Server", "SimpleW" },
            { "Date", DateTime.Now.ToString("R") }
        }
        // compress parameter is default to null, so no compression
    );
}
  • 路由特性 [Route("GET", "/json")]:声明 HTTP 方法与相对路径,最终对外为 /api/json;
  • Response.MakeResponse(匿名对象, ...):将 new { message = "Hello, World!" } 匿名对象自动序列化为 JSON 响应体;
  • addHeaders 显式补充 Server: SimpleW 与 Date(RFC 1123 格式的 "R" 标准日期格式)两个响应头;
  • 注释明确说明 compress 参数默认为 null,即不启用压缩——这与基准测试"测量原始输出能力"的目标一致,避免压缩消耗额外 CPU。

4.3 Plaintext 端点

Plaintext() 方法(Program.cs L34-L46)实现了 plaintext 测试:

[Route("GET", "/plaintext")]
public object Plaintext() {
    return Response.MakeResponse(
        "Hello, World!",
        "text/plain",
        addHeaders: new Dictionary<string, string>()
        {
            { "Server", "SimpleW" },
            { "Date", DateTime.Now.ToString("R") }
        }
        // compress parameter is default to null, so no compression
    );
}
  • 与 JSON 端点相比,多传了一个 "text/plain" 内容类型参数,其余响应头设置逻辑完全一致;
  • 两条路径的响应体文本都是 Hello, World!,这是 FrameworkBenchmarks 对这两个测试类型的统一要求(详见下文验证器)。

4.4 项目配置:面向性能的编译期调优

Benchmarks.csproj 中除了引用 SimpleW NuGet 包(Version="16.1.0")外,还体现了针对基准测试场景的运行时优化:

<ServerGarbageCollection>true</ServerGarbageCollection>
<TieredPGO>true</TieredPGO>
<RuntimeIdentifier>linux-musl-x64</RuntimeIdentifier>
  • ServerGarbageCollection=true:启用服务器模式 GC,为高并发请求场景优化内存管理策略;
  • TieredPGO=true:启用分层配置文件引导优化(Profile-Guided Optimization),让运行时在预热后基于实际执行路径生成更优的本地代码;
  • RuntimeIdentifier=linux-musl-x64:目标运行时标识为 Linux + musl libc 的 x64 环境,与下方 dockerfile 使用 Alpine 基础镜像(musl 实现)严格对应;
  • TargetFramework=net9.0:项目实际以 .NET 9 为目标框架(README 中"平台 .NET 8/9"说明 SimpleW 支持横跨这两个版本,仓库当前配置选用 9)。

五、镜像构建:多阶段 Dockerfile 与运行时环境变量

simplew.dockerfile 采用标准的多阶段构建,分为编译与运行两个阶段:

阶段一(构建):基于 mcr.microsoft.com/dotnet/sdk:9.0-alpine

  1. 先 COPY Benchmarks/*.csproj . 并执行 dotnet restore -r linux-musl-x64,将 NuGet 依赖还原缓存为独立镜像层,充分利用 Docker 层缓存加速后续重建;
  2. 再 COPY Benchmarks/ . 复制全部源码;
  3. 执行 dotnet publish -c release -o /app -r linux-musl-x64 --no-restore --self-contained,生成自包含(self-contained)发布产物到 /app,--no-restore 复用上一步的还原结果。

阶段二(运行):基于 mcr.microsoft.com/dotnet/runtime-deps:9.0-alpine

  • 由于阶段一已产出 self-contained 二进制,运行阶段不再需要完整 SDK 甚至 ASP.NET 运行时,仅使用极简的 runtime-deps 镜像,显著缩小最终镜像体积;
  • 设置三个 .NET 运行时环境变量,进一步压榨基准测试场景的性能:
    • DOTNET_GCDynamicAdaptationMode=0:关闭 GC 动态自适应模式,固定服务器 GC 的行为;
    • DOTNET_ReadyToRun=0:禁用 ReadyToRun 预编译格式,让分层 PGO 有机会对方法重新 JIT 并应用 profile 优化;
    • DOTNET_HillClimbing_Disable=1:关闭线程池爬山算法(Hill Climbing),避免基准测试期间线程池规模自适应抖动;
  • ENTRYPOINT ["./Benchmarks"] 直接运行发布产物,EXPOSE 8080 声明服务端口。

这套"SDK 构建 + runtime-deps 运行 + GC/线程池调优"的组合,是 .NET 框架在 FrameworkBenchmarks 中常见的性能取向工程实践。

六、Toolset 如何验证与压测这两条路径

6.1 验证逻辑:plaintext 与 json 的自动化检查

FrameworkBenchmarks 的 Toolset 在每次基准测试前都会对 URL 做响应验证。针对 SimpleW 的两条路径,对应验证器行为如下:

plaintext 验证器(toolset/test_types/plaintext/plaintext.py):

  • 发起请求后首先执行 basic_body_verification(body, url, is_json_check=False);
  • 校验测试 URL 长度至少 10 个字符(/api/plaintext 满足该约束);
  • 将响应体转为小写后检查是否包含 hello, world!,若多出多余字节则给出 warn(提示可能拖累性能);
  • 校验 HTTP 状态码与响应头是否符合 plaintext 预期。

json 验证器(toolset/test_types/json/json.py):

  • 校验 URL 长度至少 5 个字符(/api/json 满足);
  • 通过 verify_helloworld_object 检查响应体是否为 { "message": "hello, world!" } 形式(大小写与引号风格不敏感);
  • 同样校验状态码与响应头。

SimpleW 的两个端点分别返回 Hello, World! 文本与 { message = "Hello, World!" } JSON 对象,与上述验证规则完全匹配。

6.2 压测方式:concurrency.sh 与 pipeline.sh

两条路径的压测脚本与并发参数在验证器中定义:

  • json 使用 get_script_name() 返回的 concurrency.sh(见 json.py),配合 --concurrency-levels 指定的并发梯度(默认 <a href="https://link.gitcode.com/i/092b84fd930480197f40b39ccaafc4ce" target="_blank">16, 32, 64, 128, 256, 512],见 [run-tests.py);
  • plaintext 使用 pipeline.sh(见 plaintext.py),pipeline 深度为 16,使用 --pipeline-concurrency-levels 指定的梯度(默认 [256, 1024, 4096, 16384])。

两类脚本均基于 toolset/wrk 目录下的 wrk 工具生成,压测时长由 --duration 控制(默认 15 秒)。

6.3 运行方式:通过 tfb 与 run-tests.py

仓库根目录的 tfb 脚本会先构建 techempower/tfb 工具镜像,再以 Docker 方式挂载仓库并运行 Toolset;其内部实际入口是 toolset/run-tests.py。运行 SimpleW 测试的典型方式:

# 运行全部测试类型(默认会包含 simplew)
./tfb --mode verify --test simplew

# 只跑 plaintext 与 json 两种类型
./tfb --type plaintext json --test simplew

相关参数说明(取自 run-tests.py):

  • --test simplew:按框架目录名精确指定测试集;
  • --type:测试类型可选项为 all, json, db, query, cached-query, fortune, update, plaintext,SimpleW 目前只支持其中的 json 与 plaintext;
  • --mode:benchmark(完整压测)/ verify(仅启动、curl 验证后关闭)/ debug(跳过验证并保持服务器运行),接入初期建议先用 verify 或 debug 模式联调。

七、本地运行与调试建议

在不依赖完整 Toolset 的前提下,可以直接在本机验证 SimpleW 的响应:

cd frameworks/CSharp/simplew
dotnet run --project Benchmarks
curl -i http://127.0.0.1:8080/api/plaintext
curl -i http://127.0.0.1:8080/api/json

若本机缺少 .NET 9 SDK 与 linux-musl 运行环境,也可直接使用仓库提供的镜像构建流程:

docker build -t simplew-benchmark -f simplew.dockerfile .
docker run --rm -p 8080:8080 simplew-benchmark

需要留意的是,dotnet run 场景下 RuntimeIdentifier=linux-musl-x64 与 Alpine 环境绑定更紧密,本机调试若使用 glibc 发行版,应以 dockerfile 构建方式为准。

八、总结:SimpleW 接入的完整链路

从 README.md 一句话式的技术栈声明出发,沿仓库源码可以还原出 SimpleW 接入 FrameworkBenchmarks 的完整链路:

  1. 元数据层:benchmark_config.json 与 config.toml 声明端口 8080、/api/plaintext、/api/json 及 Fullstack/Realistic/Linux 等分类标签;
  2. 实现层:Program.cs 通过 SimpleWServer + Controller + Route 特性定义两条 GET 端点,统一返回 Hello, World! 并附加 Server/Date 响应头;
  3. 构建层:Benchmarks.csproj 以 net9.0 + linux-musl-x64 为目标,开启 Server GC 与分层 PGO;simplew.dockerfile 多阶段构建出精简运行镜像并注入 GC/线程池调优环境变量;
  4. 验证与压测层:Toolset 的 plaintext 与 json 验证器对两条路径做响应体、状态码、响应头校验,随后由 wrk 脚本按并发梯度执行 concurrency.sh 与 pipeline.sh 压测。

对读者而言,若要在 FrameworkBenchmarks 中新增一个 .NET 框架测试,SimpleW 这份接入可以作为一个"无数据库、无 ORM、双纯 HTTP 端点"的最小可运行样板:它完整示范了元数据配置、路由实现、性能取向的编译/运行参数以及 Toolset 验证逻辑之间的对应关系。未来若为 SimpleW 补充数据库类测试(db/query/update 等),则只需新增对应端点并同步扩展 benchmark_config.json 的测试定义即可。

登录后查看全文
FrameworkBenchmarks