JAX-RS / Jersey jak dostosować obsługę błędów?

Uczę się JAX-RS (alias JSR-311) przy użyciu Jersey. Z powodzeniem utworzyłem Zasób root i bawię się parametrami:

@Path("/hello")
public class HelloWorldResource {

    @GET
    @Produces("text/html")
    public String get(
        @QueryParam("name") String name,
        @QueryParam("birthDate") Date birthDate) {

         // Return a greeting with the name and age
    }
}

Działa to świetnie i obsługuje dowolny format w bieżących ustawieniach regionalnych rozumiany przez konstruktor Date (String) (np. RRRR / mm / dd i mm / dd / RRRR). Ale jeśli podam wartość, która jest niepoprawna lub niezrozumiała, otrzymuję odpowiedź 404.

Na przykład:

GET /hello?name=Mark&birthDate=X

404 Not Found

Jak mogę dostosować to zachowanie? Może inny kod odpowiedzi (prawdopodobnie „400 złych żądań”)? Co z logowaniem błędu? Może dodać opis problemu („zły format daty”) w niestandardowym nagłówku, aby ułatwić rozwiązywanie problemów? Lub zwróć całą odpowiedź na błąd wraz ze szczegółami, wraz z kodem statusu 5xx?

Istnieje kilka podejść do dostosowania zachowania w zakresie obsługi błędów w JAX-RS. Oto trzy najprostsze sposoby.

Pierwsze podejście polega na utworzeniu klasy wyjątku, która rozszerza wyjątek WebApplicationException.

Przykład:

public class NotAuthorizedException extends WebApplicationException {
     public NotAuthorizedException(String message) {
         super(Response.status(Response.Status.UNAUTHORIZED)
             .entity(message).type(MediaType.TEXT_PLAIN).build());
     }
}

Aby rzucić ten nowo utworzony wyjątek, po prostu:

@Path("accounts/{accountId}/")
    public Item getItem(@PathParam("accountId") String accountId) {
       // An unauthorized user tries to enter
       throw new NotAuthorizedException("You Don't Have Permission");
}

Zauważ, że nie musisz deklarować wyjątku w klauzuli throws, ponieważ WebApplicationException to wyjątek czasu wykonywania. To zwróci klientowi odpowiedź 401.

Drugim i łatwiejszym podejściem jest po prostu skonstruowanie wystąpienia WebApplicationExceptionbezpośrednio w kodzie. Takie podejście działa, o ile nie musisz implementować własnych wyjątków aplikacji.

Przykład:

@Path("accounts/{accountId}/")
public Item getItem(@PathParam("accountId") String accountId) {
   // An unauthorized user tries to enter
   throw new WebApplicationException(Response.Status.UNAUTHORIZED);
}

Ten kod również zwraca klientowi wartość 401.

Oczywiście to tylko prosty przykład. Możesz uczynić wyjątek znacznie bardziej złożonym, jeśli to konieczne, i możesz wygenerować kod HTTP, którego potrzebujesz.

Innym podejściem jest zawinięcie istniejącego wyjątku, być może ObjectNotFoundExceptionz małą klasą opakowania, która implementuje ExceptionMapperinterfejs opatrzony @Provideradnotacją. Mówi to środowisku wykonawczemu JAX-RS, że jeśli zgłoszony wyjątek zostanie zgłoszony, zwróć kod odpowiedzi zdefiniowany w pliku ExceptionMapper.

@Provider
public class BadURIExceptionMapper implements ExceptionMapper<NotFoundException> {

public Response toResponse(NotFoundException exception){

    return Response.status(Response.Status.NOT_FOUND).
    entity(new ErrorResponse(exception.getClass().toString(),
                exception.getMessage()) ).
    build();
}
}

Stwórz ponad klasę. To obsłuży 404 (NotFoundException) i tutaj w metodzie toResponse możesz podać swoją niestandardową odpowiedź. Podobnie istnieją ParamException itp., Które należy zmapować, aby uzyskać dostosowane odpowiedzi.

Jersey zgłasza wyjątek com.sun.jersey.api.ParamException, gdy nie zdoła usunąć parametrów, więc jednym z rozwiązań jest utworzenie wyjątku, który obsługuje te typy wyjątków:

@Provider
public class ParamExceptionMapper implements ExceptionMapper<ParamException> {
    @Override
    public Response toResponse(ParamException exception) {
        return Response.status(Status.BAD_REQUEST).entity(exception.getParameterName() + " incorrect type").build();
    }
}

Możesz także napisać klasę wielokrotnego użytku dla zmiennych z komentarzami QueryParam

public class DateParam {
  private SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");

  private Calendar date;

  public DateParam(String in) throws WebApplicationException {
    try {
      date = Calendar.getInstance();
      date.setTime(format.parse(in));
    }
    catch (ParseException exception) {
      throw new WebApplicationException(400);
    }
  }
  public Calendar getDate() {
    return date;
  }
  public String format() {
    return format.format(value.getTime());
  }
}

