Лучшая практика при отправке запроса в JAX-RS

Question

Я видел несколько различных соглашений относительно кода статуса ответа при отправке запроса с использованием JAX-RS.

Я видел это:

  Response.ok(//content or object).build();

Первоначально я думал, что это неправильно, поскольку код состояния 200 просто означает «хорошо», что является широким термином, но, поскольку у нас есть «Размещено», я думаю, что 201 будет лучше, так как он также возвращает URI элемент внутри заголовка

 Response.created(//content or object).build();

вот что я хочу достичь:

  @POST
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public Response createUser(String content) throws CityNotFoundException
{
    ReceivedCreateUser receivedUser = gson.fromJson(content, ReceivedCreateUser.class);
    User createdUser = userFacade.createUser(receivedUser.name,
                                             receivedUser.email,
                                             receivedUser.password,
                                             receivedUser.city,
                                             receivedUser.gender,
                                             receivedUser.dateOfBirth);
    if(createdUser == null){
        throw new WebApplicationException(Response.Status.NOT_FOUND);
    }
    return Response.ok(gson.toJson(UserDTO.basic(createdUser))).build();

}

Я хочу добавить объект в ответ, но created принимает только URI, а не объекты.

Answer 1

Возможность возврата 201 по запросу POST в значительной степени зависит от его функциональности. Если ваша конечная точка создает новую сущность в системе, то 201 будет подходящим вариантом, но POST также часто используется для выполнения поискового запроса с большими наборами опций. В этом случае было бы желательно 200 или 204 в случае результатов или без результатов.

Но чтобы вернуть сущность с POST и ответом 201, вы могли бы сделать что-то похожее на это:

@POST
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public Response createUser(String content) throws CityNotFoundException
{
    ReceivedCreateUser receivedUser = gson.fromJson(content, ReceivedCreateUser.class);
    User createdUser = userFacade.createUser(receivedUser.name,
                                         receivedUser.email,
                                         receivedUser.password,
                                         receivedUser.city,
                                         receivedUser.gender,
                                         receivedUser.dateOfBirth);
    if(createdUser == null){
       throw new WebApplicationException(Response.Status.NOT_FOUND);
    }
    return Response
       .created(new Uri("http://example.org"))
       .entity(gson.toJson(UserDTO.basic(createdUser)))
       .build();
}

Answer 2

Тип ответа не лучший возврат для клиентов и автоматической документации, такой как Swagger, потому что он не имеет слишком много информации. Я предпочитаю, в частности, возвращать сущность напрямую, как кричать:

@POST
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public UserDTO createUser(String content) throws CityNotFoundException
{
    ReceivedCreateUser receivedUser = gson.fromJson(content, ReceivedCreateUser.class);
    User createdUser = userFacade.createUser(receivedUser.name,
                                         receivedUser.email,
                                         receivedUser.password,
                                         receivedUser.city,
                                         receivedUser.gender,
                                         receivedUser.dateOfBirth);
    if(createdUser == null){
       throw new WebApplicationException(Response.Status.NOT_FOUND);
    }

    return UserDTO.basic(createdUser);
}

Это вернет Status Code = 200, но есть много способов изменить его на 201. Мой фаворит переопределяет javax.ws.rs.container.ContainerResponseFilter.filter(...), как показано ниже:

import static org.springframework.http.HttpMethod.POST;
import static org.springframework.http.HttpStatus.CREATED;
import static org.springframework.http.HttpStatus.OK;

import java.io.IOException;

import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerResponseContext;
import javax.ws.rs.container.ContainerResponseFilter;
import javax.ws.rs.ext.Provider;

@Provider
public class LocalContainerResponseFilter implements ContainerResponseFilter {

    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext)
        throws IOException {
        if (POST.name().equals(requestContext.getMethod()) && OK.value() == responseContext.getStatus()) {
            responseContext.setStatus(CREATED.value());
        }
    }

}

Это изменит поведение JAX-RS, возвращая 201 для всех POST, в порядке.

Ещё 2 подсказки:

1. вы можете изменить параметр (содержимое строки) на (содержимое ReceivedCreateUser); и

2. Вы можете поместить код "throw new WebApplicationException" внутри userFacade.createUser(...)

Answer 3

Response.ok () не всегда в порядке, это может показать, что запрос был выполнен, но на самом деле ресурс не был создан. Возможно, вы захотите использовать Response.created или Response.accepted. Как и в этой ссылке , вы можете видеть, что все зависит от бизнес-логики вашего бэкэнда.