返回指南
编辑此页面

使用旧版 REST 客户端

本指南介绍的是与 RESTEasy Classic 兼容的 REST 客户端。RESTEasy Classic 在 Quarkus 2.8 之前一直是默认的 Jakarta REST（前身为 JAX-RS）实现。

现在推荐使用 Quarkus REST（前身为 RESTEasy Reactive），它同样能够很好地支持传统的阻塞式工作负载和响应式工作负载。有关 Quarkus REST 的更多信息，请参阅 REST Client 指南，以及服务器端 REST JSON 入门指南 或更详细的 Quarkus REST 指南。

本指南将解释如何使用 RESTEasy REST 客户端，以便以极少的精力与 REST API 进行交互。

如果您需要编写服务器端 JSON REST API，还有另一份指南。

先决条件

要完成本指南，您需要

  • 大约 15 分钟

  • 一个 IDE

  • 已安装 JDK 17+ 并正确配置了 JAVA_HOME

  • Apache Maven 3.9.9

  • 如果您想使用它，可以选择 Quarkus CLI

  • 如果您想构建本机可执行文件（或者如果您使用本机容器构建，则为 Docker），可以选择安装 Mandrel 或 GraalVM 并进行适当的配置

解决方案

我们建议您按照以下章节中的说明，逐步创建应用程序。但是，您可以直接转到完整的示例。

克隆 Git 仓库：git clone https://github.com/quarkusio/quarkus-quickstarts.git，或下载 存档。

解决方案位于 resteasy-client-quickstart 目录中。

创建 Maven 项目

首先，我们需要一个新项目。使用以下命令创建一个新项目

CLI
quarkus create app org.acme:resteasy-client-quickstart \
    --extension='resteasy,resteasy-jackson,resteasy-client,resteasy-client-jackson' \
    --no-code
cd resteasy-client-quickstart

要创建 Gradle 项目，请添加 --gradle 或 --gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息，请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=resteasy-client-quickstart \
    -Dextensions='resteasy,resteasy-jackson,resteasy-client,resteasy-client-jackson' \
    -DnoCode
cd resteasy-client-quickstart

要创建 Gradle 项目，请添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

对于 Windows 用户

  • 如果使用 cmd，（不要使用反斜杠 \ 并将所有内容放在同一行上）

  • 如果使用 Powershell，请将 -D 参数括在双引号中，例如 "-DprojectArtifactId=resteasy-client-quickstart"

此命令生成一个带有 REST 端点的 Maven 项目，并导入

  • 用于 REST 服务器支持的 resteasy 和 resteasy-jackson 扩展；

  • 用于 REST 客户端支持的 resteasy-client 和 resteasy-client-jackson 扩展。

如果您已经配置了 Quarkus 项目，可以通过在项目根目录下运行以下命令，将 resteasy-client 和 resteasy-client-jackson 扩展添加到您的项目中：

CLI
quarkus extension add resteasy-client,resteasy-client-jackson
Maven
./mvnw quarkus:add-extension -Dextensions='resteasy-client,resteasy-client-jackson'
Gradle
./gradlew addExtension --extensions='resteasy-client,resteasy-client-jackson'

这会将以下内容添加到您的 pom.xml 中

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-client</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-client-jackson</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-resteasy-client")
implementation("io.quarkus:quarkus-resteasy-client-jackson")

设置模型

在本指南中，我们将演示如何使用 stage.code.quarkus.io 服务提供的 REST API 的一部分。我们的首要任务是设置模型，我们将使用一个 Extension POJO 来表示。

创建一个 src/main/java/org/acme/rest/client/Extension.java 文件并包含以下内容：

package org.acme.rest.client;

import java.util.List;

public class Extension {

    public String id;
    public String name;
    public String shortName;
    public List<String> keywords;

}

上面的模型仅包含了服务提供的部分字段，但已足够本指南的目的。

创建接口

使用 RESTEasy REST 客户端就像创建使用适当的 Jakarta REST 和 MicroProfile 注释的接口一样简单。在本例中，接口应创建在 src/main/java/org/acme/rest/client/ExtensionsService.java，并包含以下内容：

package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.annotations.jaxrs.QueryParam;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Set;

@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {

    @GET
    Set<Extension> getById(@QueryParam String id);
}

getById 方法使我们的代码能够通过 ID 从 Code Quarkus API 获取扩展。客户端将处理所有网络和编组工作，使我们的代码摆脱这些技术细节。

上面代码中注解的目的是以下几点

  • @RegisterRestClient 允许 Quarkus 知道此接口旨在作为 REST 客户端用于 CDI 注入

  • @Path、@GET 和 @QueryParam 是用于定义如何访问服务的标准 Jakarta REST 注释。

当安装了 JSON 扩展（如 quarkus-resteasy-client-jackson 或 quarkus-resteasy-client-jsonb）时，Quarkus 将默认使用 application/json 媒体类型来处理大多数返回值，除非通过 @Produces 或 @Consumes 注释显式设置了媒体类型（对于一些已知类型，如 String 和 File，它们分别默认使用 text/plain 和 application/octet-stream，存在一些例外）。

