Seite 4: MicroProfile Rest Client

Inhaltsverzeichnis

Viele Aufrufe in einer Microservice-Architektur werden nicht von einem einzigen Service bearbeitet. Der Service, der durch einen Client aufgerufen wird, ruft häufig weitere Services auf, die Teilaufgaben implementieren. Um den Vorgang zu vereinfachen, kommt die MicroProfile-Rest-Client-Spezifikation zum Einsatz, die aufbauend auf den JAX-RS 2.0 Client APIs eine einfache Möglichkeit bietet, aus einem Microservice einen anderen REST-Endpoint aufzurufen. Dazu werden ein Clientinterface des aufzurufenden REST-Service und ein ResponseExceptionMapper zur Behandlung auftretender Fehler benötigt.

Ein Interface beschreibt den Endpoint

Der aufzurufende REST-Endpoint wird durch ein Clientinterface abgebildet. Die Methoden dieses Interfaces müssen dabei denen entsprechen, die auf dem entfernten REST-Endpoint aufgerufen werden sollen.

Um beispielsweise die getOrderById-Methode des bereits zuvor gezeigten Order Endpoints aufzurufen, benötigt man das nachfolgend gezeigte Client-Interface. Wenn mehrere Methoden auf dem REST-Endpoint aufgerufen werden sollen, lässt sich das Interface um diese erweitern.

@Path("/order")
 @Consumes("application/json")
@Dependent
 @RegisterRestClient
 @RegisterProvider(OrderResponseExceptionMapper.class)
 public interface OrderService {

    @GET
    @Path("/{orderId}")
    public Response getOrderById(@PathParam("orderId") String orderId) throws UnknownOrderException;
 }

Die @RegisterRestClient-Annotation ist in diesem Beispiel von besonderer Bedeutung. Sie registriert das Interface als REST-Client, der sich in andere CDI-Beans injecten lässt. Falls sich für die beim Aufruf verwendete orderId keine Order finden lässt, liefert der Endpoint den Response Code 404 zurück. Die Behandlung des Codes erfolgt durch den OrderResponseExceptionMapper, der mit Hilfe der @RegisterProvider-Annotation registriert und im nachfolgenden Abschnitt genauer erläutert wird.

Fehlerbehandlung mit einem ResponseExceptionMapper

Um die im Fehlerfall erhaltenen HTTP-Codes in der Anwendung behandeln zu können, werden sie durch einen ResponseExceptionMapper auf Java Exceptions abgebildet. In diesem Beispiel wird für den HTTP-Code 404 eine UnknownOrderException erzeugt.

    @Override
    public boolean handles(int statusCode, MultivaluedMap<String, Object> headers) {
        return statusCode == 404;
    }

    @Override
    public OrderException toThrowable(Response response) {
        switch(response.getStatus()) {
        case 404: return new UnknownOrderException();
        }
        return null;
    }

 }

Aufruf eines REST Endpoints

Sobald das Client-Interface und die Fehlerbehandlung implementiert sind, lässt sich der REST-Client mit Hilfe der @Inject- und @RestClient-Annotationen in eine CDI Bean injecten und anschließend verwenden.

@ApplicationScoped
public class OrderManager {

    @Inject
    @RestClient
    private OrderService orderService;

    …
 }

In den bisherigen Codebeispielen ist die Base URL des OrderService nicht definiert. Das liegt daran, dass sie auf Basis der MicroProfile-Config-Spezifikation konfiguriert werden sollte. Dazu ist ein Parameter erforderlich, der dem Namensmuster <fullyQualifiedInterfaceName>/mp-rest/url entspricht. In diesem Beispiel ließe sich die Base URL also durch den Parameter org.example.OrderService/mp-rest/url konfigurieren.