FrameworkBenchmarks 中 SimpleW(C/.NET)框架基准测试接入指南:plaintext 与 json 测试实现解析
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 中的路径指示以仓库源码为准);
- Plaintext 测试 →
- 官方文档链接:文档末尾指向 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
- 先
COPY Benchmarks/*.csproj .并执行dotnet restore -r linux-musl-x64,将 NuGet 依赖还原缓存为独立镜像层,充分利用 Docker 层缓存加速后续重建; - 再
COPY Benchmarks/ .复制全部源码; - 执行
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 的完整链路:
- 元数据层:benchmark_config.json 与 config.toml 声明端口 8080、
/api/plaintext、/api/json及 Fullstack/Realistic/Linux 等分类标签; - 实现层:Program.cs 通过
SimpleWServer+Controller+Route特性定义两条 GET 端点,统一返回Hello, World!并附加Server/Date响应头; - 构建层:Benchmarks.csproj 以 net9.0 + linux-musl-x64 为目标,开启 Server GC 与分层 PGO;simplew.dockerfile 多阶段构建出精简运行镜像并注入 GC/线程池调优环境变量;
- 验证与压测层:Toolset 的 plaintext 与 json 验证器对两条路径做响应体、状态码、响应头校验,随后由 wrk 脚本按并发梯度执行
concurrency.sh与pipeline.sh压测。
对读者而言,若要在 FrameworkBenchmarks 中新增一个 .NET 框架测试,SimpleW 这份接入可以作为一个"无数据库、无 ORM、双纯 HTTP 端点"的最小可运行样板:它完整示范了元数据配置、路由实现、性能取向的编译/运行参数以及 Toolset 验证逻辑之间的对应关系。未来若为 SimpleW 补充数据库类测试(db/query/update 等),则只需新增对应端点并同步扩展 benchmark_config.json 的测试定义即可。