如果您不希望默认使用 JSON，可以将 quarkus.resteasy-json.default-json=false 设置为 false，默认值将变回自动协商。如果进行此设置，您需要为端点添加 @Produces(MediaType.APPLICATION_JSON) 和 @Consumes(MediaType.APPLICATION_JSON) 注释才能使用 JSON。

如果您不依赖 JSON 默认设置，强烈建议您为端点添加 @Produces 和 @Consumes 注释来精确定义预期的内容类型。这将有助于减少包含在原生可执行文件中的 Jakarta REST 提供程序（可视为转换器）的数量。

路径参数

如果 GET 请求需要路径参数，您可以利用 @PathParam("parameter-name") 注释代替（或 إضافة إلى）@QueryParam。如示例所示，可以根据需要组合路径和查询参数。

package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;
import org.jboss.resteasy.annotations.jaxrs.QueryParam;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;

@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {

    @GET
    @Path("/stream/{stream}")
    Set<Extension> getByStream(@PathParam String stream, @QueryParam("id") String id);
}

创建配置

为了确定将进行 REST 调用的基本 URL，REST 客户端使用 application.properties 中的配置。属性的名称需要遵循一定的约定，最好在以下代码中显示

# Your configuration properties
quarkus.rest-client."org.acme.rest.client.ExtensionsService".url=https://stage.code.quarkus.io/api # (1)
quarkus.rest-client."org.acme.rest.client.ExtensionsService".scope=jakarta.inject.Singleton # (2)
1 此配置意味着使用 ExtensionsService 执行的所有请求将使用 https://stage.code.quarkus.io 作为基本 URL。使用上述配置，调用 ExtensionsService 的 getById 方法并传入 io.quarkus:quarkus-resteasy-client 的值，将导致向 https://stage.code.quarkus.io/api/extensions?id=io.quarkus:quarkus-rest-client 发送 HTTP GET 请求。
2 此配置意味着 ExtensionsService 的默认作用域将是 @Singleton。支持的作用域值包括 @Singleton、@Dependent、@ApplicationScoped 和 @RequestScoped。默认作用域是 @Dependent。还可以直接在接口上定义默认作用域。

请注意，org.acme.rest.client.ExtensionsService 必须与我们在上一节创建的 ExtensionsService 接口的完全限定名称匹配。

标准的 MicroProfile Rest Client 属性表示法也可用于配置客户端。

org.acme.rest.client.ExtensionsService/mp-rest/url=https://stage.code.quarkus.io/api
org.acme.rest.client.ExtensionsService/mp-rest/scope=jakarta.inject.Singleton

如果一个属性通过 Quarkus 表示法和 MicroProfile 表示法同时指定，Quarkus 表示法具有优先权。

为了方便配置，您可以使用 @RegisterRestClient 的 configKey 属性，它允许使用一个不同于接口完全限定名称的配置根。

@RegisterRestClient(configKey="extensions-api")
public interface ExtensionsService {
    [...]
}
# Your configuration properties
quarkus.rest-client.extensions-api.url=https://stage.code.quarkus.io/api
quarkus.rest-client.extensions-api.scope=jakarta.inject.Singleton

禁用主机名验证

要为特定的 REST 客户端禁用 SSL 主机名验证，请将以下属性添加到您的配置中：

quarkus.rest-client.extensions-api.verify-host=false

此设置不应在生产环境中使用，因为它会禁用 SSL 主机名验证。

此外，您可以配置 REST 客户端以使用自定义主机名验证策略。您只需提供一个实现 javax.net.ssl.HostnameVerifier 接口的类，并将以下属性添加到您的配置中：

quarkus.rest-client.extensions-api.hostname-verifier=<full qualified custom hostname verifier class name>

Quarkus REST 客户端提供了一个嵌入式主机名验证策略来禁用主机名验证，名为 io.quarkus.restclient.NoopHostnameVerifier。

禁用 SSL 验证

要禁用所有 SSL 验证，请将以下属性添加到您的配置中：

quarkus.tls.trust-all=true

此设置不应在生产环境中使用，因为它会禁用任何类型的 SSL 验证。

创建 Jakarta REST 资源

创建 src/main/java/org/acme/rest/client/ExtensionsResource.java 文件并包含以下内容：

package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;

@Path("/extension")
public class ExtensionsResource {

    @Inject
    @RestClient
    ExtensionsService extensionsService;

    @GET
    @Path("/id/{id}")
    public Set<Extension> id(@PathParam String id) {
        return extensionsService.getById(id);
    }
}

请注意，除了标准的 CDI @Inject 注释外，我们还需要使用 MicroProfile @RestClient 注释来注入 ExtensionsService。

更新测试

我们还需要更新功能测试以反映对端点的更改。编辑 src/test/java/org/acme/rest/client/ExtensionsResourceTest.java 文件，并将 testExtensionIdEndpoint 方法的内容更改为：

package org.acme.rest.client;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.hasItem;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.greaterThan;

import org.acme.rest.client.resources.WireMockExtensionsResource;
import org.junit.jupiter.api.Test;

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
@QuarkusTestResource(WireMockExtensionsResource.class)
public class ExtensionsResourceTest {

