Рубрики
Без рубрики

Создание API с рамками Spark Java

Краткий учебник о том, как создать веб-API с использованием Spark Framework для Java.

Автор оригинала: baeldung.

Создание API с рамками Spark Java

1. Введение

В этой статье мы быстро ввеем в Искровая . Spark framework является быстрой веб-инфраструктурой разработки, вдохновленной платформой Sinatra для Ruby, и построена на философии Java 8 Lambda Expression, что делает ее менее многословной, чем большинство приложений, написанных в других java-фреймворках.

Это хороший выбор, если вы хотите иметь Узел.js как опыт при разработке веб-API или микрослужб на Java. С Spark вы можете иметь API REST, готовый обслуживать JSON менее чем в десяти строках кода.

Мы быстро начнем с примера “Hello World”, за которым последует простой API REST.

2. Мейвен зависимостей

2.1. Искра Рамочная

Включите следующие Maven зависимости в вашей пом.xml :


    com.sparkjava
    spark-core
    2.5.4

Вы можете найти последнюю версию Spark на Мавен Центральный .

2.2. Библиотека Гсона

В различных местах в примере мы будем использовать библиотеку Gson для операций JSON. Чтобы включить Gson в свой проект, включите эту зависимость в свой пом.xml :


    com.google.code.gson
    gson
    2.8.0

Вы можете найти последнюю версию Gson на Мавен Центральный .

3. Начало работы с Spark Framework

Давайте рассмотрим основные строительные блоки приложения Spark и продемонстрируем быстрый веб-сервис.

3.1. Маршруты

Веб-службы в Spark Java построены на маршрутах и их обработчиках. Маршруты являются важными элементами в Spark. В соответствии с документация , каждый маршрут состоит из трех простых частей – глагол , путь , и обратный вызов .

  1. глагол является методом, соответствующим методу HTTP. Методы глагола включают: получить, пост, положить, удалить, голова, след, подключиться, и Параметры
  2. путь (также называемый шаблон маршрута) определяет, какой URI (ы) маршрут должен слушать и предоставлять ответ на
  3. обратный вызов является функцией обработчика, которая вызывается для данного глагола и пути для генерации и возврата ответа на соответствующий запрос HTTP. Обратный вызов принимает объект запроса и объект ответа в качестве аргументов

Здесь мы покажем основную структуру маршрута, который использует получить глагол:

get("/your-route-path/", (request, response) -> {
    // your callback code
});

3.2. Привет мир API

Давайте создадим простой веб-сервис, который имеет два маршрута для GET запросов и возвращает “Привет” сообщения в ответ. Эти маршруты используют получить метод, который является статическим импортом из класса искра. Искра :

import static spark.Spark.*;

public class HelloWorldService {
    public static void main(String[] args) {
 
        get("/hello", (req, res)->"Hello, world");
        
        get("/hello/:name", (req,res)->{
            return "Hello, "+ req.params(":name");
        });
    }
}

Первый аргумент в получить метод является маршрутом для маршрута. Первый маршрут содержит статический путь, представляющий только один URI ( “/привет” ).

Путь второго маршрута ( “/привет/:имя” ) содержит заполнитель для “имя” параметр, обозначаемый префацией параметра с толстой кишкой («).). Этот маршрут будет вызываться в ответ на запросы GET в ИРИС, такие как “/привет/Джо” и “/привет/Мария” .

Второй аргумент в получить метод является выражение лямбды придавая этой структуре функциональный вкус программирования.

Выражение lambda имеет запрос и ответ в качестве аргументов и помогает вернуть ответ. Мы положу нашу логику контроллера в выражение lambda для маршрутов REST API, как мы увидим позже в этом учебнике.

3.3. Тестирование API Hello World

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

Рассмотрим запрос и ответ на первый маршрут:

просьба:

GET http://localhost:4567/hello

ответ:

Hello, world

Давайте попробуем второй маршрут, пройдя имя параметр на своем пути:

просьба:

GET http://localhost:4567/hello/baeldung

ответ:

Hello, baeldung

Посмотрите, как размещение текста “baeldung” в URI использовался для того, чтобы соответствовать шаблону маршрута “/привет/:имя” – вызывая вызов функции обработчика обратного вызова второго маршрута.