użyj tego w następujący sposób:

private @QueryParam("from") DateParam startDateParam;
private @QueryParam("to") DateParam endDateParam;
// ...
startDateParam.getDate();

Mimo że obsługa błędów jest w tym przypadku trywialna (generowanie odpowiedzi 400), użycie tej klasy pozwala ogólnie oddzielić obsługę parametrów, która może obejmować rejestrowanie itp.

Jedno oczywiste rozwiązanie: weź ciąg, przekonwertuj na datę sam. W ten sposób możesz zdefiniować żądany format, wychwytywać wyjątki i ponownie przesłać lub dostosować wysyłany błąd. Do parsowania SimpleDateFormat powinien działać poprawnie.

Jestem pewien, że istnieją sposoby na przechwycenie procedur obsługi typów danych, ale być może w tym przypadku wystarczy trochę prostego kodu.

Ja też lubię, że StaxMan prawdopodobnie zaimplementuje ten QueryParam jako String, a następnie obsłuży konwersję, w razie potrzeby ponownie przesyłając.

Jeśli zachowanie specyficzne dla ustawień narodowych jest pożądanym i oczekiwanym zachowaniem, skorzystaj z następujących opcji, aby zwrócić błąd 400 BŁĘDNE ŻĄDANIE:

throw new WebApplicationException(Response.Status.BAD_REQUEST);

Więcej informacji znajdziesz w JavaDoc dla javax.ws.rs.core.Response.Status .

Dokumentacja @QueryParam mówi

„Typ T opisanego parametru, pola lub właściwości musi:

1) Bądź prymitywnym typem
2)
Posiadaj konstruktor, który akceptuje pojedynczy argument String 3) Posiadaj metodę statyczną o nazwie valueOf lub fromString, która akceptuje pojedynczy argument String (patrz na przykład Integer.valueOf (String))
4) zarejestrowana implementacja rozszerzenia SPI javax.ws.rs.ext.ParamConverterProvider JAX-RS, która zwraca instancję javax.ws.rs.ext.ParamConverter zdolną do konwersji typu „z ciągu” dla tego typu.
5) Bądź na liście, ustaw lub sortuj, gdzie T spełnia 2, 3 lub 4 powyżej. Powstała kolekcja jest tylko do odczytu. „

Jeśli chcesz kontrolować, jaka odpowiedź trafia do użytkownika, gdy parametru zapytania w postaci ciągu nie można przekonwertować na typ T, możesz zgłosić wyjątek WebApplicationException. Dropwizard zawiera następujące * klasy Param, których możesz użyć do swoich potrzeb.

BooleanParam, DateTimeParam, IntParam, LongParam, LocalDateParam, NonEmptyStringParam, UUIDParam. Zobacz https://github.com/dropwizard/dropwizard/tree/master/dropwizard-jersey/src/main/java/io/dropwizard/jersey/params

Jeśli potrzebujesz Joda DateTime, po prostu użyj Dropwizard DateTimeParam .

Jeśli powyższa lista nie odpowiada Twoim potrzebom, zdefiniuj własną, rozszerzając AbstractParam. Zastąp metodę analizy. Jeśli potrzebujesz kontroli nad treścią odpowiedzi na błąd, zastąp metodę błędu.

Dobry artykuł Cody Hale na ten temat znajduje się na stronie http://codahale.com/what-makes-jersey-interesting-parameter-classes/

import io.dropwizard.jersey.params.AbstractParam;

import java.util.Date;

import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;

public class DateParam extends AbstractParam<Date> {

    public DateParam(String input) {
        super(input);
    }

    @Override
    protected Date parse(String input) throws Exception {
        return new Date(input);
    }

    @Override
    protected Response error(String input, Exception e) {
        // customize response body if you like here by specifying entity
        return Response.status(Status.BAD_REQUEST).build();
    }
}

Konstruktor Date (String arg) jest przestarzały. Używałbym klas daty Java 8, jeśli korzystasz z Java 8. W przeciwnym razie zalecana jest data i godzina Joda.

To jest właściwie właściwe zachowanie. Jersey spróbuje znaleźć moduł obsługi dla danych wejściowych i spróbuje skonstruować obiekt na podstawie danych wejściowych. W takim przypadku spróbuje utworzyć nowy obiekt Date o wartości X podanej konstruktorowi. Ponieważ jest to nieprawidłowa data, zgodnie z umową Jersey zwróci 404.

Możesz przepisać i ustawić datę urodzenia jako ciąg znaków, a następnie spróbować przeanalizować, a jeśli nie dostaniesz tego, czego chcesz, możesz zgłosić dowolny wyjątek za pomocą dowolnego mechanizmu odwzorowywania wyjątków (istnieje kilka ).