    @Test
    public void testExtensionsIdEndpoint() {
        given()
            .when().get("/extension/id/io.quarkus:quarkus-rest-client")
            .then()
            .statusCode(200)
            .body("$.size()", is(1),
                "[0].id", is("io.quarkus:quarkus-rest-client"),
                "[0].name", is("REST Client Classic"),
                "[0].keywords.size()", greaterThan(1),
                "[0].keywords", hasItem("rest-client"));
    }
}

上面的代码使用了 REST Assured 的 json-path 功能。

重定向

HTTP 服务器可以通过发送以 "3" 开头的状态码响应和包含重定向 URL 的 HTTP 报头 "Location" 来将响应重定向到另一个位置。当 REST 客户端收到 HTTP 服务器的重定向响应时，它不会自动执行到新位置的请求。但是，您可以通过启用 "follow-redirects" 属性来启用自动重定向。

  • quarkus.rest-client.follow-redirects 用于启用所有 REST 客户端的重定向。

  • quarkus.rest-client.<client-prefix>.follow-redirects 用于启用特定 REST 客户端的重定向。

如果此属性为 true，则 REST 客户端将在收到 HTTP 服务器的重定向响应时执行新请求。

此外，我们还可以使用 "max-redirects" 属性限制重定向次数。

根据 RFC2616 规范，一个重要的注意事项是，默认情况下重定向仅会针对 GET 或 HEAD 方法发生。

异步支持

REST 客户端支持异步 REST 调用。异步支持有两种形式：您可以返回 CompletionStage 或 Uni（需要 quarkus-resteasy-client-mutiny 扩展）。让我们通过在 ExtensionsService REST 接口中添加一个 getByIdAsync 方法来实际演示。代码应如下所示：

package org.acme.rest.client;

import java.util.Set;
import java.util.concurrent.CompletionStage;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.annotations.jaxrs.QueryParam;

@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {

    @GET
    Set<Extension> getById(@QueryParam String id);

    @GET
    CompletionStage<Set<Extension>> getByIdAsync(@QueryParam String id);

}

打开 src/main/java/org/acme/rest/client/ExtensionsResource.java 文件，并更新为以下内容：

package org.acme.rest.client;

import java.util.Set;
import java.util.concurrent.CompletionStage;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;

@Path("/extension")
public class ExtensionsResource {

    @Inject
    @RestClient
    ExtensionsService extensionsService;

    @GET
    @Path("/id/{id}")
    public Set<Extension> id(@PathParam String id) {
        return extensionsService.getById(id);
    }

    @GET
    @Path("/id-async/{id}")
    public CompletionStage<Set<Extension>> idAsync(@PathParam String id) {
        return extensionsService.getByIdAsync(id);
    }

}

要测试异步方法，请在 ExtensionsResourceTest 中添加以下测试方法：

@Test
public void testExtensionIdAsyncEndpoint() {
    given()
        .when().get("/extension/id-async/io.quarkus:quarkus-rest-client")
        .then()
        .statusCode(200)
        .body("$.size()", is(1),
            "[0].id", is("io.quarkus:quarkus-rest-client"),
            "[0].name", is("REST Client Classic"),
            "[0].keywords.size()", greaterThan(1),
            "[0].keywords", hasItem("rest-client"));
}

Uni 版本非常相似。

package org.acme.rest.client;

import java.util.Set;
import java.util.concurrent.CompletionStage;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.annotations.jaxrs.QueryParam;

import io.smallrye.mutiny.Uni;

@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {

    // ...

    @GET
    Uni<Set<Extension>> getByIdAsUni(@QueryParam String id);
}

ExtensionsResource 变为：

package org.acme.rest.client;

import java.util.Set;
import java.util.concurrent.CompletionStage;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;

import io.smallrye.mutiny.Uni;

@Path("/extension")
public class ExtensionsResource {

    @Inject
    @RestClient
    ExtensionsService extensionsService;


    // ...

    @GET
    @Path("/id-uni/{id}")
    public Uni<Set<Extension>> idMutiny(@PathParam String id) {
        return extensionsService.getByIdAsUni(id);
    }
}
Mutiny

前面的代码片段使用了 Mutiny 响应式类型。如果您不熟悉 Mutiny，请查看 Mutiny - 一个直观的响应式编程库。

返回 Uni 时，每次订阅都会调用远程服务。这意味着您可以通过重新订阅 Uni 来重新发送请求，或使用 retry，如下所示：

@Inject @RestClient ExtensionsService extensionsService;

// ...

extensionsService.getByIdAsUni(id)
    .onFailure().retry().atMost(10);

如果您使用 CompletionStage，则需要调用服务的方法来重试。此差异源于 Mutiny 的惰性特性及其订阅协议。有关更多详细信息，请参阅 Mutiny 文档。

自定义头支持

MicroProfile REST 客户端允许通过使用 @RegisterClientHeaders 注释注册 ClientHeadersFactory 来修改请求头。

让我们通过在 ExtensionsService REST 接口中添加一个指向 RequestUUIDHeaderFactory 类的 @RegisterClientHeaders 注释来演示此功能：

package org.acme.rest.client;

import java.util.Set;
import java.util.concurrent.CompletionStage;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.eclipse.microprofile.rest.client.annotation.RegisterClientHeaders;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.annotations.jaxrs.QueryParam;