4. Проектирование службы RESTful

В этом разделе мы разработать простой веб-сервис REST для следующих Пользователь сущность:

public class User {
    private String id;
    private String firstName;
    private String lastName;
    private String email;

    // constructors, getters and setters
}

4.1. Маршруты

Давайте перечислим маршруты, которые составляют наш API:

  • GET/пользователи – получить список всех пользователей
  • GET/users/:id – получить пользователя с учетом ID
  • POST/пользователи/:id – добавить пользователя
  • PUT/пользователи/:id – редактировать конкретного пользователя
  • OPTIONS/users/:id – проверьте, существует ли пользователь с данном идентификатором
  • DELETE/users/:id – удалить конкретного пользователя

4.2. Служба пользователей

Ниже приведена Служба пользователей интерфейс, объявляющий операции CRUD для Пользователь сущность:

public interface UserService {
 
    public void addUser (User user);
    
    public Collection getUsers ();
    public User getUser (String id);
    
    public User editUser (User user) 
      throws UserException;
    
    public void deleteUser (String id);
    
    public boolean userExist (String id);
}

Для демонстрационных целей мы предоставляем Карта реализации этого Служба пользователей интерфейс в коде GitHub для имитации настойчивости. Вы можете предоставить свою собственную реализацию с базой данных и уровень настойчивости по вашему выбору.

4.3. Структура реагирования JSON

Ниже приведена структура ответов JSON, используемая в нашем сервисе REST:

{
    status: 
    message: 
    data: 
}

статус значение поля может быть либо УСПЕХ или ОШИБКА . данные поле будет содержать представление JSON данных возврата, таких как Пользователь или коллекция Пользователи .

Когда данные не возвращаются, или если статус это ОШИБКА , мы заселим сообщение поле для передачи причины ошибки или отсутствия данных о возврате.

Давайте рассмотрим вышеупомятую структуру JSON с помощью класса Java:

public class StandardResponse {
 
    private StatusResponse status;
    private String message;
    private JsonElement data;
    
    public StandardResponse(StatusResponse status) {
        // ...
    }
    public StandardResponse(StatusResponse status, String message) {
        // ...
    }
    public StandardResponse(StatusResponse status, JsonElement data) {
        // ...
    }
    
    // getters and setters
}

где СтатусОтвет является enum определяется как ниже:

public enum StatusResponse {
    SUCCESS ("Success"),
    ERROR ("Error");
 
    private String status;       
    // constructors, getters
}

5. Внедрение услуг RESTful

Теперь давайте реализуем маршруты и обработчики для нашего API REST.

5.1. Создание контроллеров

Следующий класс Java содержит маршруты для нашего API, включая глаголы и пути, а также наброски обработчиков для каждого маршрута:

public class SparkRestExample {
    public static void main(String[] args) {
        post("/users", (request, response) -> {
            //...
        });
        get("/users", (request, response) -> {
            //...
        });
        get("/users/:id", (request, response) -> {
            //...
        });
        put("/users/:id", (request, response) -> {
            //...
        });
        delete("/users/:id", (request, response) -> {
            //...
        });
        options("/users/:id", (request, response) -> {
            //...
        });
    }
}

Мы покажем полную реализацию каждого обработчика маршрутов в следующих подразделах.

5.2. Добавить пользователя

Ниже приведена почтовый обработчик реакции метода, который добавит Пользователь :

post("/users", (request, response) -> {
    response.type("application/json");
    User user = new Gson().fromJson(request.body(), User.class);
    userService.addUser(user);

    return new Gson()
      .toJson(new StandardResponse(StatusResponse.SUCCESS));
});

Примечание: В этом примере представительство JSON Пользователь объект передается как необработанный корпус запроса POST.

Давайте проверьте маршрут:

просьба:

POST http://localhost:4567/users
{
    "id": "1012", 
    "email": "[email protected]", 
    "firstName": "Mac",
    "lastName": "Mason1"
}

ответ:

{
    "status":"SUCCESS"
}

5.3. Получить все пользователи