Miałem do czynienia z tym samym problemem.

Chciałem złapać wszystkie błędy w centralnym miejscu i je przekształcić.

Poniżej znajduje się kod tego, jak sobie z tym poradziłem.

Utwórz następującą klasę, która implementuje ExceptionMapperi dodaje@Provider adnotację do tej klasy. Pozwoli to obsłużyć wszystkie wyjątki.

Przesłoń toResponsemetodę i zwróć obiekt odpowiedzi wypełniony dostosowanymi danymi.

//ExceptionMapperProvider.java
/**
 * exception thrown by restful endpoints will be caught and transformed here
 * so that client gets a proper error message
 */
@Provider
public class ExceptionMapperProvider implements ExceptionMapper<Throwable> {
    private final ErrorTransformer errorTransformer = new ErrorTransformer();

    public ExceptionMapperProvider() {

    }

    @Override
    public Response toResponse(Throwable throwable) {
        //transforming the error using the custom logic of ErrorTransformer 
        final ServiceError errorResponse = errorTransformer.getErrorResponse(throwable);
        final ResponseBuilder responseBuilder = Response.status(errorResponse.getStatus());

        if (errorResponse.getBody().isPresent()) {
            responseBuilder.type(MediaType.APPLICATION_JSON_TYPE);
            responseBuilder.entity(errorResponse.getBody().get());
        }

        for (Map.Entry<String, String> header : errorResponse.getHeaders().entrySet()) {
            responseBuilder.header(header.getKey(), header.getValue());
        }

        return responseBuilder.build();
    }
}

// ErrorTransformer.java
/**
 * Error transformation logic
 */
public class ErrorTransformer {
    public ServiceError getErrorResponse(Throwable throwable) {
        ServiceError serviceError = new ServiceError();
        //add you logic here
        serviceError.setStatus(getStatus(throwable));
        serviceError.setBody(getBody(throwable));
        serviceError.setHeaders(getHeaders(throwable));

    }
    private String getStatus(Throwable throwable) {
        //your logic
    }
    private Optional<String> getBody(Throwable throwable) {
        //your logic
    }
    private Map<String, String> getHeaders(Throwable throwable) {
        //your logic
    }
}

//ServiceError.java
/**
 * error data holder
 */
public class ServiceError {
    private int status;
    private Map<String, String> headers;
    private Optional<String> body;
    //setters and getters
}

Podejście 1: przez rozszerzenie klasy WebApplicationException

Utwórz nowy wyjątek, rozszerzając wyjątek WebApplicationException

public class RestException extends WebApplicationException {

         private static final long serialVersionUID = 1L;

         public RestException(String message, Status status) {
         super(Response.status(status).entity(message).type(MediaType.TEXT_PLAIN).build());
         }
}

Teraz rzucaj „RestException”, gdy jest to wymagane.

public static Employee getEmployee(int id) {

         Employee emp = employees.get(id);

         if (emp == null) {
                 throw new RestException("Employee with id " + id + " not exist", Status.NOT_FOUND);
         }
         return emp;
}

Możesz zobaczyć pełną aplikację pod tym linkiem .

Podejście 2: Implementuj ExceptionMapper

Poniższy program odwzorowujący obsługuje wyjątek typu „DataNotFoundException”

@Provider
public class DataNotFoundExceptionMapper implements
        ExceptionMapper<DataNotFoundException> {

    @Override
    public Response toResponse(DataNotFoundException ex) {
        ErrorMessage model = new ErrorMessage(ex.getErrorCode(),
                ex.getMessage());
        return Response.status(Status.NOT_FOUND).entity(model).build();
    }

}

Możesz zobaczyć pełną aplikację pod tym linkiem .

Tylko jako rozszerzenie odpowiedzi @Steven Lavine na wypadek, gdybyś chciał otworzyć okno logowania przeglądarki. Trudno mi było poprawnie zwrócić odpowiedź ( uwierzytelnianie MDN HTTP ) z filtra, na wypadek gdyby użytkownik nie został jeszcze uwierzytelniony

Pomogło mi to zbudować Odpowiedź, aby wymusić logowanie do przeglądarki, zwróć uwagę na dodatkową modyfikację nagłówków. Spowoduje to ustawienie kodu stanu na 401 i ustawienie nagłówka, który spowoduje, że przeglądarka otworzy okno dialogowe nazwy użytkownika / hasła.

// The extended Exception class
public class NotLoggedInException extends WebApplicationException {
  public NotLoggedInException(String message) {
    super(Response.status(Response.Status.UNAUTHORIZED)
      .entity(message)
      .type(MediaType.TEXT_PLAIN)
      .header("WWW-Authenticate", "Basic realm=SecuredApp").build()); 
  }
}

// Usage in the Filter
if(headers.get("Authorization") == null) { throw new NotLoggedInException("Not logged in"); }