import io.smallrye.mutiny.Uni;

@Path("/extensions")
@RegisterRestClient
@RegisterClientHeaders(RequestUUIDHeaderFactory.class)
public interface ExtensionsService {

    @GET
    Set<Extension> getById(@QueryParam String id);

    @GET
    CompletionStage<Set<Extension>> getByIdAsync(@QueryParam String id);

    @GET
    Uni<Set<Extension>> getByIdAsUni(@QueryParam String id);
}

RequestUUIDHeaderFactory 如下所示：

package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.ext.ClientHeadersFactory;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.core.MultivaluedHashMap;
import jakarta.ws.rs.core.MultivaluedMap;
import java.util.UUID;

@ApplicationScoped
public class RequestUUIDHeaderFactory implements ClientHeadersFactory {

    @Override
    public MultivaluedMap<String, String> update(MultivaluedMap<String, String> incomingHeaders, MultivaluedMap<String, String> clientOutgoingHeaders) {
        MultivaluedMap<String, String> result = new MultivaluedHashMap<>();
        result.add("X-request-uuid", UUID.randomUUID().toString());
        return result;
    }
}

如上例所示，您可以通过用作用域定义注释（如 @Singleton、@ApplicationScoped 等）来使 ClientHeadersFactory 实现成为 CDI bean。

默认头工厂

您也可以使用不带自定义工厂的 @RegisterClientHeaders 注释。在这种情况下，将使用 DefaultClientHeadersFactoryImpl 工厂，并且 org.eclipse.microprofile.rest.client.propagateHeaders 配置属性中列出的所有头都将被添加。单个头名称是逗号分隔的。

@Path("/extensions")
@RegisterRestClient
@RegisterClientHeaders
public interface ExtensionsService {

    @GET
    Set<Extension> getById(@QueryParam String id);

    @GET
    CompletionStage<Set<Extension>> getByIdAsync(@QueryParam String id);

    @GET
    Uni<Set<Extension>> getByIdAsUni(@QueryParam String id);
}
org.eclipse.microprofile.rest.client.propagateHeaders=Authorization,Proxy-Authorization

打包并运行应用程序

使用以下命令运行应用程序

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

在浏览器中打开 https://:8080/extension/id/io.quarkus:quarkus-rest-client。

您应该会看到一个 JSON 对象，其中包含有关 REST Client 扩展的一些基本信息。

与往常一样，可以使用以下命令打包应用程序

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

并使用 java -jar target/quarkus-app/quarkus-run.jar 执行。

您还可以使用以下命令生成原生可执行文件

CLI
quarkus build --native
Maven
./mvnw install -Dnative
Gradle
./gradlew build -Dquarkus.native.enabled=true

REST Client 和 RESTEasy 交互

在 Quarkus 中，REST Client 扩展和 RESTEasy 扩展 共享相同的底层基础设施。这一考虑的一个重要结果是它们共享相同的提供程序列表（在 Jakarta REST 的术语中）。

例如，如果您声明了一个 WriterInterceptor，它默认会拦截服务器调用和客户端调用，这可能不是期望的行为。

但是，您可以通过添加 @ConstrainedTo(RuntimeType.CLIENT) 注释到提供程序来更改此默认行为并限制提供程序：

  • 仅考虑客户端调用，方法是向您的提供程序添加 @ConstrainedTo(RuntimeType.CLIENT) 注释；

  • 仅考虑服务器调用，方法是向您的提供程序添加 @ConstrainedTo(RuntimeType.SERVER) 注释。

为测试使用模拟 HTTP 服务器

在某些情况下，您可能希望模拟远程端点（HTTP 服务器），而不是模拟客户端本身。这对于原生测试或以编程方式创建的客户端尤其有用。

您可以使用 Wiremock 轻松模拟 HTTP 服务器。Quarkus - 使用 REST Client 的 Wiremock 部分 详细描述了如何进行设置。

进一步阅读

配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

quarkus.rest-client.removes-trailing-slash

如果为 true，则扩展将自动删除路径中任何尾部的斜杠。 此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_REMOVES_TRAILING_SLASH

显示更多

布尔值

true

quarkus.rest-client.multipart-post-encoder-mode

表单数据编码的模式。可能的值为 HTML5、RFC1738 和 RFC3986。模式在 Netty 文档 中有描述。

默认情况下，Rest Client Reactive 使用 RFC1738。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_MULTIPART_POST_ENCODER_MODE

显示更多

字符串

quarkus.rest-client.proxy-address

一个字符串值，格式为 :，用于指定客户端要使用的 HTTP 代理服务器主机名（或 IP 地址）和端口。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_PROXY_ADDRESS

显示更多

字符串

quarkus.rest-client.proxy-user

代理用户名，等效于 http.proxy 或 https.proxy JVM 设置。

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_PROXY_USER

显示更多

字符串

quarkus.rest-client.proxy-password

代理密码，等效于 http.proxyPassword 或 https.proxyPassword JVM 设置。

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_PROXY_PASSWORD

显示更多

字符串

quarkus.rest-client.non-proxy-hosts

要访问而不使用代理的主机，类似于 http.nonProxyHosts 或 https.nonProxyHosts JVM 设置。 请注意，与 JVM 设置不同，此属性默认情况下为空。

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_NON_PROXY_HOSTS

