用 Micronaut Test 与 REST-Assured 验证 HTTP 端点-未完纪

来源：原文；作者或维护方：Sergio del Amo、Dean Wette。中文编译整理与技术核对：未完纪。核对日期：2026-10-05。

编辑自绘技术示意图；用于解释本文流程，不代表运行结果。

验证 HTTP 端点时，我们关心请求是否进入正确路由、响应状态是否符合预期，以及返回的正文是否正确。REST-Assured 为 Java 提供了描述请求和响应断言的接口；Micronaut Test REST-Assured 模块把它接入 Micronaut 的测试生命周期，并支持注入 RequestSpecification。这样，测试不必自己寻找嵌入式服务器的端口，也不必独立硬编码 REST-Assured 版本。

本指南使用 Java、Gradle 和 JUnit。它完成一个小而完整的成功路径：创建返回问候语的控制器，通过真实 HTTP 请求检查状态码 200 和正文 Hello World。本文译自 Sergio del Amo 与 Dean Wette 的官方指南，并补充源包版本核验；以下代码保留原作者版权头。

准备环境：以下载源码的目标版本为准

原页面的前提仍写 JDK 21 或更高版本，并要求正确配置 JAVA_HOME。但 2026-10-05 下载的官方完整示例中，gradle.properties 的 micronautVersion 为 5.2.0，而 build.gradle 明确把 Java 源码与目标兼容版本设为 25。若直接使用这个源包，应该准备匹配的 JDK 25；仅满足正文的 21+ 描述不足以证明可以编译。

micronautVersion=5.2.0

java {
    sourceCompatibility = JavaVersion.toVersion("25")
    targetCompatibility = JavaVersion.toVersion("25")
}

还需要常用编辑器或 IDE，以及下载构建依赖的环境。本文本身不要求 Docker 或云账户。可以从官方示例 ZIP 开始，也可以按下面的步骤创建项目。CLI 当前生成的项目版本可能随时间变化，不能据这个创建命令认定你拿到的就是上述源包版本。

创建应用

使用 Micronaut CLI 执行：

mn create-app example.micronaut.micronautguide --build=gradle --lang=java

也可以使用 Micronaut Launch。命令会创建名为 micronautguide 的目录，默认包名为 example.micronaut。按官方说明，不传 --build 时默认使用 Gradle 的 Kotlin DSL；不传 --lang 时使用 Java；不传 --test 时，Java/Kotlin 默认使用 JUnit，Groovy 默认使用 Spock。

实现问候端点

创建 src/main/java/example/micronaut/HelloController.java：

/*
 * Copyright 2017-2026 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package example.micronaut;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;

@Controller("/hello") // <1>
public class HelloController {
    @Get // <2>
    @Produces(MediaType.TEXT_PLAIN) // <3>
    public String index() {
        return "Hello World"; // <4>
    }
}

@Controller("/hello") 将控制器映射到 /hello。@Get 将 index() 映射为这个路径上的 GET 请求。方法返回普通字符串，因此通过 @Produces(MediaType.TEXT_PLAIN) 声明 text/plain，而不使用默认的 JSON 响应类型。

这个端点没有用户输入，也没有数据库、文件系统或外部 HTTP 访问，便于把注意力集中在测试请求的接入方式上。它也没有认证逻辑，不应因为这个例子可访问，就把实际业务端点都设计为匿名公开。

加入测试依赖

在 Gradle 的 dependencies 中加入 Micronaut Test REST-Assured 模块：

testImplementation("io.micronaut.test:micronaut-test-rest-assured")

这里没有单独填写版本，使用 Micronaut 平台提供的依赖管理。项目已经有对应的 JUnit 测试基础时，这个模块负责补齐 REST-Assured 集成。不要随意把它和另一组不匹配的手动版本混用。

注入 RequestSpecification 并断言响应

创建 src/test/java/example/micronaut/HelloControllerTest.java。源页面某处把路径写成 java/src/test/...；下载的 Java/Gradle 示例实际使用下面这个标准路径。

/*
 * Copyright 2017-2026 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import io.restassured.specification.RequestSpecification;
import org.junit.jupiter.api.Test;

import static org.hamcrest.CoreMatchers.is;

@MicronautTest // <1>
public class HelloControllerTest {

    @Test
    public void testHelloEndpoint(RequestSpecification spec) { // <2>
        spec    // <3>
            .when()
                .get("/hello")
            .then()
                .statusCode(200)
                .body(is("Hello World"));
    }
}

@MicronautTest 初始化应用上下文和嵌入式服务器。JUnit 5 的测试方法可以声明 RequestSpecification 参数，集成模块会为它设置测试服务器端口，所以无需再注入 EmbeddedServer 并自己读取端口。请求规格也支持字段注入；原文明确指出，方法参数注入仅适用于 JUnit 5。

请求和断言按顺序读即可：when().get("/hello") 发起 GET 请求，then().statusCode(200) 检查 HTTP 状态，body(is("Hello World")) 精确比较正文。URL 只写相对路径，使请求由注入的测试服务器配置决定，而不是误指向一台硬编码的开发或生产服务器。

运行测试与阅读报告

在项目根目录使用项目自带的 Gradle Wrapper：

./gradlew test

官方指南让读者随后用浏览器打开 build/reports/tests/test/index.html。这条命令会执行项目构建逻辑，并可能下载插件或依赖；先检查来源，再在授权的开发环境中运行。本次仅静态阅读代码和构建文件，没有执行该命令，也没有生成通过报告。

还有一个容易忽略的源包细节：下载的 build.gradle 将 failOnNoDiscoveredTests 设为了 false。因此不能只看构建退出成功，就宣称这一个测试确实跑过；应在报告中确认 HelloControllerTest.testHelloEndpoint 被发现并执行，同时检查实际测试数量。源包还列出了两个 snapshots 仓库，这是依赖来源核对的一部分，不代表本次确认有快照依赖被下载。