Usando o Cliente REST
Este guia explica como usar o Cliente REST Reativo para interagir com as APIs REST. O Cliente REST Reativo é a implementação do Cliente REST compatível com o RESTEasy Reativo.
Se o seu aplicativo usa um cliente e expõe endpoints REST, use o RESTEasy Reativo para a parte do servidor.
Pré-requisitos
Para concluir este guia, você precisa:
-
Cerca de 15 minutos
-
Um IDE
-
JDK 17+ instalado com
JAVA_HOMEconfigurado corretamente -
Apache Maven 3.9.6
-
Opcionalmente, o Quarkus CLI se você quiser usá-lo
-
Opcionalmente, Mandrel ou GraalVM instalado e configurado apropriadamente se você quiser criar um executável nativo (ou Docker se você usar uma compilação de contêiner nativo)
Solução
Recomendamos que siga as instruções nas seções seguintes e crie a aplicação passo a passo. No entanto, você pode ir diretamente para o exemplo completo.
Clone o repositório Git: git clone -b 3.8 https://github.com/quarkusio/quarkus-quickstarts.git, ou baixe um arquivo.
A solução está localizada no diretório rest-client-reactive-quickstart.
Criar o projeto Maven
Primeiro, precisamos de um novo projeto. Crie um novo projeto com o seguinte comando:
Para usuários do Windows:
-
Se estiver usando cmd, (não use barra invertida '\' e coloque tudo na mesma linha)
-
Se estiver usando o Powershell, envolva os parâmetros '-D' entre aspas duplas, por exemplo, '"-DprojectArtifactId=rest-client-reactive-quickstart"'
Este comando gera o projeto Maven com um endpoint REST e com importações:
-
a extensão
resteasy-reactive-jacksonpara o suporte do servidor REST. Useresteasy-reactiveem vez disso se não pretender utilizar Jackson; -
a extensão
rest-client-reactive-jacksonpara o suporte do cliente REST. Userest-client-reactiveem vez disso se não pretender utilizar Jackson
Se já tiver o projeto Quarkus configurado, você pode adicionar a extensão rest-client-reactive-jackson ao projeto executando o seguinte comando no diretório base do projeto:
quarkus extension add rest-client-reactive-jackson./mvnw quarkus:add-extension -Dextensions='rest-client-reactive-jackson'./gradlew addExtension --extensions='rest-client-reactive-jackson'Isto irá adicionar o seguinte trecho no seu arquivo de build:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-client-reactive-jackson</artifactId>
</dependency>implementation("io.quarkus:quarkus-rest-client-reactive-jackson")Configurando o modelo
Neste guia, demonstraremos como consumir parte da API REST fornecida pelo serviço stage.code.quarkus.io . Nosso primeiro passo é configurar o modelo que usaremos, na forma de um POJO Extension .
Crie um arquivo src/main/java/org/acme/rest/client/Extension.java e defina o seguinte conteúdo:
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;
}O modelo acima é apenas um subconjunto dos campos fornecidos pelo serviço, mas é suficiente para os objetivos deste guia.
Crie a interface
Usar o Cliente REST Reativo é tão simples quanto criar uma interface usando as anotações Jakarta REST e MicroProfile adequadas. No nosso caso, a interface deve ser criada em src/main/java/org/acme/rest/client/ExtensionsService.java e ter o seguinte conteúdo:
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
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("id") String id);
}O método getById dá ao nosso código a capacidade de obter uma extensão por id a partir da API do Code Quarkus. O cliente tratará de toda a ligação em rede e da organização, deixando o nosso código livre desses pormenores técnicos.
O objetivo das anotações no código acima é o seguinte:
-
@RegisterRestClientpermite que o Quarkus saiba que essa interface deve estar disponível para injeção de CDI como um Cliente REST -
@Path,@GETe@QueryParamsão as anotações Jakarta REST padrão utilizadas para definir o modo de acesso ao serviço
|
Quando a extensão Se você não conta com JSON padrão, é altamente recomendável anotar seus endpoints com as anotações |
|
The |
Parâmetros de Consulta
A maneira mais fácil de especificar um parâmetro de consulta é anotar um parâmetro de método do cliente com @QueryParam ou @RestQuery . O @RestQuery é equivalente ao @QueryParam , mas com nome opcional. Além disso, ele também pode ser usado para passar parâmetros de consulta como Map , o que é conveniente se os parâmetros não forem conhecidos antecipadamente.
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.reactive.RestQuery;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MultivaluedMap;
import java.util.Map;
import java.util.Set;
@Path("/extensions")
@RegisterRestClient(configKey = "extensions-api")
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") Integer id);
@GET
Set<Extension> getByName(@RestQuery String name); (1)
@GET
Set<Extension> getByFilter(@RestQuery Map<String, String> filter); (2)
@GET
Set<Extension> getByFilters(@RestQuery MultivaluedMap<String, String> filters); (3)
}| 1 | A consulta da requisição incluirá um parâmetro com a chave name |
| 2 | Cada entrada Map representa exatamente um parâmetro de consulta |
| 3 | MultivaluedMap permite enviar valores de vetor |
Usando @ClientQueryParam
Outra forma de adicionar parâmetros de consulta a uma requisição é usar @io.quarkus.rest.client.reactive.ClientQueryParam na interface do cliente REST ou em um método específico da interface. A anotação pode especificar o nome do parâmetro de consulta, enquanto o valor pode ser uma constante, uma propriedade de configuração ou pode ser determinado pela chamada de um método.
O exemplo a seguir mostra as várias utilizações possíveis:
@ClientQueryParam(name = "my-param", value = "${my.property-value}") (1)
public interface Client {
@GET
String getWithParam();
@GET
@ClientQueryParam(name = "some-other-param", value = "other") (2)
String getWithOtherParam();
@GET
@ClientQueryParam(name = "param-from-method", value = "{with-param}") (3)
String getFromMethod();
default String withParam(String name) {
if ("param-from-method".equals(name)) {
return "test";
}
throw new IllegalArgumentException();
}
}| 1 | Ao colocar @ClientQueryParam na interface, garantimos que my-param será adicionado a todas as requisições do cliente. Como usamos a sintaxe ${…}, o valor real do parâmetro será obtido usando a propriedade de configuração my.property-value . |
| 2 | Quando getWithOtherParam é chamado, além do parâmetro de consulta my-param, some-other-param com o valor de other também será adicionado. |
| 3 | quando getFromMethod é chamado, além do parâmetro de consulta my-param, param-from-method com o valor de test (porque é isso que o método withParam devolve quando invocado com param-from-method) também será adicionado. |
|
Observe que, se um método de interface contiver um argumento anotado com |
Mais informações sobre esta anotação podem ser encontradas no javadoc do @ClientQueryParam.
Parâmetros do Formulário
Os parâmetros do formulário podem ser especificados utilizando as anotações @RestForm (ou @FormParam):
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.reactive.RestForm;
import jakarta.ws.rs.PORT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.FormParam;
import jakarta.ws.rs.core.MultivaluedMap;
import java.util.Map;
import java.util.Set;
@Path("/extensions")
@RegisterRestClient(configKey = "extensions-api")
public interface ExtensionsService {
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
Set<Extension> postId(@FormParam("id") Integer id);
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
Set<Extension> postName(@RestForm String name);
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
Set<Extension> postFilter(@RestForm Map<String, String> filter);
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
Set<Extension> postFilters(@RestForm MultivaluedMap<String, String> filters);
}Usando @ClientFormParam
Os parâmetros do formulário também podem ser especificados utilizando @ClientFormParam, semelhante a @ClientQueryParam:
@ClientFormParam(name = "my-param", value = "${my.property-value}")
public interface Client {
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
String postWithParam();
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@ClientFormParam(name = "some-other-param", value = "other")
String postWithOtherParam();
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@ClientFormParam(name = "param-from-method", value = "{with-param}")
String postFromMethod();
default String withParam(String name) {
if ("param-from-method".equals(name)) {
return "test";
}
throw new IllegalArgumentException();
}
}Mais informações sobre esta anotação podem ser encontradas no javadoc do @ClientFormParam.
Parâmetros do Caminho
Se a requisição GET exigir parâmetros de caminho, você poderá utilizar a anotação @PathParam("parameter-name") em vez de (ou além de) @QueryParam . Os parâmetros de caminho e de consulta podem ser combinados, conforme necessário, como ilustrado no exemplo abaixo.
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.QueryParam;
import java.util.Set;
@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {
@GET
@Path("/stream/{stream}")
Set<Extension> getByStream(@PathParam("stream") String stream, @QueryParam("id") String id);
}Using ClientMultipartForm
MultipartForm can be built using the Class ClientMultipartForm which supports building the form as needed:
ClientMultipartForm can be programmatically created with custom inputs and/or from MultipartFormDataInput and/or from custom Resteasy Reactive Input annotated with @RestForm if received.
public interface MultipartService {
@POST
@Path("/multipart")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.APPLICATION_JSON)
Map<String, String> multipart(ClientMultipartForm dataParts); (1)
}| 1 | input to the method is a custom Generic ClientMultipartForm which matches external application api contract. |
More information about this Class and supported methods can be found on the javadoc of ClientMultipartForm.
Build ClientMultipartForm from MultipartFormDataInput programmatically
public ClientMultipartForm buildClientMultipartForm(MultipartFormDataInput inputForm) (1)
throws IOException {
ClientMultipartForm multiPartForm = ClientMultipartForm.create(); (2)
for (Entry<String, Collection<FormValue>> attribute : inputForm.getValues().entrySet()) {
for (FormValue fv : attribute.getValue()) {
if (fv.isFileItem()) {
final FileItem fi = fv.getFileItem();
String mediaType = Objects.toString(fv.getHeaders().getFirst(HttpHeaders.CONTENT_TYPE),
MediaType.APPLICATION_OCTET_STREAM);
if (fi.isInMemory()) {
multiPartForm.binaryFileUpload(attribute.getKey(), fv.getFileName(),
Buffer.buffer(IOUtils.toByteArray(fi.getInputStream())), mediaType); (3)
} else {
multiPartForm.binaryFileUpload(attribute.getKey(), fv.getFileName(),
fi.getFile().toString(), mediaType); (4)
}
} else {
multiPartForm.attribute(attribute.getKey(), fv.getValue(), fv.getFileName()); (5)
}
}
}
return multiPartForm;
}| 1 | MultipartFormDataInput inputForm supported by RestEasy Reactive (Server). |
| 2 | Creating a ClientMultipartForm object to populate with various dataparts. |
| 3 | Adding InMemory FileItem to ClientMultipartForm |
| 4 | Adding physical FileItem to ClientMultipartForm |
| 5 | Adding any attribute directly to ClientMultipartForm if not FileItem. |
Build ClientMultipartForm from custom Attributes annotated with @RestForm
public class MultiPartPayloadFormData { (1)
@RestForm("files")
@PartType(MediaType.APPLICATION_OCTET_STREAM)
List<FileUpload> files;
@RestForm("jsonPayload")
@PartType(MediaType.TEXT_PLAIN)
String jsonPayload;
}
/*
* Generate ClientMultipartForm from custom attributes annotated with @RestForm
*/
public ClientMultipartForm buildClientMultipartForm(MultiPartPayloadFormData inputForm) { (1)
ClientMultipartForm multiPartForm = ClientMultipartForm.create();
multiPartForm.attribute("jsonPayload", inputForm.getJsonPayload(), "jsonPayload"); (2)
inputForm.getFiles().forEach(fu -> {
multiPartForm.binaryFileUpload("file", fu.name(), fu.filePath().toString(), fu.contentType()); (3)
});
return multiPartForm;
}| 1 | MultiPartPayloadFormData custom Object created to match the API contract for calling service which needs to be converted to ClientMultipartForm |
| 2 | Adding attribute jsonPayload directly to ClientMultipartForm |
| 3 | Adding FileUpload objects to ClientMultipartForm as binaryFileUpload with contentType. |
|
When sending multipart data that uses the same name, problems can arise if the client and server do not use the same multipart encoder mode.
By default, the REST Client uses This configuration can be achieved via the |
Crie a configuração
Para determinar o URL de base para o qual as chamadas REST serão feitas, o Cliente REST usa a configuração de application.properties. O nome da propriedade precisa seguir uma determinada convenção que é melhor exibida no código a seguir:
# Your configuration properties
quarkus.rest-client."org.acme.rest.client.ExtensionsService".url=https://stage.code.quarkus.io/api # (1)| 1 | Essa configuração significa que todas as requisições realizadas usando org.acme.rest.client.ExtensionsService usarão o https://stage.code.quarkus.io/api como URL base. Usando a configuração acima, chamar o método getById de ExtensionsService com um valor de io.quarkus:quarkus-rest-client-reactive resultaria em uma requisição HTTP GET feita para https://stage.code.quarkus.io/api/extensions?id=io.quarkus:quarkus-rest-client-reactive. |
Note que org.acme.rest.client.ExtensionsService deve corresponder ao nome totalmente qualificado da interface ExtensionsService que criamos na seção anterior.
Para facilitar a configuração, você pode utilizar a propriedade configKey de @RegisterRestClient que permite utilizar uma raiz de configuração diferente do nome totalmente qualificado da sua interface.
@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.SingletonDesabilitando a Verificação do Nome do Host
Para desabilitar a verificação do nome do host SSL para um cliente REST específico, adicione a seguinte propriedade à sua configuração:
quarkus.rest-client.extensions-api.verify-host=false|
Esta definição não deve ser utilizada em produção, uma vez que irá desativar a verificação do nome do host SSL. |
Suporte HTTP/2
O HTTP/2 está desabilitado por padrão no Cliente REST. Se pretende habilitar, pode definir:
// for all REST Clients:
quarkus.rest-client.http2=true
// or for a single REST Client:
quarkus.rest-client.extensions-api.http2=trueAlternativamente, você pode habilitar a extensão TLS de Negociação de Protocolo de Camada de Aplicação (alpn) e o cliente irá determinar qual versão HTTP utilizar, dentre as que são compatíveis com o servidor. Por padrão, ele tentará usar o HTTP/2 primeiro e, se não estiver habilitado, usará o HTTP/1.1. Se você quiser habilitá-lo, você pode definir:
quarkus.rest-client.alpn=true
// or for a single REST Client:
quarkus.rest-client.extensions-api.alpn=trueCrie o recurso Jakarta REST
Crie o arquivo src/main/java/org/acme/rest/client/ExtensionsResource.java com o seguinte conteúdo:
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;
@Path("/extension")
public class ExtensionsResource {
@RestClient (1)
ExtensionsService extensionsService;
@GET
@Path("/id/{id}")
public Set<Extension> id(String id) {
return extensionsService.getById(id);
}
}Há duas partes interessantes nesta listagem:
| 1 | o stub do cliente é injetado com a anotação @RestClient em vez da habitual anotação CDI @Inject |
Criação programática de clientes com o QuarkusRestClientBuilder
Em vez de anotar o cliente com @RegisterRestClient e injetar um cliente com @RestClient, você também pode criar um cliente REST de forma programática. Você faz isso com o QuarkusRestClientBuilder .
Com esta abordagem, a interface do cliente poderia ter o seguinte aspecto:
package org.acme.rest.client;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Set;
@Path("/extensions")
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") String id);
}E o serviço é o seguinte:
package org.acme.rest.client;
import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.net.URI;
import java.util.Set;
@Path("/extension")
public class ExtensionsResource {
private final ExtensionsService extensionsService;
public ExtensionsResource() {
extensionsService = QuarkusRestClientBuilder.newBuilder()
.baseUri(URI.create("https://stage.code.quarkus.io/api"))
.build(ExtensionsService.class);
}
@GET
@Path("/id/{id}")
public Set<Extension> id(String id) {
return extensionsService.getById(id);
}
}|
A interface |
Usar Opções HTTP Personalizadas
O Cliente REST Reativo utiliza internamente o Cliente HTTP Vert.x para efetuar as conexões de rede. As extensões do Cliente REST Reativo permitem configurar algumas definições através de propriedades, por exemplo:
-
quarkus.rest-client.client-prefix.connect-timeoutpara configurar o tempo limite de conexão em milissegundos. -
quarkus.rest-client.client-prefix.max-redirectspara limitar o número de redirecionamentos.
No entanto, existem muitas outras opções no Cliente HTTP Vert.x para configurar as conexões. Veja todas as opções na API de Opções do Cliente HTTP Vert.x neste link.
Para personalizar totalmente a instância do Cliente HTTP Vert.x que o Cliente REST Reativo está usando internamente, você pode fornecer a sua instância personalizada de Opções de Cliente HTTP através de CDI ou ao criar programaticamente o seu cliente.
Vejamos um exemplo de como fornecer as Opções de Cliente HTTP através de CDI:
package org.acme.rest.client;
import jakarta.enterprise.inject.Produces;
import jakarta.ws.rs.ext.ContextResolver;
import io.vertx.core.http.HttpClientOptions;
import io.quarkus.arc.Unremovable;
@Provider
public class CustomHttpClientOptions implements ContextResolver<HttpClientOptions> {
@Override
public HttpClientOptions getContext(Class<?> aClass) {
HttpClientOptions options = new HttpClientOptions();
// ...
return options;
}
}Agora, todos os Clientes REST usarão suas Opções de Cliente HTTP personalizadas.
Outra abordagem é fornecer as opções do Cliente HTTP personalizadas ao criar o cliente programaticamente:
package org.acme.rest.client;
import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.net.URI;
import java.util.Set;
import io.vertx.core.http.HttpClientOptions;
@Path("/extension")
public class ExtensionsResource {
private final ExtensionsService extensionsService;
public ExtensionsResource() {
HttpClientOptions options = new HttpClientOptions();
// ...
extensionsService = QuarkusRestClientBuilder.newBuilder()
.baseUri(URI.create("https://stage.code.quarkus.io/api"))
.httpClientOptions(options) (1)
.build(ExtensionsService.class);
}
// ...
}| 1 | o cliente utilizará as opções de Cliente HTTP registradas em vez das opções de Cliente HTTP fornecidas via CDI, se existirem. |
Redirecionamento
Um servidor HTTP pode redirecionar uma resposta para outra localização, enviando uma resposta com um código de estado que começa por "3" e um cabeçalho HTTP "Location" que contém o URL para onde deve ser redirecionado. Quando o Cliente REST recebe uma resposta de redirecionamento de um servidor HTTP, não efetua automaticamente outra requisição para a nova localização. Podemos ativar o redirecionamento automático no Cliente REST adicionando a propriedade "follow-redirects":
-
quarkus.rest-client.follow-redirectspara ativar o redirecionamento para todos os clientes REST. -
quarkus.rest-client.<client-prefix>.follow-redirectspara ativar o redirecionamento para um cliente REST específico.
Se esta propriedade for verdadeira, então o Cliente REST efetuará uma nova requisição quando receber uma resposta de redirecionamento do servidor HTTP.
Além disso, podemos limitar o número de redirecionamentos utilizando a propriedade "max-redirects".
Uma nota importante é que, de acordo com as especificações RFC2616, por padrão o redirecionamento só ocorrerá para os métodos GET ou HEAD. No entanto, no Cliente REST, você pode fornecer o seu manipulador de redirecionamento personalizado para permitir o redirecionamento nos métodos POST ou PUT, ou para seguir uma lógica mais complexa, utilizando a anotação @ClientRedirectHandler, CDI ou programaticamente ao criar o seu cliente.
Vejamos um exemplo sobre como registrar o seu próprio manipulador de redirecionamento personalizado utilizando a anotação @ClientRedirectHandler:
import jakarta.ws.rs.core.Response;
import io.quarkus.rest.client.reactive.ClientRedirectHandler;
@RegisterRestClient(configKey="extensions-api")
public interface ExtensionsService {
@ClientRedirectHandler
static URI alwaysRedirect(Response response) {
if (Response.Status.Family.familyOf(response.getStatus()) == Response.Status.Family.REDIRECTION) {
return response.getLocation();
}
return null;
}
}O manipulador de redirecionamento "alwaysRedirect" só será utilizado pelo Cliente REST especificado que, neste exemplo, é o cliente "ExtensionsService".
Alternativamente, você também pode fornecer um manipulador de redirecionamento personalizado para todos os seus Clientes REST através de CDI:
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ContextResolver;
import jakarta.ws.rs.ext.Provider;
import org.jboss.resteasy.reactive.client.handlers.RedirectHandler;
@Provider
public class AlwaysRedirectHandler implements ContextResolver<RedirectHandler> {
@Override
public RedirectHandler getContext(Class<?> aClass) {
return response -> {
if (Response.Status.Family.familyOf(response.getStatus()) == Response.Status.Family.REDIRECTION) {
return response.getLocation();
}
// no redirect
return null;
};
}
}Agora, todos os Clientes REST usarão seu manipulador de redirecionamento personalizado.
Outra abordagem consiste em fornecê-lo programaticamente na criação do cliente:
@Path("/extension")
public class ExtensionsResource {
private final ExtensionsService extensionsService;
public ExtensionsResource() {
extensionsService = QuarkusRestClientBuilder.newBuilder()
.baseUri(URI.create("https://stage.code.quarkus.io/api"))
.register(AlwaysRedirectHandler.class) (1)
.build(ExtensionsService.class);
}
// ...
}| 1 | o cliente utilizará o manipulador de redirecionamento registrado em vez do manipulador de redirecionamento fornecido através do CDI, se existir. |
Atualize o teste
Em seguida, precisamos atualizar o teste funcional para refletir as alterações feitas no endpoint. Edite o arquivo src/test/java/org/acme/rest/client/ExtensionsResourceTest.java e altere o conteúdo do teste para:
package org.acme.rest.client;
import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.hasItem;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.greaterThan;
@QuarkusTest
public class ExtensionsResourceTest {
@Test
public void testExtensionsIdEndpoint() {
given()
.when().get("/extension/id/io.quarkus:quarkus-rest-client-reactive")
.then()
.statusCode(200)
.body("$.size()", is(1),
"[0].id", is("io.quarkus:quarkus-rest-client-reactive"),
"[0].name", is("REST Client Reactive"),
"[0].keywords.size()", greaterThan(1),
"[0].keywords", hasItem("rest-client"));
}
}O código acima utiliza as capacidades json-path do REST Assured.
Suporte Assíncrono
Para obter todo o poder da natureza reativa do cliente, você pode usar a variante não blocante da extensão Cliente REST Reativo, que vem com suporte para CompletionStage e Uni . Vamos ver isso em ação adicionando um método getByIdAsync em nossa interface REST ExtensionsService . O código deve ter a seguinte aparência:
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Set;
import java.util.concurrent.CompletionStage;
@Path("/extensions")
@RegisterRestClient(configKey = "extensions-api")
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") String id);
@GET
CompletionStage<Set<Extension>> getByIdAsync(@QueryParam("id") String id);
}Abra o arquivo src/main/java/org/acme/rest/client/ExtensionsResource.java e atualize-o com o seguinte conteúdo:
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;
import java.util.concurrent.CompletionStage;
@Path("/extension")
public class ExtensionsResource {
@RestClient
ExtensionsService extensionsService;
@GET
@Path("/id/{id}")
public Set<Extension> id(String id) {
return extensionsService.getById(id);
}
@GET
@Path("/id-async/{id}")
public CompletionStage<Set<Extension>> idAsync(String id) {
return extensionsService.getByIdAsync(id);
}
}Observe que, como a invocação agora é não blocante, o método idAsync será invocado no loop de eventos, ou seja, não será transferido para um thread de pool de trabalho, reduzindo assim a utilização de recursos de hardware. Para obter mais detalhes, consulte o modelo de execução reativa Resteasy .
Para testar métodos assíncronos, adicione o método de teste abaixo em ExtensionsResourceTest:
@Test
public void testExtensionIdAsyncEndpoint() {
given()
.when().get("/extension/id-async/io.quarkus:quarkus-rest-client-reactive")
.then()
.statusCode(200)
.body("$.size()", is(1),
"[0].id", is("io.quarkus:quarkus-rest-client-reactive"),
"[0].name", is("REST Client Reactive"),
"[0].keywords.size()", greaterThan(1),
"[0].keywords", hasItem("rest-client"));
}A versão Uni é muito semelhante:
package org.acme.rest.client;
import io.smallrye.mutiny.Uni;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Set;
@Path("/extensions")
@RegisterRestClient(configKey = "extensions-api")
public interface ExtensionsService {
// ...
@GET
Uni<Set<Extension>> getByIdAsUni(@QueryParam("id") String id);
}O ExtensionsResource torna-se:
package org.acme.rest.client;
import io.smallrye.mutiny.Uni;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;
@Path("/extension")
public class ExtensionsResource {
@RestClient
ExtensionsService extensionsService;
// ...
@GET
@Path("/id-uni/{id}")
public Uni<Set<Extension>> idUni(String id) {
return extensionsService.getByIdAsUni(id);
}
}|
Mutiny
O código anterior usa tipos reativos do Mutiny. Se você não estiver familiarizado com o Mutiny, consulte Mutiny - uma biblioteca de programação reativa intuitiva . |
Ao retornar um Uni , cada assinatura invoca o serviço remoto. Isso significa que você pode reenviar a requisição assinando novamente o Uni , ou usar um retry da seguinte forma:
@RestClient ExtensionsService extensionsService;
// ...
extensionsService.getByIdAsUni(id)
.onFailure().retry().atMost(10);Se você usar um CompletionStage , precisará chamar o método do serviço para tentar novamente. Essa diferença vem do aspecto preguiçoso do Mutiny e de seu protocolo de assinatura. Mais detalhes sobre isso podem ser encontrados na documentação do Mutiny .
Suporte a Eventos Enviados pelo Servidor (SSE)
O consumo de eventos SSE é possível simplesmente declarando o tipo de resultado como um io.smallrye.mutiny.Multi .
O exemplo mais simples é:
package org.acme.rest.client;
import io.smallrye.mutiny.Multi;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
@Path("/sse")
@RegisterRestClient(configKey = "some-api")
public interface SseClient {
@GET
@Produces(MediaType.SERVER_SENT_EVENTS)
Multi<String> get();
}|
Toda a E/S envolvida no streaming dos resultados do SSE é feita de forma não blocante. |
Os resultados não se limitam a strings - por exemplo, quando o servidor retorna um payload JSON para cada evento, o Quarkus a desserializa automaticamente para o tipo genérico usado no Multi .
|
Os usuários também podem acessar todo o evento SSE usando o tipo Um exemplo simples em que os payloads do evento são valores |
Filtrando eventos
Ocasionalmente, o fluxo de eventos SSE pode conter alguns eventos que não devem ser retornados pelo cliente - um exemplo disso é fazer com que o servidor envie eventos de batimento cardíaco para manter aberta a conexão TCP subjacente. O Cliente REST oferece suporte à filtragem desses eventos, fornecendo o @org.jboss.resteasy.reactive.client.SseEventFilter .
Aqui está um exemplo de filtragem de eventos de batimento cardíaco:
package org.acme.rest.client;
import io.smallrye.mutiny.Uni;
import java.util.function.Predicate;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.jboss.resteasy.reactive.client.SseEvent;
import org.jboss.resteasy.reactive.client.SseEventFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
@Path("/sse")
@RegisterRestClient(configKey = "some-api")
public interface SseClient {
@GET
@Produces(MediaType.SERVER_SENT_EVENTS)
@SseEventFilter(HeartbeatFilter.class)
Multi<SseEvent<Long>> get();
class HeartbeatFilter implements Predicate<SseEvent<String>> {
@Override
public boolean test(SseEvent<String> event) {
return !"heartbeat".equals(event.id());
}
}
}Suporte para cabeçalhos personalizados
Existem algumas formas de especificar cabeçalhos personalizados para as suas chamadas REST:
-
registrando um
ClientHeadersFactoryou umReactiveClientHeadersFactorycom a anotação@RegisterClientHeaders -
registrando programaticamente um
ClientHeadersFactoryou umReactiveClientHeadersFactorycom o métodoQuarkusRestClientBuilder.clientHeadersFactory(factory) -
especificando o valor do cabeçalho com
@ClientHeaderParam -
especificando o valor do cabeçalho por
@HeaderParam
O código abaixo demonstra como utilizar cada uma destas técnicas:
package org.acme.rest.client;
import org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam;
import org.eclipse.microprofile.rest.client.annotation.RegisterClientHeaders;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.HeaderParam;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Set;
import io.quarkus.rest.client.reactive.NotBody;
@Path("/extensions")
@RegisterRestClient
@RegisterClientHeaders(RequestUUIDHeaderFactory.class) (1)
@ClientHeaderParam(name = "my-header", value = "constant-header-value") (2)
@ClientHeaderParam(name = "computed-header", value = "{org.acme.rest.client.Util.computeHeader}") (3)
public interface ExtensionsService {
@GET
@ClientHeaderParam(name = "header-from-properties", value = "${header.value}") (4)
@ClientHeaderParam(name = "header-from-method-param", value = "Bearer {token}") (5)
Set<Extension> getById(@QueryParam("id") String id, @HeaderParam("jaxrs-style-header") String headerValue, @NotBody String token); (6)
}| 1 | Só pode haver um ClientHeadersFactory por classe. Com ela, é possível não só adicionar cabeçalhos personalizados, mas também transformar os existentes. Veja a classe RequestUUIDHeaderFactory abaixo para um exemplo da fábrica. |
| 2 | @ClientHeaderParam pode ser utilizado na interface do cliente e nos métodos. Pode especificar um valor de cabeçalho constante… |
| 3 | … e um nome de um método que deve calcular o valor do cabeçalho. Pode ser um método estático ou um método padrão nesta interface. O método pode não receber nenhum parâmetro, um único parâmetro String ou um único parâmetro io.quarkus.rest.client.reactive.ComputedParamContext (que é muito útil para código que precisa calcular cabeçalhos com base em parâmetros de métodos e complementa naturalmente @io.quarkus.rest.client.reactive.NotBody). |
| 4 | … bem como um valor da configuração da sua aplicação |
| 5 | … ou mesmo qualquer mistura de texto literal, parâmetros de métodos (referenciados pelo nome), um valor de configuração (como mencionado anteriormente) e invocações de métodos (como mencionado anteriormente) |
| 6 | … ou como um argumento anotado do Jakarta REST @HeaderParam normal |
|
Ao usar o Kotlin, se os métodos padrão forem aproveitados, o compilador do Kotlin precisará ser configurado para usar os recursos de interface padrão do Java. Veja isso para obter mais detalhes. |
Um ClientHeadersFactory pode ter o seguinte aspecto:
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;
}
}Como você vê no exemplo acima, é possível tornar a implementação do ClientHeadersFactory um bean CDI anotando-o com uma anotação de definição de escopo, como @Singleton , @ApplicationScoped , etc.
Para especificar um valor para ${header.value}, basta colocar o seguinte no seu application.properties:
header.value=value of the headerAlém disso, existe uma variante reativa de ClientHeadersFactory que permite realizar operações blocantes. Por exemplo:
package org.acme.rest.client;
import io.smallrye.mutiny.Uni;
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 GetTokenReactiveClientHeadersFactory extends ReactiveClientHeadersFactory {
@Inject
Service service;
@Override
public Uni<MultivaluedMap<String, String>> getHeaders(
MultivaluedMap<String, String> incomingHeaders,
MultivaluedMap<String, String> clientOutgoingHeaders) {
return Uni.createFrom().item(() -> {
MultivaluedHashMap<String, String> newHeaders = new MultivaluedHashMap<>();
// perform blocking call
newHeaders.add(HEADER_NAME, service.getToken());
return newHeaders;
});
}
}Fábrica de cabeçalhos padrão
A anotação @RegisterClientHeaders também pode ser usada sem nenhuma fábrica personalizada especificada. Nesse caso, será usada a fábrica DefaultClientHeadersFactoryImpl . Se você fizer uma chamada de cliente REST a partir de um recurso REST, essa fábrica propagará todos os cabeçalhos listados na propriedade de configuração org.eclipse.microprofile.rest.client.propagateHeaders da requisição do recurso para a requisição do cliente. Os nomes dos cabeçalhos individuais são separados por vírgulas.
@Path("/extensions")
@RegisterRestClient
@RegisterClientHeaders
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") String id);
@GET
CompletionStage<Set<Extension>> getByIdAsync(@QueryParam("id") String id);
}org.eclipse.microprofile.rest.client.propagateHeaders=Authorization,Proxy-AuthorizationPersonalização da requisição
O Cliente REST Reativo suporta uma maior personalização da requisição final que será enviada para o servidor através de filtros. Os filtros devem implementar a interface ClientRequestFilter ou ResteasyReactiveClientRequestFilter.
Um exemplo simples de personalização da requisição seria adicionar um cabeçalho personalizado:
@Provider
public class TestClientRequestFilter implements ClientRequestFilter {
@Override
public void filter(ClientRequestContext requestContext) {
requestContext.getHeaders().add("my_header", "value");
}
}Em seguida, pode registrar o seu filtro utilizando a anotação @RegisterProvider:
@Path("/extensions")
@RegisterProvider(TestClientRequestFilter.class)
public interface ExtensionsService {
// ...
}Ou programaticamente, utilizando o método .register():
QuarkusRestClientBuilder.newBuilder()
.register(TestClientRequestFilter.class)
.build(ExtensionsService.class)Injetando a instância jakarta.ws.rs.ext.Providers em filtros
O jakarta.ws.rs.ext.Providers é útil quando precisamos procurar as instâncias do fornecedor do cliente atual.
Podemos obter a instância Providers nos nossos filtros a partir do contexto do requisição da seguinte forma:
@Provider
public class TestClientRequestFilter implements ClientRequestFilter {
@Override
public void filter(ClientRequestContext requestContext) {
Providers providers = ((ResteasyReactiveClientRequestContext) requestContext).getProviders();
// ...
}
}Alternativamente, pode implementar a interface ResteasyReactiveClientRequestFilter em vez da interface ClientRequestFilter, que fornecerá diretamente o contexto ResteasyReactiveClientRequestContext:
@Provider
public class TestClientRequestFilter implements ResteasyReactiveClientRequestFilter {
@Override
public void filter(ResteasyReactiveClientRequestFilter requestContext) {
Providers providers = requestContext.getProviders();
// ...
}
}Personalizando o ObjectMapper no Cliente REST Reativo Jackson
O Cliente REST Reativo suporta a adição de um ObjectMapper personalizado para ser utilizado apenas pelo Cliente utilizando a anotação @ClientObjectMapper.
Um exemplo simples é fornecer um ObjectMapper personalizado para a extensão Cliente REST Reativo Jackson:
@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") String id);
@ClientObjectMapper (1)
static ObjectMapper objectMapper(ObjectMapper defaultObjectMapper) { (2)
return defaultObjectMapper.copy() (3)
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.disable(DeserializationFeature.UNWRAP_ROOT_VALUE);
}
}| 1 | O método deve ser anotado com @ClientObjectMapper. |
| 2 | Tem que ser um método estático. Além disso, o parâmetro defaultObjectMapper será resolvido através do CDI. Se não for encontrado, será lançada uma exceção em tempo de execução. |
| 3 | Neste exemplo, estamos criando uma cópia do mapeador de objetos padrão. Você NUNCA deve modificar o mapeador de objetos padrão, mas sim criar uma cópia. |
Tratamento de exceções
A especificação do Cliente REST MicroProfile introduz o org.eclipse.microprofile.rest.client.ext.ResponseExceptionMapper, cujo objetivo é converter uma resposta HTTP numa exceção.
Um exemplo simples de implementação de tal ResponseExceptionMapper para o ExtensionsService discutido acima, poderia ser:
public class MyResponseExceptionMapper implements ResponseExceptionMapper<RuntimeException> {
@Override
public RuntimeException toThrowable(Response response) {
if (response.getStatus() == 500) {
throw new RuntimeException("The remote service responded with HTTP 500");
}
return null;
}
}ResponseExceptionMapper também define o método getPriority , que é usado para determinar a prioridade com que as implementações de ResponseExceptionMapper serão chamadas (as implementações com um valor menor para getPriority serão chamadas primeiro). Se toThrowable retornar uma exceção, essa exceção será lançada. Se null for retornado, a próxima implementação de ResponseExceptionMapper na cadeia será chamada (se houver alguma).
A classe, conforme escrito acima, não seria usada automaticamente por nenhum Cliente REST. Para torná-la disponível para todos os Clientes REST da aplicação, a classe precisa ser anotada com @Provider (desde que quarkus.rest-client-reactive.provider-autodiscovery não esteja definido como false ). Como alternativa, se a classe de tratamento de exceções se aplicar apenas a interfaces específicas do Cliente REST, você poderá anotar as interfaces com @RegisterProvider(MyResponseExceptionMapper.class) ou registrá-la usando a configuração com a propriedade providers do grupo de configuração quarkus.rest-client adequado.
Usando @ClientExceptionMapper
Uma forma mais simples de converter códigos de resposta HTTP de 400 pra cima é utilizar a anotação @ClientExceptionMapper.
Para a interface de Cliente REST ExtensionsService definida acima, um exemplo de utilização de @ClientExceptionMapper seria:
@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {
@GET
Set<Extension> getById(@QueryParam("id") String id);
@GET
CompletionStage<Set<Extension>> getByIdAsync(@QueryParam("id") String id);
@ClientExceptionMapper
static RuntimeException toException(Response response) {
if (response.getStatus() == 500) {
return new RuntimeException("The remote service responded with HTTP 500");
}
return null;
}
}Naturalmente, este tratamento é efetuado por Cliente REST. @ClientExceptionMapper utiliza a prioridade predefinida se o atributo priority não estiver definido e aplicam-se as regras normais de invocação de todos os manipuladores sucessivamente.
Os métodos anotados com @ClientExceptionMapper também podem receber um parâmetro java.lang.reflect.Method, o que é útil se o código de mapeamento de exceções precisar conhecer o método do Cliente REST que foi invocado e causou a ativação do código de mapeamento de exceções.
|
Usando a anotação @Blocking em mapeadores de exceções
Em casos que justifiquem a utilização de InputStream como tipo de retorno do método do Cliente REST (por exemplo, quando é necessário ler grandes quantidades de dados):
@Path("/echo")
@RegisterRestClient
public interface EchoClient {
@GET
InputStream get();
}Isso funcionará como esperado, mas se você tentar ler esse objeto InputStream em um mapeador de exceções personalizado, receberá uma exceção BlockingNotAllowedException. Isso ocorre porque as classes ResponseExceptionMapper são executadas no executor de thread do Loop de Eventos por padrão - o que não permite realizar operações de E/S.
Para tornar o seu mapeador de exceções blocante, pode anotar o mapeador de exceções com a anotação @Blocking:
@Provider
@Blocking (1)
public class MyResponseExceptionMapper implements ResponseExceptionMapper<RuntimeException> {
@Override
public RuntimeException toThrowable(Response response) {
if (response.getStatus() == 500) {
response.readEntity(String.class); (2)
return new RuntimeException("The remote service responded with HTTP 500");
}
return null;
}
}| 1 | Com a anotação @Blocking, o mapeador de exceções MyResponseExceptionMapper será executado no pool de threads de trabalho. |
| 2 | A leitura da entidade é agora permitida porque estamos executando o mapeador no pool de threads de trabalho. |
Note que também pode utilizar a anotação @Blocking quando utilizar @ClientExceptionMapper:
@Path("/echo")
@RegisterRestClient
public interface EchoClient {
@GET
InputStream get();
@ClientExceptionMapper
@Blocking
static RuntimeException toException(Response response) {
if (response.getStatus() == 500) {
response.readEntity(String.class);
return new RuntimeException("The remote service responded with HTTP 500");
}
return null;
}
}Suporte a Formulários Multi-partes
O Cliente REST Reativo suporta mensagens com multi-parte.
Enviando Mensagens Multi-partes
O Cliente REST Reativo permite o envio de dados como formulários multi-partes. Dessa forma, você pode, por exemplo, enviar arquivos de forma eficiente.
Para enviar dados como um formulário multi-partes, você pode simplesmente utilizar as anotações normais @RestForm (ou @FormParam):
@POST
@Path("/binary")
String sendMultipart(@RestForm File file, @RestForm String otherField);Os parâmetros especificados como File , Path , byte[] ou Buffer são enviados como arquivos e têm como padrão o tipo MIME application/octet-stream . Outros tipos de parâmetros @RestForm têm como padrão o tipo MIME text/plain . Você pode substituir esses padrões com a anotação @PartType .
Naturalmente, também é possível agrupar estes parâmetros numa classe que os contenha:
public static class Parameters {
@RestForm
File file;
@RestForm
String otherField;
}
@POST
@Path("/binary")
String sendMultipart(Parameters parameters);Qualquer parâmetro @RestForm do tipo File , Path , byte[] ou Buffer , bem como qualquer parâmetro anotado com @PartType implica automaticamente em um @Consumes(MediaType.MULTIPART_FORM_DATA) no método se não houver um @Consumes presente.
| Se houver parâmetros @RestForm que não implicam em multi-parte, então @Consumes(MediaType.APPLICATION_FORM_URLENCODED) estará implícito. |
Há alguns modos pelos quais os dados do formulário podem ser codificados. Por padrão, o Cliente REST Reativo usa RFC1738. Você pode substituí-la especificando o modo no nível do cliente, definindo a propriedade io.quarkus.rest.client.multipart-post-encoder-mode RESTBuilder como o valor selecionado de HttpPostRequestEncoder.EncoderMode ou especificando quarkus.rest-client.multipart-post-encoder-mode em seu application.properties . Observe que a última opção funciona somente para clientes criados com a anotação @RegisterRESTClient . Todos os modos disponíveis estão descritos na documentação do Netty
Você também pode enviar multi-partes JSON especificando a anotação @PartType:
public static class Person {
public String firstName;
public String lastName;
}
@POST
@Path("/json")
String sendMultipart(@RestForm @PartType(MediaType.APPLICATION_JSON) Person person);Recebendo Mensagens Multi-partes
O Cliente REST Reativo também oferece suporte ao recebimento de mensagens multi-partes. Assim como no envio, para analisar uma resposta multi-parte, você precisa criar uma classe que descreva os dados da resposta, por exemplo
public class FormDto {
@RestForm (1)
@PartType(MediaType.APPLICATION_OCTET_STREAM)
public File file;
@FormParam("otherField") (2)
@PartType(MediaType.TEXT_PLAIN)
public String textProperty;
}| 1 | utiliza a anotação abreviada @RestForm para criar um campo como parte de um formulário multi-partes |
| 2 | a norma @FormParam também pode ser utilizada. Permite substituir o nome da parte multi-partes. |
Em seguida, crie um método de interface que corresponda à chamada e faça-o devolver o FormDto:
@GET
@Produces(MediaType.MULTIPART_FORM_DATA)
@Path("/get-file")
FormDto data receiveMultipart();Atualmente, o suporte de respostas multi-partes está sujeito às seguintes limitações:
-
os arquivos enviados em respostas multi-partes só podem ser analisados em
File,PatheFileDownload -
cada campo do tipo de resposta tem de ser anotado com
@PartType- os campos sem esta anotação são ignorados
O Cliente REST Reativo precisa de conhecer antecipadamente as classes utilizadas como tipos de retorno multi-partes. Se tiver um método de interface que produz multipart/form-data, o tipo de retorno será descoberto automaticamente. No entanto, se pretender utilizar a API ClientBuilder para analisar uma resposta como multi-parte, tem de anotar a sua classe DTO com @MultipartForm.
| Os arquivos que você baixa não são removidos automaticamente e podem ocupar muito espaço no disco. Considere a remoção dos arquivos quando terminar de trabalhar com eles. |
Utilização de multi-partes mistas / OData
Não é incomum que um aplicativo precise interagir com sistemas corporativos (como sistemas de CRM) usando um protocolo especial chamado OData . Esse protocolo usa essencialmente um Content-Type HTTP personalizado que precisa de algum código de cola para funcionar com o Cliente REST (a criação do corpo depende inteiramente da aplicação - o Cliente REST não pode fazer muito para ajudar).
Um exemplo é o seguinte:
@Path("/crm")
@RegisterRestClient
public interface CRMService {
@POST
@ClientHeaderParam(name = "Content-Type", value = "{calculateContentType}") (1)
String performBatch(@HeaderParam("Authorization") String accessToken, @NotBody String batchId, String body); (2)
default String calculateContentType(ComputedParamContext context) {
return "multipart/mixed;boundary=batch_" + context.methodParameters().get(1).value(); (3)
}
}O código utiliza os seguintes elementos:
| 1 | @ClientHeaderParam(name = "Content-Type", value = "{calculateContentType}") que garante que o cabeçalho Content-Type é criado chamando o método padrão calculateContentType da interface. |
| 2 | O parâmetro acima mencionado precisa de ser anotado com @NotBody porque só é utilizado para ajudar na construção de cabeçalhos HTTP. |
| 3 | context.methodParameters().get(1).value() que permite que o método calculateContentType obtenha o parâmetro de método correto passado para o método do Cliente REST. |
Tal como referido anteriormente, o parâmetro do corpo tem de ser corretamente elaborado pelo código da aplicação para estar em conformidade com os requisitos do serviço.
Recebendo mensagens comprimidas
O Cliente REST Reativo também suporta o recebimento de mensagens compactadas usando GZIP. Você pode ativar o suporte à compactação HTTP adicionando a propriedade quarkus.http.enable-compression=true . Quando esse recurso está ativado e um servidor retorna uma resposta que inclui o cabeçalho Content-Encoding: gzip , o Cliente REST Reativo decodifica automaticamente o conteúdo e prossegue com o tratamento da mensagem.
Suporte de proxy
O Cliente REST Reativo suporta o envio de requisições por meio de um proxy. Ele respeita as configurações da JVM para isso, mas também permite especificar ambos:
-
definições globais de proxy de cliente, com
quarkus.rest-client.proxy-address,quarkus.rest-client.proxy-user,quarkus.rest-client.proxy-password,quarkus.rest-client.non-proxy-hosts -
definições de proxy por cliente, com
quarkus.rest-client.<my-client>.proxy-address, etc. Estas são aplicadas apenas a clientes injetados com CDI, ou seja, os criados com@RegisterRestClient
Se proxy-address estiver definido no nível do cliente, o cliente utiliza as suas definições de proxy específicas. Nenhuma definição de proxy é propagada a partir da configuração global ou das propriedades da JVM.
Se proxy-address não estiver definido para o cliente, mas estiver definido no nível global, o cliente usará as configurações globais. Caso contrário, o cliente usará as configurações da JVM.
Um exemplo de configuração para definir o proxy:
# global proxy configuration is used for all clients
quarkus.rest-client.proxy-address=localhost:8182
quarkus.rest-client.proxy-user=<proxy user name>
quarkus.rest-client.proxy-password=<proxy password>
quarkus.rest-client.non-proxy-hosts=example.com
# per-client configuration overrides the global settings for a specific client
quarkus.rest-client.my-client.proxy-address=localhost:8183
quarkus.rest-client.my-client.proxy-user=<proxy user name>
quarkus.rest-client.my-client.proxy-password=<proxy password>
quarkus.rest-client.my-client.url=...
A especificação do Cliente REST MicroProfile não permite a definição de credenciais de proxy. Para especificar o usuário e a senha do proxy de forma programática, é necessário enviar o seu RestClientBuilder para RestClientBuilderImpl.
|
Empacote e execute a aplicação
Execute a aplicação com:
quarkus dev./mvnw quarkus:dev./gradlew --console=plain quarkusDevAbra o seu browser em http://localhost:8080/extension/id/io.quarkus:quarkus-rest-client-reactive.
Você deve ver um objeto JSON que contém algumas informações básicas sobre esta extensão.
Como de costume, a aplicação pode ser empacotada utilizando:
quarkus build./mvnw install./gradlew buildE executado com java -jar target/quarkus-app/quarkus-run.jar.
Também é possível gerar o executável nativo com:
quarkus build --native./mvnw install -Dnative./gradlew build -Dquarkus.package.type=nativeRegistrando tráfego
O Cliente REST Reativo pode registrar as requisições que envia e as respostas que recebe. Para ativar o registro, adicione a propriedade quarkus.rest-client.logging.scope ao seu application.properties e defina-a como:
-
request-responsepara registrar o conteúdo da requisição e da resposta, ou -
allpara permitir também o registro de baixo nível das bibliotecas subjacentes.
Como as mensagens HTTP podem ter corpos grandes, limitamos a quantidade de caracteres do corpo registrado. O limite padrão é 100, pode alterá-lo especificando quarkus.rest-client.logging.body-limit.
| O Cliente REST Reativo está registrando o tráfego com o nível DEBUG e não altera as propriedades do registrador. Poderá ser necessário ajustar a configuração do registrador para utilizar esta funcionalidade. |
Um exemplo de configuração de registro:
quarkus.rest-client.logging.scope=request-response
quarkus.rest-client.logging.body-limit=50
quarkus.log.category."org.jboss.resteasy.reactive.client.logging".level=DEBUG|
REST Client Reactive uses a default When setting up the client programmatically using the For declarative clients using |
Simulação do cliente para testes
Se você usar um cliente injetado com a anotação @RestClient, poderá facilmente simulá-lo para testes. Você pode fazer isso com @InjectMock do Mockito ou com QuarkusMock .
Esta seção mostra como substituir o seu cliente por uma simulação. Se pretender obter uma compreensão mais aprofundada de como funciona a simulação no Quarkus, consulte a publicação do blog sobre a simulação de beans CDI.
A simulação não funciona quando se utiliza @QuarkusIntegrationTest.
|
Vamos supor que você tem o seguinte cliente:
package io.quarkus.it.rest.client.main;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
@Path("/")
@RegisterRestClient
public interface Client {
@GET
String get();
}Simulando com InjectMock
A abordagem mais simples para simular um cliente para testes é usar Mockito e @InjectMock.
Primeiro, adicione a seguinte dependência à sua aplicação:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5-mockito</artifactId>
<scope>test</scope>
</dependency>testImplementation("io.quarkus:quarkus-junit5-mockito")Depois, no seu teste, pode simplesmente utilizar @InjectMock para criar e injetar uma simulação:
package io.quarkus.it.rest.client.main;
import static org.mockito.Mockito.when;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;
@QuarkusTest
public class InjectMockTest {
@InjectMock
@RestClient
Client mock;
@BeforeEach
public void setUp() {
when(mock.get()).thenReturn("MockAnswer");
}
@Test
void doTest() {
// ...
}
}Simulando com o QuarkusMock
Se o Mockito não satisfizer as suas necessidades, você pode criar uma simulação programaticamente utilizando QuarkusMock, e.g.:
package io.quarkus.it.rest.client.main;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import io.quarkus.test.junit.QuarkusMock;
import io.quarkus.test.junit.QuarkusTest;
@QuarkusTest
public class QuarkusMockTest {
@BeforeEach
public void setUp() {
Client customMock = new Client() { (1)
@Override
public String get() {
return "MockAnswer";
}
};
QuarkusMock.installMockForType(customMock, Client.class, RestClient.LITERAL); (2)
}
@Test
void doTest() {
// ...
}
}| 1 | aqui utilizamos uma implementação criada manualmente da interface do cliente para substituir a interface do cliente atual |
| 2 | note-se que RestClient.LITERAL tem de ser passado como último argumento do método installMockForType |
Usando um Servidor HTTP Simulado para testes
Setting up a mock HTTP server, against which tests are run, is a common testing pattern.
Examples of such servers are Wiremock and Hoverfly.
In this section we’ll demonstrate how Wiremock can be leveraged for testing the ExtensionsService which was developed above.
First, Wiremock needs to be added as a test dependency. For a Maven project that would happen like so:
<dependency>
<groupId>org.wiremock</groupId>
<artifactId>wiremock</artifactId>
<scope>test</scope>
<version>${wiremock.version}</version> (1)
</dependency>| 1 | Use a proper Wiremock version. All available versions can be found here. |
testImplementation("org.wiremock:wiremock:$wiremockVersion") (1)| 1 | Use a proper Wiremock version. All available versions can be found here. |
In Quarkus tests when some service needs to be started before the Quarkus tests are ran, we utilize the @io.quarkus.test.common.QuarkusTestResource
annotation to specify a io.quarkus.test.common.QuarkusTestResourceLifecycleManager which can start the service and supply configuration
values that Quarkus will use.
|
For more details about |
Let’s create an implementation of QuarkusTestResourceLifecycleManager called WiremockExtensions like so:
package org.acme.rest.client;
import java.util.Map;
import com.github.tomakehurst.wiremock.WireMockServer;
import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
import static com.github.tomakehurst.wiremock.client.WireMock.*; (1)
public class WireMockExtensions implements QuarkusTestResourceLifecycleManager { (2)
private WireMockServer wireMockServer;
@Override
public Map<String, String> start() {
wireMockServer = new WireMockServer();
wireMockServer.start(); (3)
wireMockServer.stubFor(get(urlEqualTo("/extensions?id=io.quarkus:quarkus-rest-client-reactive")) (4)
.willReturn(aResponse()
.withHeader("Content-Type", "application/json")
.withBody(
"[{" +
"\"id\": \"io.quarkus:quarkus-rest-client-reactive\"," +
"\"name\": \"REST Client\"" +
"}]"
)));
wireMockServer.stubFor(get(urlMatching(".*")).atPriority(10).willReturn(aResponse().proxiedFrom("https://stage.code.quarkus.io/api"))); (5)
return Map.of("quarkus.rest-client.\"org.acme.rest.client.ExtensionsService\".url", wireMockServer.baseUrl()); (6)
}
@Override
public void stop() {
if (null != wireMockServer) {
wireMockServer.stop(); (7)
}
}
}| 1 | Statically importing the methods in the Wiremock package makes it easier to read the test. |
| 2 | The start method is invoked by Quarkus before any test is run and returns a Map of configuration properties that apply during the test execution. |
| 3 | Launch Wiremock. |
| 4 | Configure Wiremock to stub the calls to /extensions?id=io.quarkus:quarkus-rest-client-reactive by returning a specific canned response. |
| 5 | All HTTP calls that have not been stubbed are handled by calling the real service. This is done for demonstration purposes, as it is not something that would usually happen in a real test. |
| 6 | As the start method returns configuration that applies for tests, we set the rest-client property that controls the base URL which is used by the implementation
of ExtensionsService to the base URL where Wiremock is listening for incoming requests. |
| 7 | When all tests have finished, shutdown Wiremock. |
The ExtensionsResourceTest test class needs to be annotated like so:
@QuarkusTest
@QuarkusTestResource(WireMockExtensions.class)
public class ExtensionsResourceTest {
}|
|
Limitações conhecidas
Embora a extensão Cliente REST Reativo pretenda ser uma substituição imediata da extensão Cliente REST, existem algumas diferenças e limitações:
-
o escopo padrão do cliente para a nova extensão é
@ApplicationScoped, enquanto oquarkus-rest-clienttem como padrão@Dependent. Para alterar esse comportamento, defina a propriedadequarkus.rest-client-reactive.scopecomo o nome do escopo totalmente qualificado. -
não é possível definir
HostnameVerifierouSSLContext -
algumas coisas que não fazem sentido para implementações não blocantes, como a definição do
ExecutorService, não funcionam