显示更多

字符串

quarkus.rest-client.connect-timeout

REST 客户端应等待连接到远程端点的超时时间（以毫秒为单位）。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_CONNECT_TIMEOUT

显示更多

long

15000

quarkus.rest-client.read-timeout

REST 客户端应等待来自远程端点响应的超时时间（以毫秒为单位）。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_READ_TIMEOUT

显示更多

long

30000

quarkus.rest-client.disable-contextual-error-messages

如果为 true，则在客户端调用期间发生异常时，REST 客户端将不会提供额外的上下文信息（例如 REST 客户端类和方法名称）。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_DISABLE_CONTEXTUAL_ERROR_MESSAGES

显示更多

布尔值

false

quarkus.rest-client.user-agent

用于所有 REST 客户端的 HTTP user-agent 标头的默认配置。

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_USER_AGENT

显示更多

字符串

quarkus.rest-client.headers."header-name"

应应用于 rest 客户端所有请求的 HTTP 标头。

环境变量：QUARKUS_REST_CLIENT_HEADERS__HEADER_NAME_

显示更多

Map<String,String>

quarkus.rest-client.hostname-verifier

主机名验证器的类名。 该类必须具有一个公共的无参数构造函数。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_HOSTNAME_VERIFIER

显示更多

字符串

quarkus.rest-client.connection-ttl

连接在连接池中保持未使用状态的时间（以毫秒为单位），然后被驱逐和关闭。 超时 0 表示没有超时。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_CONNECTION_TTL

显示更多

整数

quarkus.rest-client.connection-pool-size

此客户端的连接池的大小。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_CONNECTION_POOL_SIZE

显示更多

整数

50

quarkus.rest-client.keep-alive-enabled

如果设置为 false，则完全禁用 keep alive。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_KEEP_ALIVE_ENABLED

显示更多

布尔值

true

quarkus.rest-client.max-redirects

请求可以遵循的最大重定向次数。

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_MAX_REDIRECTS

显示更多

整数

quarkus.rest-client.follow-redirects

一个布尔值，用于确定客户端是否应遵循 HTTP 重定向响应。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_FOLLOW_REDIRECTS

显示更多

布尔值

quarkus.rest-client.providers

要包含在客户端中的完全限定的提供程序类名。 等效于 @RegisterProvider 注释。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_PROVIDERS

显示更多

字符串

quarkus.rest-client.scope

用于注入 REST 客户端实例的 CDI 范围。 值可以是 CDI 范围注释的完全限定类名（例如“jakarta.enterprise.context.ApplicationScoped”）或其简单名称（例如“ApplicationScoped”）。

rest-client 扩展的默认范围是“Dependent”（这是符合规范的行为）。

rest-client-reactive 扩展的默认范围是“ApplicationScoped”。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_SCOPE

显示更多

字符串

quarkus.rest-client.query-param-style

一个枚举类型字符串值，可能的值为“MULTI_PAIRS”（默认）、“COMMA_SEPARATED”或“ARRAY_PAIRS”，用于指定使用相同查询参数的多个值的格式。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_QUERY_PARAM_STYLE

显示更多

multi-pairs, comma-separated, array-pairs

quarkus.rest-client.verify-host

设置是否启用主机名验证。 默认已启用。 不应在生产环境中禁用此设置，因为它会使客户端容易受到 MITM 攻击。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_VERIFY_HOST

显示更多

布尔值

quarkus.rest-client.trust-store

信任存储位置。 可以指向类路径资源或文件。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_TRUST_STORE

显示更多

字符串

quarkus.rest-client.trust-store-password

信任存储密码。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_TRUST_STORE_PASSWORD

显示更多

字符串

quarkus.rest-client.trust-store-type

信任存储的类型。 默认为“JKS”。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_TRUST_STORE_TYPE

显示更多

字符串

quarkus.rest-client.key-store

密钥存储位置。 可以指向类路径资源或文件。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_KEY_STORE

显示更多

字符串

quarkus.rest-client.key-store-password

密钥存储密码。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_KEY_STORE_PASSWORD

显示更多

字符串

quarkus.rest-client.key-store-type

密钥存储的类型。 默认为“JKS”。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_KEY_STORE_TYPE

显示更多

字符串

quarkus.rest-client.tls-configuration-name

要使用的 TLS 配置的名称。

如果配置了名称，则它使用来自 quarkus.tls.<name>.* 的配置 如果配置了名称，但未找到具有该名称的 TLS 配置，则会抛出错误。 默认的 TLS 配置将被忽略。

如果未设置命名的 TLS 配置，则将使用 key-store、trust-store 等属性。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_TLS_CONFIGURATION_NAME

显示更多

字符串

quarkus.rest-client.http2

如果为 true，则将启用 HTTP/2。

环境变量：QUARKUS_REST_CLIENT_HTTP2

显示更多

布尔值

false

quarkus.rest-client.http2-upgrade-max-content-length

配置 HTTP/2 升级聚合内容的最大长度（以字节为单位）。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_HTTP2_UPGRADE_MAX_CONTENT_LENGTH

显示更多

MemorySize 

64K

quarkus.rest-client.max-chunk-size

