Armeria 基准测试实现全解析:基于 TechEmpower Framework Benchmarks 的六项测试实战指南

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

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-8 byte[],响应直接复用该字节数组,避免每次请求重复编码,这是纯 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));
  });
}

要点:

  1. getFortunes 在 blockingTaskExecutor 上执行 SELECT * FROM fortune,逐行构造 Fortune.java 对象列表;
  2. 按 TFB 规范追加一条固定语句 "Additional fortune added at request time."(id 为 0);
  3. 按 message 字段字典序排序(Comparator.comparing(Fortune::getMessage));
  4. 用 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 的 repackage goal 把依赖打成一个自包含的 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 基准实现,其工程组织可以提炼为三层清晰的结构:

  1. 装配层:App.java 用 8080 端口 + 三个 annotatedService 完成服务注册,零路由配置;
  2. 业务层:HelloService(无状态)、PostgresDbService(DB 读/批量读/读后写)、PostgresFortunesService(DB 读 + 排序 + Mustache 渲染)分别对应 README 中列出的全部测试 URL;
  3. 基础设施层:HikariCP 管理 PostgreSQL 连接,blockingTaskExecutor 隔离阻塞 JDBC 调用,Mustache 模板位于 classpath 资源,pom.xml + armeria.dockerfile 负责产出自包含可执行 JAR 与最小化运行镜像。

这套实现最值得借鉴的实践,是将 Netty 事件循环与 JDBC 阻塞操作彻底分离:所有数据库查询都通过 CompletableFuture.supplyAsync(..., ctx.blockingTaskExecutor()) 提交到独立线程池,既保持了 Armeria 异步、高吞吐的 I/O 特性,又不牺牲 JDBC 生态的成熟度——这正是 Armeria 作为"Realistic"型微服务框架参与基准测试的典型姿势。

登录后查看全文
FrameworkBenchmarks