Создание 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), то можете импортировать урок прямо из него.
pom.xml
, вы найдете, что указана версия для maven-compiler-plugin.
В общем, это не рекомендуется делать. В данном случае он предназначен для решения проблем с нашей CI системы,
которая по умолчанию имеет старую(до Java 5) версию этого плагина.
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;
}
}
Greeting
в JSON.
Далее вы создаете контроллер ресурса, который будет обрабатывать эти приветствия.
Создание контроллера ресурса
Подход 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()
методу.
GET
, PUT
, POST
и т.д.,
потому то @RequestMapping
сопоставляет все HTTP-операции по умолчанию.
Использование @RequestMapping(method=GET)
определяет это сопоставление.
@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
mvn clean package && java -jar target/gs-rest-service-0.1.0.jar
.
Как вариант, вы можете запустить ваш сервис напрямую из Gradle примерно так:
./gradlew bootRun
mvn spring-boot:run
.Выходные данные отображены. Сервис должен быть поднят и запущен через несколько секунд.
Тестирование сервиса
Теперь, когда сервис поднят, по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.
comments powered by Disqus