配置两件不同的事情

  • 最大 HTTP 块大小，最多 Integer.MAX_VALUE 个字节。

  • 使用 InputStream 作为输入时要读取的块的大小

可以被特定于客户端的设置覆盖。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT_MAX_CHUNK_SIZE

显示更多

MemorySize 

8k

quarkus.rest-client.enable-compression

支持接收 GZIP 压缩的消息。启用此功能后，如果服务器返回的响应包含 Content-Encoding: gzip 报头，REST Client 将自动解码内容并继续处理消息。

此属性不适用于 RESTEasy Client。

可以被特定于客户端的设置覆盖。

环境变量：QUARKUS_REST_CLIENT_ENABLE_COMPRESSION

显示更多

布尔值

quarkus.rest-client.alpn

如果启用了应用层协议协商，客户端将在服务器公开的协议之上协商要使用的协议。默认情况下，它将首先尝试使用 HTTP/2，如果不可用，则使用 HTTP/1.1。当 http2 属性启用时，此标志将自动启用。

环境变量：QUARKUS_REST_CLIENT_ALPN

显示更多

布尔值

quarkus.rest-client.capture-stacktrace

如果为 true，则会捕获 REST Client 方法调用的堆栈跟踪。 如果调用引发异常，则将使用此堆栈跟踪

环境变量：QUARKUS_REST_CLIENT_CAPTURE_STACKTRACE

显示更多

布尔值

false

quarkus.rest-client.logging.scope

客户端的日志记录范围。
警告：注意记录敏感数据
可能的值为

  • request-response - 启用记录请求和响应，包括重定向响应

  • all - 启用记录请求和响应以及较低级别的日志记录

  • none - 无其他日志记录

此属性仅适用于响应式 REST 客户端。

环境变量：QUARKUS_REST_CLIENT_LOGGING_SCOPE

显示更多

字符串

quarkus.rest-client.logging.body-limit

应记录正文的多少个字符。 消息正文可能很大，并且很容易污染日志。

默认情况下，设置为 100。

此属性仅适用于响应式 REST 客户端。

环境变量：QUARKUS_REST_CLIENT_LOGGING_BODY_LIMIT

显示更多

整数

100

quarkus.rest-client."clients".scope

用于注入的 CDI 作用域。此属性可以包含 CDI 作用域注释的完全限定类名（例如 "jakarta.enterprise.context.ApplicationScoped"）或其简单名称（例如 "ApplicationScoped"）。默认情况下，此属性未设置，这意味着除非接口被 RegisterRestClient 注释，否则它不会被注册为 bean。如果一个接口没有被 RegisterRestClient 注释，并且此属性被设置，那么 Quarkus 将使该接口成为已配置作用域的 bean。

环境变量：QUARKUS_REST_CLIENT__CLIENTS__SCOPE

显示更多

字符串

quarkus.rest-client."clients".enable-local-proxy

如果设置为 true，则 Quarkus 将确保来自 REST 客户端的所有调用都通过本地代理服务器（由 Quarkus 管理）。 这对于捕获到使用 HTTPS 服务的网络流量非常有用。

此属性不适用于 RESTEasy Client，仅适用于 Quarkus REST 客户端（以前的 RESTEasy Reactive 客户端）。

此属性仅适用于开发和测试模式。

环境变量：QUARKUS_REST_CLIENT__CLIENTS__ENABLE_LOCAL_PROXY

显示更多

布尔值

false

quarkus.rest-client."clients".local-proxy-provider

如果存在多个代理提供程序，则使用此设置来选择要使用的代理提供程序。 它仅在 enable-local-proxy 为 true 时适用。

在多个提供程序之间进行选择的算法如下

  • 如果只有默认提供程序，则使用它（其名称为 default）

  • 如果除了默认提供程序之外只有一个，则使用它

  • 如果有多个，则失败

环境变量：QUARKUS_REST_CLIENT__CLIENTS__LOCAL_PROXY_PROVIDER

显示更多

字符串

quarkus.rest-client."clients".removes-trailing-slash

如果为 true，则扩展将自动删除路径中任何尾部的斜杠。 此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENTS__REMOVES_TRAILING_SLASH

显示更多

布尔值

true

quarkus.rest-client."client".url

用于此服务的基本 URL。 除非在 @RegisterRestClient 注释中配置了 baseUri 属性，否则此属性或 uri 属性被认为是必需的。

环境变量：QUARKUS_REST_CLIENT__CLIENT__URL

显示更多

字符串

quarkus.rest-client."client".uri

用于此服务的基本 URI。 除非在 @RegisterRestClient 注释中配置了 baseUri 属性，否则此属性或 url 属性被认为是必需的。

环境变量：QUARKUS_REST_CLIENT__CLIENT__URI

显示更多

字符串

quarkus.rest-client."client".override-uri

此属性仅用于高级配置设置，以覆盖为 uri 或 url 设置的任何值。 覆盖是使用 REST Client 类名配置语法完成的。

此属性不适用于 RESTEasy Client，仅适用于 Quarkus Rest 客户端（以前的 RESTEasy Reactive 客户端）。

环境变量：QUARKUS_REST_CLIENT__CLIENT__OVERRIDE_URI