Ниже приведена получить обработчик реакции метода, который возвращает всех пользователей из Служба пользователей :

get("/users", (request, response) -> {
    response.type("application/json");
    return new Gson().toJson(
      new StandardResponse(StatusResponse.SUCCESS,new Gson()
        .toJsonTree(userService.getUsers())));
});

Теперь давайте проверьте маршрут:

просьба:

GET http://localhost:4567/users

ответ:

{
    "status":"SUCCESS",
    "data":[
        {
            "id":"1014",
            "firstName":"John",
            "lastName":"Miller",
            "email":"[email protected]"
        },
        {
            "id":"1012",
            "firstName":"Mac",
            "lastName":"Mason1",
            "email":"[email protected]"
        }
    ]
}

5.4. Получить пользователя id

Ниже приведена получить обработчик реакции метода, который возвращает Пользователь с данной id :

get("/users/:id", (request, response) -> {
    response.type("application/json");
    return new Gson().toJson(
      new StandardResponse(StatusResponse.SUCCESS,new Gson()
        .toJsonTree(userService.getUser(request.params(":id")))));
});

Теперь давайте проверьте маршрут:

просьба:

GET http://localhost:4567/users/1012

ответ:

{
    "status":"SUCCESS",
    "data":{
        "id":"1012",
        "firstName":"Mac",
        "lastName":"Mason1",
        "email":"[email protected]"
    }
}

5.5. Редактировать пользователя

Ниже приведена положить обработчик реакции метода, который редактирует пользователя, id поставляется в шаблоне маршрута:

put("/users/:id", (request, response) -> {
    response.type("application/json");
    User toEdit = new Gson().fromJson(request.body(), User.class);
    User editedUser = userService.editUser(toEdit);
            
    if (editedUser != null) {
        return new Gson().toJson(
          new StandardResponse(StatusResponse.SUCCESS,new Gson()
            .toJsonTree(editedUser)));
    } else {
        return new Gson().toJson(
          new StandardResponse(StatusResponse.ERROR,new Gson()
            .toJson("User not found or error in edit")));
    }
});

Примечание: В этом примере данные передаются в необработанный корпус запроса POST как объект JSON, названия свойств которого соответствуют полям Пользователь объект, который будет отредактирован.

Давайте проверьте маршрут:

просьба:

PUT http://localhost:4567/users/1012
{
    "lastName": "Mason"
}

ответ:

{
    "status":"SUCCESS",
    "data":{
        "id":"1012",
        "firstName":"Mac",
        "lastName":"Mason",
        "email":"[email protected]"
    }
}

5.6. Удалить пользователя

Ниже приведена удалить обработчик ответа метода, который удалит Пользователь с данной id :

delete("/users/:id", (request, response) -> {
    response.type("application/json");
    userService.deleteUser(request.params(":id"));
    return new Gson().toJson(
      new StandardResponse(StatusResponse.SUCCESS, "user deleted"));
});

Теперь давайте проверьте маршрут:

просьба:

DELETE http://localhost:4567/users/1012

ответ:

{
    "status":"SUCCESS",
    "message":"user deleted"
}

5.7. Проверьте, существует ли пользователь

варианты метод является хорошим выбором для условной проверки. Ниже приведена варианты обработчик реакции метода, который проверит, является ли Пользователь с данной id Существует:

options("/users/:id", (request, response) -> {
    response.type("application/json");
    return new Gson().toJson(
      new StandardResponse(StatusResponse.SUCCESS, 
        (userService.userExist(
          request.params(":id"))) ? "User exists" : "User does not exists" ));
});

Теперь давайте проверьте маршрут:

просьба:

OPTIONS http://localhost:4567/users/1012

ответ:

{
    "status":"SUCCESS",
    "message":"User exists"
}

6. Заключение

В этой статье мы кратко о представлении о системе Spark для быстрого веб-разработки.

Эта структура в основном продвигается для создания микрослужб в Java. Узел.js разработчики со знанием Java, которые хотят использовать библиотеки, построенные на библиотеках JVM, должны чувствовать себя как дома, используя эту структуру.

И, как всегда, вы можете найти все источники для этого учебника в Проект Github .