Потрібний @QueryParam у JAX-RS (і що робити за їх відсутності)

Я розгортаю компонент веб-служб на JBoss Application Server 7, використовуючи реалізацію RESTEasy JAX-RS .

Чи доступна анотація для оголошення необхідних, обов’язкових параметрів @QueryParam у JAX-RS ? А якщо ні, то який «стандартний» спосіб вирішення ситуацій, коли такі параметри відсутні?

Мої методи веб-сервісу (ресурсу) повертають строкові результати JSON при правильному виклику з усіма обов’язковими аргументами, але я не впевнений, що найкращий спосіб вказати абоненту, що потрібний параметр відсутній.

Гарне питання. На жаль (або, можливо, на щастя) у JAX-RS немає механізму, який би робив будь-які параметри обов'язковими. Якщо параметр не вказано, його значення буде, NULLі ваш ресурс повинен з цим відповідати. Я б рекомендував використовувати WebApplicationExceptionдля інформування своїх користувачів:

@GET
@Path("/some-path")
public String read(@QueryParam("name") String name) {
  if (name == null) {
    throw new WebApplicationException(
      Response.status(Response.Status.BAD_REQUEST)
        .entity("name parameter is mandatory")
        .build()
    );
  }
  // continue with a normal flow
}

Ви можете використовувати javax.validationанотації, щоб переконатись, що параметри є обов’язковими, анотуючи їх @javax.validation.constraints.NotNull. Див. Приклад для Джерсі та один для RESTeasy .

Отже, ваш метод просто став би:

@GET
@Path("/some-path")
public String read(@NotNull @QueryParam("name") String name) {
  String something = 
  // implementation
  return something;
}

Зверніть увагу, що виняток потім перекладається провайдером JAX-RS на якийсь код помилки. Зазвичай його можна замінити, зареєструвавши власну реалізацію javax.ws.rs.ext.ExceptionMapper<javax.validation.ValidationException>.

Це забезпечує централізований спосіб перекладу обов’язкового параметра на відповіді на помилки, і дублювати код не потрібно.

Я зіткнувся з тією ж проблемою і вирішив, що не хочу, щоб нульові перевірки шаблону gazillion були розкидані по моєму коду REST, тому ось це я вирішив зробити:

1. Створіть анотацію, яка спричиняє появу винятку, коли необхідний параметр не вказано.
2. Обробляти викинуте виняток так само, як я обробляю всі інші винятки, додані в мій код REST.

Для 1) я реалізував таку анотацію:

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Required
{
    // This is just a marker annotation, so nothing in here.
}

... та наступний JAX-RS ContainerRequestFilterдля його застосування:

import java.lang.reflect.Parameter;
import javax.ws.rs.QueryParam;
import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.container.ResourceInfo;
import javax.ws.rs.core.Context;
import javax.ws.rs.ext.Provider;

@Provider
public class RequiredParameterFilter implements ContainerRequestFilter
{
    @Context
    private ResourceInfo resourceInfo;

    @Override
    public void filter(ContainerRequestContext requestContext)
    {
        // Loop through each parameter
        for (Parameter parameter : resourceInfo.getResourceMethod().getParameters())
        {
            // Check is this parameter is a query parameter
            QueryParam queryAnnotation = parameter.getAnnotation(QueryParam.class);

            // ... and whether it is a required one
            if (queryAnnotation != null && parameter.isAnnotationPresent(Required.class))
            {
                // ... and whether it was not specified
                if (!requestContext.getUriInfo().getQueryParameters().containsKey(queryAnnotation.value()))
                {
                    // We pass the query variable name to the constructor so that the exception can generate a meaningful error message
                    throw new YourCustomRuntimeException(queryAnnotation.value());
                }
            }
        }
    }
}

Вам потрібно зареєструвати ContainerRequestFilterтак само, як і інші ваші @Providerкласи у вашій бібліотеці JAX-RS. Можливо, RESTEasy робить це за вас автоматично.

Для 2) я обробляю всі винятки під час виконання, використовуючи загальний JAX-RS ExceptionMapper:

import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

@Provider
public class MyExceptionMapper implements ExceptionMapper<RuntimeException>
{
    @Override
    public Response toResponse(RuntimeException ex)
    {
        // In this example, we just return the .toString() of the exception. 
        // You might want to wrap this in a JSON structure if this is a JSON API, for example.
        return Response
            .status(Response.Status.BAD_REQUEST)
            .entity(ex.toString())
            .build();
    }
}

Як і раніше, не забудьте зареєструвати клас у своїй бібліотеці JAX-RS.

Можливо , найпростіший спосіб полягає у використанні @Nonnullвід javax.annotationдосягнення цієї мети. Це дуже просто у використанні, оскільки все, що вам потрібно зробити, це додати його раніше, @QueryParamяк показано нижче.

Однак майте на увазі, що це призведе до значення, IllegalArgumentExceptionколи параметр має значення null, тому відповідь, яку ви надсилаєте назад, буде тим, що ви робите для виключення. Якщо ви не перехопите це, це буде 500 Server Errorнавіть незважаючи на те, що правильно відправити назад буде a 400 Bad Request. Ви можете перехопити IllegalArgumentExceptionта обробити його, щоб повернути належну відповідь.

Приклад:

import javax.annotation.Nonnull;
...

    @GET
    @Path("/your-path")
    public Response get(@Nonnull @QueryParam("paramName") String paramName) {
        ... 
    }

Повідомлення про помилку за замовчуванням, яке повертається абоненту, виглядає так:

{"timestamp": 1536152114437, "status": 500, "error": "Internal Server Error", "exception": "java.lang.IllegalArgumentException", "message": "Аргумент для параметра @Nonnull 'paramName' com /example/YourClass.get не повинен мати значення null "," path ":" / path / to / your-path "}