显示更多

字符串

quarkus.rest-client."client".providers

Map，其中键是要包含在客户端中的完全限定的提供程序类名，值是它们的整数优先级。 等效于 @RegisterProvider 注释。

环境变量：QUARKUS_REST_CLIENT__CLIENT__PROVIDERS

显示更多

字符串

quarkus.rest-client."client".connect-timeout

等待连接到远程端点的超时时间（以毫秒为单位）。

环境变量：QUARKUS_REST_CLIENT__CLIENT__CONNECT_TIMEOUT

显示更多

long

quarkus.rest-client."client".read-timeout

等待来自远程端点响应的超时时间（以毫秒为单位）。

环境变量：QUARKUS_REST_CLIENT__CLIENT__READ_TIMEOUT

显示更多

long

quarkus.rest-client."client".follow-redirects

一个布尔值，用于确定客户端是否应遵循 HTTP 重定向响应。

环境变量：QUARKUS_REST_CLIENT__CLIENT__FOLLOW_REDIRECTS

显示更多

布尔值

quarkus.rest-client."client".multipart-post-encoder-mode

表单数据编码的模式。可能的值为 HTML5、RFC1738 和 RFC3986。模式在 Netty 文档 中有描述。

默认情况下，Rest Client Reactive 使用 RFC1738。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__MULTIPART_POST_ENCODER_MODE

显示更多

字符串

quarkus.rest-client."client".proxy-address

一个字符串值，格式为 :，用于指定此客户端要使用的 HTTP 代理服务器主机名（或 IP 地址）和端口。

使用 none 禁用代理

环境变量：QUARKUS_REST_CLIENT__CLIENT__PROXY_ADDRESS

显示更多

字符串

quarkus.rest-client."client".proxy-user

代理用户名。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__PROXY_USER

显示更多

字符串

quarkus.rest-client."client".proxy-password

代理密码。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__PROXY_PASSWORD

显示更多

字符串

quarkus.rest-client."client".non-proxy-hosts

要访问而不使用代理的主机

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__NON_PROXY_HOSTS

显示更多

字符串

quarkus.rest-client."client".query-param-style

一个枚举类型字符串值，可能的值为“MULTI_PAIRS”（默认）、“COMMA_SEPARATED”或“ARRAY_PAIRS”，用于指定使用相同查询参数的多个值的格式。

环境变量：QUARKUS_REST_CLIENT__CLIENT__QUERY_PARAM_STYLE

显示更多

multi-pairs, comma-separated, array-pairs

quarkus.rest-client."client".verify-host

设置是否启用主机名验证。 默认已启用。 不应在生产环境中禁用此设置，因为它会使客户端容易受到 MITM 攻击。

环境变量：QUARKUS_REST_CLIENT__CLIENT__VERIFY_HOST

显示更多

布尔值

quarkus.rest-client."client".trust-store

信任存储位置。 可以指向类路径资源或文件。

环境变量：QUARKUS_REST_CLIENT__CLIENT__TRUST_STORE

显示更多

字符串

quarkus.rest-client."client".trust-store-password

信任存储密码。

环境变量：QUARKUS_REST_CLIENT__CLIENT__TRUST_STORE_PASSWORD

显示更多

字符串

quarkus.rest-client."client".trust-store-type

信任存储的类型。 默认为“JKS”。

环境变量：QUARKUS_REST_CLIENT__CLIENT__TRUST_STORE_TYPE

显示更多

字符串

quarkus.rest-client."client".key-store

密钥存储位置。 可以指向类路径资源或文件。

环境变量：QUARKUS_REST_CLIENT__CLIENT__KEY_STORE

显示更多

字符串

quarkus.rest-client."client".key-store-password

密钥存储密码。

环境变量：QUARKUS_REST_CLIENT__CLIENT__KEY_STORE_PASSWORD

显示更多

字符串

quarkus.rest-client."client".key-store-type

密钥存储的类型。 默认为“JKS”。

环境变量：QUARKUS_REST_CLIENT__CLIENT__KEY_STORE_TYPE

显示更多

字符串

quarkus.rest-client."client".hostname-verifier

主机名验证器的类名。 该类必须具有一个公共的无参数构造函数。

环境变量：QUARKUS_REST_CLIENT__CLIENT__HOSTNAME_VERIFIER

显示更多

字符串

quarkus.rest-client."client".tls-configuration-name

要使用的 TLS 配置的名称。

如果配置了名称，则它使用来自 quarkus.tls.<name>.* 的配置 如果配置了名称，但未找到具有该名称的 TLS 配置，则会抛出错误。 默认的 TLS 配置将被忽略。

如果未设置命名的 TLS 配置，则将使用 key-store、trust-store 等属性。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__TLS_CONFIGURATION_NAME

显示更多

字符串

quarkus.rest-client."client".connection-ttl

连接在连接池中保持未使用状态的时间（以毫秒为单位），然后被驱逐和关闭。 超时 0 表示没有超时。

环境变量：QUARKUS_REST_CLIENT__CLIENT__CONNECTION_TTL

显示更多

整数

quarkus.rest-client."client".connection-pool-size

此客户端的连接池的大小。

