Создание RESTful Web-сервиса

Этот урок освещает создание "hello world" RESTful web service с использованием Spring.

Что вы создадите

Вы создадите сервис, который будет принимать HTTP GET запросы на:

http://localhost:8080/greeting

а ответом будет JSON строка вида:

{"id":1,"content":"Hello, World!"}

Вы можете модифицировать сообщение ответа, если добавить к строке запроса параметр name:

http://localhost:8080/greeting?name=User

Значение параметра name заменяет значение по умолчанию "World" отображается в ответе:

{"id":1,"content":"Hello, User!"}

Что вам потребуется

• Примерно 15 минут свободного времени
• Любимый текстовый редактор или IDE
• JDK 6 и выше
• Gradle 1.11+ или Maven 3.0+
• Вы также можете импортировать код этого урока, а также просматривать web-страницы прямо из Spring Tool Suite (STS), собственно как и работать дальше из него.

Как проходить этот урок

Как и большинство уроков по Spring, вы можете начать с нуля и выполнять каждый шаг, либо пропустить базовые шаги, которые вам уже знакомы. В любом случае, вы в конечном итоге получите рабочий код.

Чтобы начать с нуля, перейдите в Настройка проекта.

Чтобы пропустить базовые шаги, выполните следующее:

• Загрузите и распакуйте архив с кодом этого урока, либо клонируйте из репозитория с помощью Git: git clone https://github.com/spring-guides/gs-rest-service.git
• Перейдите в каталог gs-rest-service/initial
• Забегая вперед, создайте класс, представляющий ресурс

Когда вы закончите, можете сравнить получившийся результат с образцом в gs-rest-service/complete.

Настройка проекта

Для начала вам необходимо настроить базовый скрипт сборки. Вы можете использовать любую систему сборки, которая вам нравится для сборки проетов Spring, но в этом уроке рассмотрим код для работы с Gradle и Maven. Если вы не знакомы ни с одним из них, ознакомьтесь с соответсвующими уроками Сборка Java-проекта с использованием Gradle или Сборка Java-проекта с использованием Maven.

Создание структуры каталогов

В выбранном вами каталоге проекта создайте следующую структуру каталогов; к примеру, командой mkdir -p src/main/java/hello для *nix систем:

+-- src
    +-- main
        +-- java
            +-- hello

Создание файла сборки Gradle

Ниже представлен начальный файл сборки Gradle. Файл pom.xml находится здесь. Если вы используете Spring Tool Suite (STS), то можете импортировать урок прямо из него.

build.gradle

buildscript {
    repositories {
        maven { url "http://repo.spring.io/libs-release" }
        mavenLocal()
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.1.4.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'

jar {
    baseName = 'gs-rest-service'
    version =  '0.1.0'
}

repositories {
    mavenLocal()
    mavenCentral()
    maven { url "http://repo.spring.io/libs-release" }
}

dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    testCompile("junit:junit")
}

task wrapper(type: Wrapper) {
    gradleVersion = '1.11'
}

Spring Boot gradle plugin предоставляет множество удобных возможностей:

• Он собирает все jar'ы в classpath и собирает единое, исполняемое "?ber-jar", что делает более удобным выполнение и доставку вашего сервиса
• Он ищет public static void main() метод, как признак исполняемого класса
• Он предоставляет встроенное разрешение зависимостей, с определенными номерами версий для соответсвующих Spring Boot зависимостей. Вы можете переопределить на любые версии, какие захотите, но он будет по умолчанию для Boot выбранным набором версий

Создание класса, представляющего ресурс

Теперь, когда вы настроили проект и систему сборки, вы можете создать ваш web-сервис.

Для начала подумаем о взаимодействии с сервисом.

Сервис будет обрабатывать GET запросы для /greeting, дополнительно - параметр name в строке запроса. GET запрос должен возвращать ответ со статусом 200 OK и JSON в теле, которое соответствует сообщению приветствия. он должен выглядеть таким образом:

{
    "id": 1,
    "content": "Hello, World!"
}

Поле id - это уникальный идентификатор приветствия, а content - текстовое представление.

Для модели представления приветствия вам необходимо создать класс, представляющего ресурс. Он представляет собой простой java-объект с полями, конструкторами и методами доступа к значениям id и content:

src/main/java/hello/Greeting.java

package hello;

public class Greeting {

    private final long id;
    private final String content;

    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}

Далее вы создаете контроллер ресурса, который будет обрабатывать эти приветствия.

Создание контроллера ресурса

Подход Spring при построении RESTful web-сервиса заключается в обработке HTTP-запросов контроллером. Эти компоненты легко опознаются по @RestController аннотации, а GreetingController ниже обрабатывает GET запросы для /greeting, возвращая новый экземпляр Greeting класса:

src/main/java/hello/GreetingController.java

package hello;

import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", required=false, defaultValue="World") String name) {
        return new Greeting(counter.incrementAndGet(),
                            String.format(template, name));
    }
}

Этот контроллер краток и прост, однако внутри происходит много чего. Давайте разберем его шаг за шагом.

Аннотация @RequestMapping гарантирует, что HTTP-запросы на /greeting будут сопоставлены greeting() методу.

