Armeria 基准测试实现全解析:基于 TechEmpower Framework Benchmarks 的六项测试实战指南
Armeria 基准测试实现全解析:基于 TechEmpower Framework Benchmarks 的六项测试实战指南
本文以 TechEmpower Framework Benchmarks 仓库中 Armeria 框架的完整实现为主线,深入拆解其如何用 Armeria 1.33.4 构建 /json、/db、/queries/、/updates/、/fortunes、/plaintext 六大基准测试端点,并结合 HikariCP 连接池、PostgreSQL JDBC 驱动与 Mustache 模板引擎的底层代码,讲解从应用装配、数据库访问到 Docker 化部署的完整链路。读者在读完本文后,既能掌握 Armeria 注解式服务(Annotated Service)与 blockingTaskExecutor 的异步编程模式,也能复现这套可运行的基准测试工程,并理解 Toolset 验证器对每个端点的具体校验规则。
一、项目背景:这套 Armeria 实现属于谁
这份 README 是 TechEmpower Framework Benchmarks(TFB)仓库中 Java/armeria 目录的测试说明文档。TFB 是一套用于横向比较各类 Web 开发平台的基准测试套件,armeria 目录即其中"Armeria + PostgreSQL"这一参赛实现。仓库根目录见 README,整个基准套件的调度入口位于 tfb 与 toolset/run-tests.py。
该实现的技术栈在 README 中明确列出:
| 组件 | 版本 | 用途 |
|---|---|---|
| Armeria | 1.33.4 | 异步/响应式 HTTP 服务器与 RPC 框架 |
| HikariCP | 7.0.2 | JDBC 连接池 |
| PostgreSQL JDBC 驱动 | 42.7.8 | 访问 PostgreSQL 数据库 |
| Mustache (mustache.java compiler) | 0.9.14 | Fortunes 测试的 HTML 模板渲染 |
这四项版本声明与 pom.xml 中的依赖声明完全一致,是构建与运行的权威依据。
二、项目结构:一个高度精简的 Maven 工程
armeria 目录整体结构如下,所有业务逻辑集中在 hello 包内:
frameworks/Java/armeria/
├── README.md # 测试说明文档(本文章主题)
├── armeria.dockerfile # 多阶段构建镜像
├── benchmark_config.json # TFB 基准配置
├── config.toml # 与 benchmark_config.json 等价的新版配置
├── pom.xml # Maven 构建文件
└── src/main/
├── java/hello/
│ ├── App.java # 服务装配入口
│ ├── helpers/PostgresDbHelper.java # HikariCP 数据源工厂
│ ├── models/Message.java / World.java / Fortune.java
│ └── services/
│ ├── HelloService.java # /json 与 /plaintext
│ ├── PostgresDbService.java # /db、/queries/、/updates/
│ └── PostgresFortunesService.java # /fortunes
└── main/resources/fortunes.mustache # Fortune 渲染模板
一个值得注意的细节:README 的 "Source for Tests" 一节写的文件名是 DbService.java 与 FortunesService.java,而实际仓库中的实现文件名为 PostgresDbService.java 与 PostgresFortunesService.java。阅读源码时应以后者为准——README 的命名属于历史遗留的简写,不影响任何功能。
三、应用装配入口:App.java 与注解式服务
App.java 是整个应用的唯一入口,展示了 Armeria 最基础的启动方式:
public final class App {
public static void main(String[] args) {
ServerBuilder sb = Server.builder();
sb.http(8080)
.annotatedService(new HelloService())
.annotatedService(new PostgresDbService())
.annotatedService(new PostgresFortunesService());
Server server = sb.build();
server.start().join();
}
}
关键点:
Server.builder()创建ServerBuilder,http(8080)监听 8080 端口(与 benchmark_config.json 中"port": 8080一致);annotatedService(...)把三个普通 POJO 注册为 Armeria 的注解式服务,Armeria 会扫描类上的@Get等路由注解自动完成映射,无需编写路由表;server.start().join()同步阻塞等待服务器启动完成,保证基准测试压测时服务已就绪。
Armeria 基于 Netty 构建(benchmark_config.json 中 "platform": "Netty"、"webserver": "None" 即说明它自带 Web 服务器,不依赖外部反向代理),因此三个服务共享同一个 Netty event loop,而阻塞的 JDBC 调用被显式迁移到 blockingTaskExecutor 线程池执行,见下文第四节。
四、无状态端点:JSON 序列化与 Plaintext
HelloService.java 实现了两个无数据库依赖的测试端点:
public class HelloService {
private static final byte[] PLAINTEXT =
"Hello, World!".getBytes(StandardCharsets.UTF_8);
@Get("/plaintext")
public HttpResponse plaintext() {
return HttpResponse.of(HttpStatus.OK, MediaType.PLAIN_TEXT_UTF_8, PLAINTEXT);
}
@Get("/json")
@ProducesJson
public Message json() {
return new Message("Hello, World!");
}
}
对应 README 中的测试 URL:
| 测试 | URL | 响应格式 |
|---|---|---|
| JSON Serialization | http://localhost:8080/json |
JSON 对象 {"message":"Hello, World!"} |
| Plaintext | http://localhost:8080/plaintext |
纯文本 Hello, World! |
实现上的性能细节:
- Plaintext 预编码:
"Hello, World!"在类加载时就被编码为 UTF-8byte[],响应直接复用该字节数组,避免每次请求重复编码,这是纯 I/O 型基准测试的常见优化; - JSON 返回 POJO:
@ProducesJson让 Armeria 自动将Message对象序列化为 JSON;Message.java 是一个仅有public String message字段的极简模型,序列化开销极低。
Toolset 侧的校验逻辑(见 toolset/test_types/json/json.py 与 toolset/test_types/plaintext/plaintext.py)会验证:JSON 响应的 Content-Type 必须是 JSON、body 解析后是含 message 键的对象;plaintext 响应 body(转为小写后)必须包含 hello, world!,且返回字节数超过必要字节会给出 warn 提示(影响性能评分),这解释了为什么本实现要预编码固定字节串。
五、数据库端点:单查询、批量查询与更新
PostgresDbService.java 承载了三个依赖 PostgreSQL 的测试:Single Database Query(/db)、Multiple Database Query(/queries/)、Database Updates(/updates/)。
5.1 数据源:HikariCP 连接池
服务构造时通过 PostgresDbHelper.java 创建连接池:
public static HikariConfig hikariConfig() {
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:postgresql://tfb-database:5432/hello_world");
config.setUsername("benchmarkdbuser");
config.setPassword("benchmarkdbpass");
return config;
}
注意主机名是 tfb-database——这是 TFB 工具集在 Docker 网络内为数据库容器分配的固定别名,账号/密码与 toolset/databases/postgres/postgres.py 中的连接参数一致,也与 create-postgres.sql 中 GRANT ALL PRIVILEGES ... to benchmarkdbuser 的授权对应。HikariConfig 未显式设置池大小、超时等参数时使用 HikariCP 默认值,从源码结构看这是为了贴近"Raw + 默认配置"的基准定位("orm": "Raw")。
5.2 SQL 与随机数
private static final String SELECT_QUERY = "SELECT * FROM world WHERE id = ?";
private static final String UPDATE_QUERY =
"UPDATE world SET randomNumber = ? WHERE id = ?";
- 查询使用
PreparedStatement绑定参数,避免 SQL 注入且便于驱动复用执行计划; - 随机 id 生成遵循 TFB 规范:
1 + ThreadLocalRandom.current().nextInt(10000),取值范围 1–10000,恰好覆盖 create-postgres.sql 中generate_series(1,10000)建出的 10000 行 World 表; ThreadLocalRandom避免了多线程竞争共享Random实例。
5.3 /db:单条查询
@Get("/db")
@ProducesJson
public CompletableFuture<World> db(ServiceRequestContext ctx) throws Exception {
return getWorld(getRandomNumber(), ctx);
}
getWorld 的完整逻辑为:在 ctx.blockingTaskExecutor() 上通过 CompletableFuture.supplyAsync 提交阻塞任务,任务内取连接、执行 SELECT、读取 (id, randomNumber) 两列并封装为 World.java 对象。这是 Armeria 异步模型与 JDBC 阻塞 I/O 的标准桥接方式:Netty 事件循环绝不执行阻塞调用,JDBC 全部在专门的阻塞线程池中运行,从而保证高并发下事件循环不被拖垮。
Toolset 的 db 校验器(toolset/test_types/db/db.py)会验证响应是含 id 与 randomNumber 两个整数字段的 JSON 对象,并通过 pg_stat_statements 统计实际 SQL 执行次数(verify_queries_count),确保每次请求恰好一次数据库查询。
5.4 /queries/:批量查询
@Get("/queries/{count}")
@ProducesJson
public CompletableFuture<World[]> queries(
@Param("count") String count,
ServiceRequestContext ctx) {
return doQueries(count, ctx);
}
@Get("/queries/")
@ProducesJson
public CompletableFuture<World[]> queries(ServiceRequestContext ctx) {
return doQueries("", ctx);
}
同一端点提供了带路径参数(/queries/{count})与不带参数(/queries/,默认 count)两个重载,@Param("count") 从路径中提取参数。getSanitizedCount 实现了参数清洗:
private static int getSanitizedCount(String count) {
try {
int intCount = Integer.parseInt(count);
if (intCount < 1) {
return 1;
}
if (intCount > 500) {
return 500;
}
return intCount;
} catch (NumberFormatException e) {
return 1;
}
}
规则:小于 1 或非数字一律取 1,大于 500 截断为 500。这与 Toolset query 校验器(toolset/test_types/query/query.py)的测试用例完全对应——它会对 '2'(合法)、'0'(应归 1)、'foo'(应归 1)、'501'(应截断为 500 并告警)、''(默认值)逐例验证返回数组长度。getWorlds 在单个 JDBC 连接上顺序循环 count 次执行 SELECT,返回 World[]。
5.5 /updates/:查询后更新
@Get("/updates/{count}")
@ProducesJson
public CompletableFuture<World[]> update(
@Param("count") String count,
ServiceRequestContext ctx) {
return doUpdate(count, ctx);
}
@Get("/updates/")
@ProducesJson
public CompletableFuture<World[]> update(ServiceRequestContext ctx) {
return doUpdate("", ctx);
}
getUpdatedWorlds 的核心流程(循环内每个 id 两段 SQL):
try (final PreparedStatement select =
connection.prepareStatement(SELECT_QUERY);
final PreparedStatement update =
connection.prepareStatement(UPDATE_QUERY)) {
// get
select.setInt(1, id);
try (final ResultSet set = select.executeQuery()) {
set.next();
// update
update.setInt(1, randomNumber);
update.setInt(2, id);
update.execute();
worlds[i] = new World(id, set.getInt(2));
worlds[i].randomNumber = randomNumber;
}
}
即:先 SELECT 出该行的原 randomNumber,再生成新的随机值 UPDATE 回数据库,返回的 World 中 id 为查询到的原 id、randomNumber 为新写入的值。校验器 toolset/test_types/update/update.py 使用与 query 相同的 5 组边界用例(且 verify_query_cases(..., True) 表示这是更新型端点),并通过 pg_stat_statements 分别核对 select 与 update 的行数统计(见 toolset/databases/postgres/postgres.py 的 get_rows / get_rows_updated)。
5.6 端点汇总表
| 测试 | URL(localhost:8080) | 实现位置 | 数据库依赖 |
|---|---|---|---|
| Single Database Query | /db |
PostgresDbService | 是 |
| Multiple Database Query | /queries/(或 /queries/{count}) |
PostgresDbService | 是 |
| Database Updates | /updates/(或 /updates/{count}) |
PostgresDbService | 是 |
| Fortunes | /fortunes |
PostgresFortunesService | 是 |
| JSON Serialization | /json |
HelloService | 否 |
| Plaintext | /plaintext |
HelloService | 否 |
六、模板渲染端点:Fortunes
PostgresFortunesService.java 实现 Fortunes 测试,它组合了 JDBC 查询、排序与 Mustache 模板渲染:
@Get("/fortunes")
public CompletableFuture<HttpResponse> fortunes(ServiceRequestContext ctx) {
return getFortunes(ctx).thenApply(fortunes -> {
fortunes.add(
new Fortune(0, "Additional fortune added at request time."));
fortunes.sort(Comparator.comparing(Fortune::getMessage));
return HttpResponse.of(
HttpStatus.OK, MediaType.HTML_UTF_8, buildMustacheTemplate(fortunes));
});
}
要点:
getFortunes在blockingTaskExecutor上执行SELECT * FROM fortune,逐行构造 Fortune.java 对象列表;- 按 TFB 规范追加一条固定语句
"Additional fortune added at request time."(id 为 0); - 按
message字段字典序排序(Comparator.comparing(Fortune::getMessage)); - 用 Mustache 渲染成 HTML 返回,
Content-Type为text/html。
Mustache 工厂的构造是一个值得注意的兼容性细节:
private final MustacheFactory mustacheFactory = new DefaultMustacheFactory(
name -> new InputStreamReader(
HelloService.class.getClassLoader().getResourceAsStream(name)));
源码注释明确说明:Mustache 在当前线程上找不到 ClassLoader,必须手动传入,才能从 classpath 加载 fortunes.mustache(模板内容为标准的 <table> 结构,用 {{#.}}...{{/.}} 遍历列表渲染 id 与 message 列)。模板放在 src/main/resources 下,最终被打进可执行 JAR 的资源目录。
Toolset 的 fortune 校验器(toolset/test_types/fortune/fortune.py)会用 FortuneHTMLParser 解析返回 HTML,逐行与标准模板 diff 比对,同时校验响应头为 html,并通过查询计数确认每次请求恰好一次 DB 查询、返回 12 行基础数据。
七、构建与运行:pom.xml、Dockerfile 与基准配置
7.1 Maven 构建配置
pom.xml 的关键点:
- Java 版本:
maven.compiler.source/target = 25,即当前实现面向 JDK 25 编译; - 依赖版本:
armeria 1.33.4、log4j-slf4j-impl 2.25.2(日志桥接)、postgresql 42.7.8、mustache.java compiler 0.9.14、HikariCP 7.0.2; - 可执行 JAR:使用
spring-boot-maven-plugin的repackagegoal 把依赖打成一个自包含的hello-1.0-SNAPSHOT.jar,<mainClass>hello.App</mainClass>指定启动类,<executable>true</executable>使其可直接java -jar运行; maven-compiler-plugin关闭 debug 信息(<debug>false</debug>),减小字节码体积。
7.2 多阶段 Docker 镜像
armeria.dockerfile 采用两阶段构建:
FROM maven:3.9.11-eclipse-temurin-25-alpine as maven
WORKDIR /armeria
COPY src src
COPY pom.xml pom.xml
RUN mvn package -q
FROM eclipse-temurin:25-jre-alpine
WORKDIR /armeria
COPY --from=maven /armeria/target/hello-1.0-SNAPSHOT.jar app.jar
EXPOSE 8080
CMD ["java", "-server", "-XX:+UseNUMA", "-XX:+UseParallelGC", "-jar", "app.jar"]
- 构建阶段用 Maven + Temurin 25 编译打包,运行阶段只保留
jre-alpine与单个 fat JAR,镜像体积最小化; - 运行参数
-server -XX:+UseNUMA -XX:+UseParallelGC针对服务器环境启用了 NUMA 感知与并行 GC,是基准场景下常见的 JVM 调优组合; EXPOSE 8080与 App 监听端口、配置中的port: 8080三者一致。
7.3 基准配置声明
benchmark_config.json 中为 TFB 工具集声明了本实现的元信息:
{
"framework": "armeria",
"tests": [{
"default": {
"json_url": "/json",
"plaintext_url": "/plaintext",
"db_url": "/db",
"query_url": "/queries/",
"update_url": "/updates/",
"fortune_url": "/fortunes",
"port": 8080,
"approach": "Realistic",
"classification": "Micro",
"database": "Postgres",
"framework": "armeria",
"language": "Java",
"flavor": "None",
"orm": "Raw",
"platform": "Netty",
"webserver": "None",
"os": "Linux",
"database_os": "Linux",
"display_name": "armeria",
"notes": "",
"versus": "netty"
}
}]
}
其中 approach: "Realistic"(贴近真实部署,未使用 xx:+UseNUMA 之外的特殊旁路)、classification: "Micro"(轻量级微服务型框架)、orm: "Raw"(手写 JDBC 而非 ORM)、platform: "Netty"、webserver: "None"(自带服务器)、versus: "netty"(与纯 Netty 实现对标)。同目录下的 config.toml 是同一份元信息的新版 TOML 表达,二者完全等价。
7.4 运行前提
本工程为基准测试而设计,直接运行需要满足:
- 数据库连接指向
tfb-database:5432的hello_world库,并使用benchmarkdbuser账号;库表结构由 create-postgres.sql 定义(World 表 10000 行、Fortune 表 12 行,含一条日文与一条 HTML 注入用例,用于校验 HTML 转义); - 推荐在 TFB 工具集(
toolset/)编排的 Docker 网络内构建运行,由 armeria.dockerfile 直接产出镜像; - 本地手动验证可执行
mvn package后运行java -jar target/hello-1.0-SNAPSHOT.jar,再依次访问 README 列出的六个 URL。
八、小结:这套实现的架构要点
回顾整个 Armeria 基准实现,其工程组织可以提炼为三层清晰的结构:
- 装配层:
App.java用 8080 端口 + 三个annotatedService完成服务注册,零路由配置; - 业务层:
HelloService(无状态)、PostgresDbService(DB 读/批量读/读后写)、PostgresFortunesService(DB 读 + 排序 + Mustache 渲染)分别对应 README 中列出的全部测试 URL; - 基础设施层:HikariCP 管理 PostgreSQL 连接,
blockingTaskExecutor隔离阻塞 JDBC 调用,Mustache 模板位于 classpath 资源,pom.xml+armeria.dockerfile负责产出自包含可执行 JAR 与最小化运行镜像。
这套实现最值得借鉴的实践,是将 Netty 事件循环与 JDBC 阻塞操作彻底分离:所有数据库查询都通过 CompletableFuture.supplyAsync(..., ctx.blockingTaskExecutor()) 提交到独立线程池,既保持了 Armeria 异步、高吞吐的 I/O 特性,又不牺牲 JDBC 生态的成熟度——这正是 Armeria 作为"Realistic"型微服务框架参与基准测试的典型姿势。