环境变量：QUARKUS_REST_CLIENT__CLIENT__CONNECTION_POOL_SIZE

显示更多

整数

50

quarkus.rest-client."client".keep-alive-enabled

如果设置为 false，则完全禁用 keep alive。

环境变量：QUARKUS_REST_CLIENT__CLIENT__KEEP_ALIVE_ENABLED

显示更多

布尔值

quarkus.rest-client."client".max-redirects

请求可以遵循的最大重定向次数。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__MAX_REDIRECTS

显示更多

整数

quarkus.rest-client."client".headers."header-name"

应应用于 rest 客户端所有请求的 HTTP 标头。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__HEADERS__HEADER_NAME_

显示更多

Map<String,String>

quarkus.rest-client."client".shared

设置为 true 以在 REST 客户端之间共享 HTTP 客户端。可以有多个共享客户端，通过名称来区分，当没有设置特定名称时，使用名称 __vertx.DEFAULT。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__SHARED

显示更多

布尔值

quarkus.rest-client."client".name

设置 HTTP 客户端名称，当客户端被共享时使用，否则忽略。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__NAME

显示更多

字符串

quarkus.rest-client."client".user-agent

配置要使用的 HTTP user-agent 标头。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__USER_AGENT

显示更多

字符串

quarkus.rest-client."client".http2

如果为 true，则将启用 HTTP/2。

环境变量：QUARKUS_REST_CLIENT__CLIENT__HTTP2

显示更多

布尔值

quarkus.rest-client."client".http2-upgrade-max-content-length

配置 HTTP/2 升级聚合内容的最大长度（以字节为单位）。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__HTTP2_UPGRADE_MAX_CONTENT_LENGTH

显示更多

MemorySize 

64K

quarkus.rest-client."client".max-chunk-size

配置两件不同的事情

  • 最大 HTTP 块大小，最多 Integer.MAX_VALUE 个字节。

  • 读取 InputStream 并发送到服务器时要读取的块的大小

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__MAX_CHUNK_SIZE

显示更多

MemorySize 

8K

quarkus.rest-client."client".enable-compression

支持接收 GZIP 压缩的消息。启用此功能后，如果服务器返回的响应包含 Content-Encoding: gzip 报头，REST Client 将自动解码内容并继续处理消息。

此属性不适用于 RESTEasy Client。

环境变量：QUARKUS_REST_CLIENT__CLIENT__ENABLE_COMPRESSION

显示更多

布尔值

quarkus.rest-client."client".alpn

如果启用了应用层协议协商，客户端将在服务器公开的协议之上协商要使用的协议。默认情况下，它将首先尝试使用 HTTP/2，如果不可用，则使用 HTTP/1.1。当 http2 属性启用时，此标志将自动启用。

环境变量：QUARKUS_REST_CLIENT__CLIENT__ALPN

显示更多

布尔值

quarkus.rest-client."client".capture-stacktrace

如果为 true，则会捕获 REST Client 方法调用的堆栈跟踪。 如果调用引发异常，则将使用此堆栈跟踪

环境变量：QUARKUS_REST_CLIENT__CLIENT__CAPTURE_STACKTRACE

显示更多

布尔值

quarkus.rest-client."client".disable-default-mapper

如果设置为 true，则此 REST 客户端将不会使用默认异常映射器，如果 HTTP 响应代码 >= 400，该映射器始终抛出异常。此属性不适用于 RESTEasy 客户端。

环境变量：QUARKUS_REST_CLIENT__CLIENT__DISABLE_DEFAULT_MAPPER

显示更多

布尔值

${microprofile.rest.client.disable.default.mapper:false}

quarkus.rest-client."client".logging.scope

客户端的日志记录范围。
警告：注意记录敏感数据
可能的值为

  • request-response - 启用记录请求和响应，包括重定向响应

  • all - 启用记录请求和响应以及较低级别的日志记录

  • none - 无其他日志记录

此属性仅适用于响应式 REST 客户端。

环境变量：QUARKUS_REST_CLIENT__CLIENT__LOGGING_SCOPE

显示更多

字符串

quarkus.rest-client."client".logging.body-limit

应记录正文的多少个字符。 消息正文可能很大，并且很容易污染日志。

默认情况下，设置为 100。

此属性仅适用于响应式 REST 客户端。

环境变量：QUARKUS_REST_CLIENT__CLIENT__LOGGING_BODY_LIMIT

显示更多

整数

100
关于 MemorySize 格式

大小配置选项识别以下格式的字符串（显示为正则表达式）：[0-9]+[KkMmGgTtPpEeZzYy]?。

如果未给出后缀，则假定为字节。

相关内容

在相同的扩展上

关于相同主题

Quarkus 是开放的。本项目的所有依赖项均可在 Apache Software License 2.0 或兼容许可证下获取。 CC by 3.0

本网站由 Jekyll 构建，托管在 GitHub Pages 上，并且完全开源。如果您想改进它，请 fork 本网站 并向我们展示您的成果。

导航
关注我们
获取帮助
语言
Quarkus 由社区项目组成
版权所有 © Quarkus。保留所有权利。有关我们的商标的详细信息，请访问我们的 商标政策 和 商标列表。第三方商标属于其各自的持有人，此处提及不代表任何认可或关联。