@RequestParam связывает значение строкового параметра name запроса с параметром name метода greeting(). Этот строковый параметр запроса не required(не обязателен); если он отсутствует в запросе, то будет использовано defaultValue "World".

Реализация метода создает и возвращает новый Greeting объект с атрибутами id и content, основанными на следующем значении counter и форматированном значении name по шаблону template.

Ключевое отличие между традиционным MVC контроллером и контроллером RESTful web-сервиса выше в создании тела HTTP-ответа. Вместо того, чтобы опираться на view-технологию для рендеринга на серверной стороне сообщения приветствия в HTML, RESTful web-сервис контроллер просто заполняет и возвращает Greeting объект. Данные объекта будут записаны напрямую в HTTP-ответ как JSON.

Этот код использует новую в Spring 4 @RestController аннотацию, помечая класс как контроллер, где каждый метод возвращает объект вместо представления(view). Это сокращение для @Controller и @ResponseBody, вместе взятых.

Greeting объект должен быть конвертирован в JSON. Благодаря поддержке Spring HTTP конвертера, вам не требуется выполнять эту конвертацию вручную. Когда Jackson 2 в classpath, MappingJackson2HttpMessageConverter из Spring выбирается автоматически для конвертации экземпляра Greeting в JSON.

Создание приложения исполняемым

Несмотря на то, что возможно упаковать этот сервис в традиционный WAR файл для развертывания на стороннем сервере приложений, более простой подход, продемонстрированный ниже создает отдельное самостоятельное приложение. Вы упаковываете все в единый, исполняемый JAR-файл, который запускается через хорошо знакомый старый main() Java-метод. Попутно, вы используете поддержку Spring для встроенного Tomcat контейнера сервлетов как HTTP среду выполнения вместо развертывания на сторонний экземпляр.

src/main/java/hello/Application.java

package hello;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.context.annotation.ComponentScan;

@ComponentScan
@EnableAutoConfiguration
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

main() метод передает управление вспомогательному классу SpringApplication, где Application.class - аргумент его run() метода. Это сообщает Spring о чтении метаданных аннотации из Application и управлении ею как компонента в Spring application context.

Аннотация @ComponentScan говорит Spring'у рекурсивно искать в пакете hello и его потомках классы, помеченные прямо или косвенно Spring аннотацией @Component. Эта директива гарантирует, что Spring найдет и зарегистрирует GreetingController, потому что он отмечен @RestController, который, в свою очередь, является своего рода @Component аннотацией.

Аннотация @EnableAutoConfiguration переключает на приемлемое по умолчанию поведение, основанное на содержании вашего classpath. К примеру, т.к. приложение зависит от встраиваемой версии Tomcat (tomcat-embed-core.jar), Tomcat сервер установлен и сконфигурирован на приемлемое по умолчанию поведение от вашего имени. И т.к. приложение также зависит от Spring MVC (spring-webmvc.jar), Spring MVC DispatcherServlet сконфигурирован и зарегистрирован для вас - web.xml не нужен! Автоконфигурация полезный и гибкий механизм. Подробную информацию смотрите в API документации.

Сборка исполняемого JAR

Вы можете собрать единый исполняемый JAR-файл, который содержит все необходимые зависимости, классы и ресурсы. Это делает его легким в загрузке, версионировании и развертывании сервиса как приложения на протяжении всего периода разработки, на различных средах и так далее.

./gradlew build

Затем вы можете запустить JAR-файл:

java -jar build/libs/gs-rest-service-0.1.0.jar

Если вы используете Maven, вы можете запустить приложение, используя mvn spring-boot:run, либо вы можете собрать приложение с mvn clean package и запустить JAR примерно так:

java -jar target/gs-rest-service-0.1.0.jar

Запуск сервиса

Если вы используете Gradle, вы можете запустить ваш сервис из командной строки:

./gradlew clean build && java -jar build/libs/gs-rest-service-0.1.0.jar

Как вариант, вы можете запустить ваш сервис напрямую из Gradle примерно так:

./gradlew bootRun

Выходные данные отображены. Сервис должен быть поднят и запущен через несколько секунд.

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

Теперь, когда сервис поднят, поcетите http://localhost:8080/greeting и вы увидите:

{"id":1,"content":"Hello, World!"}

Добавьте строковый параметр name в запрос http://localhost:8080/greeting?name=User. Обратите внимание, как значение атрибута content изменится с "Hello, World!" на "Hello User!":

{"id":1,"content":"Hello, User!"}

Это изменение показывает, что аннотация @RequestParam в GreetingController работает, как и ожидалось. Параметру name было дано значение по умолчанию "World", но оно может быть всегда переопределено через строку запроса.

Обратите внимание, как значение атрибута id изменилось с 1 на 2. Это доказывает, что вы работаете с той же копией экземпляра GreetingController на протяжении нескольких запросов, и что это привело к увеличению значения поля counter при каждом вызове, как и ожидалось.

Итог

Поздравляем! Вы только что создали RESTful web-сервис с Spring.

С оригинальным текстом урока вы можете ознакомиться на spring.io.