Zero JSR311, @BodyParam...Parameters

Поскольку запросы с телом часто используются в приложениях веб-сервисов RESTful, система Zero расширяет JSR311 и определяет новые аннотации для общего использования.

• jakarta.ws.rs.BodyParam
• jakarta.ws.rs.SessionParam
• jakarta.ws.rs.StreamParam

Вышеупомянутые три аннотации определены системой Zero, поскольку они полезны при различных требованиях. В текущем руководстве будет описано использование @BodyParam. Существует несколько простых правил для @BodyParam:

• Для @BodyParam нет имени поля, вы должны использовать его напрямую.
• @BodyParam будет привязан к специальным типам Java, не все будут поддерживаться.

Демо-проекты:

• Standalone - 6083: up-rhea

1. Исходный код

Этот пример описывает отправку данных в систему Zero и их сериализацию в двух типах Vertx:

• io.vertx.core.json.JsonArray
• io.vertx.core.json.JsonObject

Код:

package up.god.micro.params;

import io.vertx.core.json.JsonArray;
import io.vertx.core.json.JsonObject;
import io.vertx.up.annotations.EndPoint;

import jakarta.ws.rs.BodyParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;

@EndPoint
@Path("/api")
public class BodyParamExecutor {

    @POST
    @Path("/param/body/json")
    public JsonObject sayJson(
            @BodyParam final JsonObject json
    ) {
        return json;
    }

    @POST
    @Path("/param/body/jarray")
    public JsonArray sayJArray(
            @BodyParam final JsonArray jarray
    ) {
        return jarray;
    }
}

2. Консоль

Затем вы увидите журналы в консоли следующим образом:

......
[ ZERO ] ( 2 Event ) The endpoint up.god.micro.params.BodyParamExecutor scanned 2 events of Event, \
    will be mounted to routing system.
......
[ ZERO ] ( Uri Register ) "/api/param/body/jarray" has been deployed by ZeroHttpAgent, Options = Route...
[ ZERO ] ( Uri Register ) "/api/param/body/json" has been deployed by ZeroHttpAgent, Options = Route...
......

3. Тестирование

3.1. JsonObject

URI: http://localhost:6083/api/param/body/json

Метод: POST

Запрос:

{
    "username":"Lang.Yu",
    "mobile":"15922X114XX"
}

Ответ:

{
    "data": {
        "username": "Lang.Yu",
        "mobile": "15922X114XX"
    }
}

3.2. JsonArray

URI: http://localhost:6083/api/param/body/jarray

Метод: POST

Запрос:

[
    {
        "username":"Lang.Yu",
        "mobile":"15922X114XX"
    }
]

Ответ:

{
    "data": [
        {
            "username": "Lang.Yu",
            "mobile": "15922X114XX"
        }
    ]
}

4. Резюме

Приведённые выше примеры показали, как читать тело запроса в системе Zero. Если формат вашего запроса недействителен, вы получите ошибку от системы Zero.

Например, вы предоставили следующий формат JSON:

{
    "username":"Lang.Yu",
    "mobile":"15922X114XX",
}

Приведённый выше формат JSON недействителен и не может быть преобразован в JsonObject. Вы получите следующую ошибку (400 Bad Request):

{
    "code": -60004,
    "message": "[ERR-60004] (JsonObjectSaber) Web Exception occus: (400) - Zero system detect ..."
}

Помните, что вы должны предоставить правильный формат данных системе Zero, иначе система Zero отклонит ваш запрос с вышеуказанными стандартными ошибками.