Введение в Spring Boot: создание простого REST API на Java

Spring Boot REST API

В этой статье мы напишем маленькое приложение на Spring Boot, которое предоставляет REST-сервисы.
Архитектура приложения будет стандартна и включать несколько слоев: dao, (service отсутствует) и controller. Все шаги по построению приложения просты. Код приложения можно скачать на GitHub.

Spring Initializr

Заготовку любого проекта на Spring Boot удобно взять на https://start.spring.io/. Здесь мы придумываем имя группы и имя артифакта будущего проекта на Maven, выбираем dependency, которые нам точно понадобятся и генерируем проект. А потом импортируем его в Eclipse как Maven-проект.

Инициализация Spring Boot проекта

Нам понадобятся зависимости WEB, JPA и H2.

Встроенную базу данных H2 прикрепляем потому, что ее проще использовать для демонстрационных целей: не придется устанавливать настоящую базу вроде MySQL, а также прописывать ее настройки.

Maven-зависимости

В результате получаем сгенерированный POM с такими зависимостями:

Хоть файл и сгенерирован, это не мешает нам добавлять в него новые зависимости при необходимости.

Слои (multi-layer architecture)

Импортированный проект выглядит так, плюс мы создали пакеты для моделей, dao и контроллеров (выделены красным):

Service-layer отсутствует потому, что приложение слишком простое, бизнес-логики тут нет.

Модель

Модель будет состоять из одного класса Person:

Person аннотирован как JPA-сущность, то есть при запуске приложения в базе данных будет создана таблица с таким именем и полями.

DAO-layer предназначен для работы с данными. У нас он состоит из одного бина PersonRepository.

Благодаря аннотации @Repository и интерфейсу JpaRepository DAO-layer предельно прост:

Мы создаем бин PersonRepository, аннотируя его с помощью @Repository. Полученный бин реализует все методы интерфейса, можно ничего не писать самостоятельно, если не нужны какие-то особые запросы к базе. А стандартные операции поиска, добавления и удаления тут все реализованы.

Service-layer опускаем, поскольку приложение простое. В контроллере будем использовать бин PersonRepository.

Контроллер

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

• Класс аннотирован @RestController и указан основной путь к запросам этого контроллера- “/persons”.
• С помощью аннотации @Autowired бин personRepository инжектирован в поле контроллера – теперь его можно использовать.

Тут два метода для получения данных (аннотации @GetMapping) и три – для редактирования. Все методы аннотированны:

• @GetMapping – для GET-запросов, получения Person
• @PostMapping – для POST-запросов, т.е. добавления Person
• @PutMapping – для PUT-запросов, редактирования Person
• @DeleteMapping – для DELETE-запросов, удаления Person

Возвращаем обычно ResponseEntity

, это более гибкий вариант, чем вернуть просто Person, поскольку для ResponseEntity можно установить Http-статус ответа – ResponseEntity.ok() – это 200 или ResponseEntity.status(201).

В методе body() передается возвращаемая сущность – в вышеприведенных методах это Person (либо список Person). Под капотом она конвертируется в JSON благодаря тому, что у нас стоит аннотация @RestController. Для конвертации под капотом Spring Boot использует библиотеку Jackson – она включена благодаря Maven-зависимости spring-boot-starter-web.

Если надо возвратить JSON с описанием ошибки, выбрасываем исключение. Например, если запрос на редактирование содержит id несуществующего Person, то выбрасываем EntityNotFoundException. Как обрабатывать исключения и кастомизировать JSON с ошибкой, описано в следующей статье.

Запуск

Для запуска Spring Boot приложения запускаем main() этого класса:

При этом будет запущен веб-сервер, отдельно его устанавливать и запускать не надо – это одно из преимуществ Spring Boot приложения.

Также не надо задавать пути для поиска бинов, они найдутся автоматически. Единственное, класс SpringBootRestApplication не надо перекладывать в подпакет, он должен быть на верхнем уровне иерархии, иначе с поиском бинов возникнут проблемы. Когда мы сгенерировали заготовку приложения, этот файл уже был именно там, где надо – перекладывать его не следует.

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

Осталось проверить, что методы контроллера работают. Составлять запросы будем с помощью бесплатного графического приложения Postman (но учтите, оно ресурсоемкое). Как писать тесты, рассмотрим в другой статье.

Добавление Person

Ответ, возвращается вновь добавленный Person с id=1:

Редактирование Person

Ответ, возвращается отредактированный Person с id=1 и name=’Jane’:

Получение Person

Ответ, возвращается Person:

Получение списка Person

Ответ, возвращается список, состоящий из одного элемента Person:

Удаление Person

Ответ, возвращается удаленный Person с id=1 и name=’Jane’:

Заключение

Мы написали маленькое приложение, предоставляющее REST-сервис. Как обрабатывать исключения описано в следующей части.

Spring Boot REST API: 5 комментариев

Есть ли статья по тестированию?

Будет в ближайшее время

Аесть статья, как кастомизировать response body таким образом, чтобы в нем можно было возвращать не все поля энтити? Например, я хочу исключить из респонза ID. Мне на ум приходит два варианта, оба убогие.
1. В теории, я могу сделать ResponseEntity и исключить из переопределения toString нужное поле, но я не хочу возвращать стринг, я хочу вернуть именно json. Есть возможность дефолтными методами это как-то сделать или необходимо только всякие манипуляции проводить с кастованием стрингов в жсон и обратно?
2. Кастомизировать Query, чтобы он возвращал только нужные поля. Но тогда возвращаемым значением будет Object, которые никак не получится кастовать к моему классу. Да и работать с таким значением невозможно.

1. Заботиться о преобразовании в объекта в JSON не надо, это на совести контроллера. Главное, чтобы у нас был объект с нужными полями.
2. Чтобы он был, надо использовать паттерн DTO – Data Transfer Object; то есть помимо объекта Person, создаете объект PersonDTO специально для передачи – он содержит ровно те поля, которые нужно отправить/принять на фронтенд.
В статье этого нет, т.к. случай рассмотрен примитивный. Но если бы было, возвращаемым значением метода getPerson()был бы:

Создание приложений с Spring Boot

Этот урок показывает пример того, как Spring Boot помогает вам ускорить и облегчить разработку приложений. Из учебных материалов вы увидите случаи использования Spring Boot. Если вы хотите создать проект на его основе, то посетите Spring Initializr, заполните онформацию о проекте, выберите опции и вы сможете загрузить файл сборки Maven, либо Gradle, либо как проект в виде zip-файла.

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

Вы создадите простое web-приложение с Spring Boot и добавите в него несколько полезных сервисов.

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

• Примерно 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-spring-boot.git
• Перейдите в каталог gs-spring-boot/initial

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

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

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

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

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

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

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

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

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

Узнайте, что вы можете делать с Spring Boot

Spring Boot предлагает быстрый путь для создания приложений. Он просматривает ваш classpath и бины, которые вы сконфигурировали, делает предположения о том, что нехватает и добавляет их. С Spring Boot вы можете сконцентрироваться больше на решении бизнес задач и меньше на инфраструктуру.

• Требуется Spring MVC? Некоторые определенные бины вам почти всегда необходимы и Spring Boot добавит для них автоматически. Spring MVC приложению также необходим сервлет контейнер, поэтому Spring Boot автоматически настроит встроенный Tomcat
• Требуется Jetty? Если так, то скорее всего вам не нужен Tomcat, а вместо него нужен встроенный Jetty. Spring Boot обработает эту задачу для вас
• Требуется Thymeleaf? Для этого несколько бинов должны всегда быть добавлены в контекст вашего приложения; Spring Boot добавит их для вас

Это лишь несколько примеров, которые предоставляет автоманическая настройка Spring Boot. В то же время, Spring Boot не заработает с вашими настройками. Например, если Thymeleaf в вашем classpath, то Spring Boot добавит SpringTemplateEngine в ваш контекст приложения автоматически. Но если вы определите свой собственный SpringTemplateEngine с вашими настройками, то Spring Boot не добавит его. Это останется под вашим контролем и потребует от вас немного усилий.

Создание простого web приложения

Теперь вы можете создать web контроллер для простого web приложения.

Класс помечен как @RestController , означая, что он готов к использованию Spring MVC для обработки запросов. RequestMapping соответствует / метода index() . При вызове из браузера или использовании curl в командной строке, метод возвращает чистый текст. Т.к. @RestController сочетает в себе @Controller и @ResponseBody , две аннотации в результате web запросов возвращают данные, а не представление.

Создание Application класса

Здесь вы создаете Application класс с компонентами:

• @Configuration помечает класс как источник определения бинов для контекста приложения
• @EnableAutoConfiguration говорит Spring Boot о запуске добавления бинов в соответствии с содержанием classpath и других бинов, а также различных параметров настроек
• Обычно вы добавили бы @EnableMVC для Spring MVC, но Spring Boot добавляет её автоматически, когда видит spring-webmvc в classpath. Этот флаг помечает приложение как web приложение и активирует ключевые действия, такие как настройка DispatcherServlet
• @ComponentScan говорит Spring о том, чтобы просмотреть все компоненты, конфигурации и сервисы в пакете hello , сто позволяет ему найти HelloController

Метод main() используется Spring Boot методом SpringApplication.run() для запуска приложения. Вы обратили внимание, что нет ни одной строчки на XML? Файла web.xml нет вообще. Это приложение на 100% из чистой Java и вы ничего не делали для настройки какого-либо инструмента или инфраструктуры.

Метод run() возвращает ApplicationContext и этому приложению отдаются все бины, которые были созданы вашим приложением или автоматически добавлены благодаря Spring Boot. Метод сортирует бины и печатает их имена.

Запуск приложения

Для запуска приложения выполните:

Если вы используете Maven, то:

Вы должны увидеть примерно такое:

Вы можете явно видеть org.springframework.boot.autoconfigure бины. А также tomcatEmbeddedServletContainerFactory .

Добавление сервисов бизнес-уровня

Если вы создаете web-сайт для вашего бизнеса, то вам скорее всего необходимо добавить некоторые сервисы для управления. Spring Boot предоставляет несколько таких “из коробки” в одном из своих модулей, таких как состояние, аудит, бины и другие.

Добавьте это в список зависимостей вашего файла сборки:

Если вы используете Maven, то добавьте это в список зависимостей:

Затем перезапустите приложение:

Если вы используете Maven, то:

Вы увидите новый набор RESTful точек выхода, добавленных в приложение. Это сервисы управления, предоставленные Spring Boot:

это легко проверить по состоянию приложения:

Вы можете попытаться вызвать завершение работы через curl:

Т.к. мы не включили его, запрос блокирован, потому что его не существует.

Более подробную информацию о каждом из этих REST сервисов и о том, как вы можете настраивать под себя в application.properties , вы можете прочитать в документации.

Просмотр Spring Boot starters

Последний пример показал как Spring Boot упрощает инициализацию бинов, о которых вы не знаете, что они вам нужны. И он показал, как подклюсить удобные для управления сервисы.

Но Spring Boot делает ещё большее. Он поддерживает не только традиционное использование WAR файлов, но также сборку исполняемых JAR файлов, благодаря модулю загрузчика Spring Boot. Различные уроки демонстрируют эту двойную поддержку через spring-boot-gradle-plugin и spring-boot-maven-plugin .

ко всему прочему, Spring Boot поддерживает Groovy, позволяя вам создавать Spring MVC приложения в небольшом и единственном файле.

Создайте новый файл app.groovy и поместите в него приведенный ниже код:

Давайте проверим, что получилось:

Spring Boot динамически добавляет аннотации к вашему коду и использует Groovy Grape для подтягивания необходимых для запуска приложения библиотек. Смотрите документацию, если хотите копнуть шлубже.

Поздравляем! Вы только что создали простое web приложени с использованием Spring Boot и изучили как нарастить ваш темп разработки. вы также настроили некоторые удобные сервисы. Это только малая часть того, что может делать Spring Boot.

Building a RESTful Web Service

This guide walks you through the process of creating a “Hello, World” RESTful web service with Spring.

What You Will Build

You will build a service that will accept HTTP GET requests at http://localhost:8080/greeting .

It will respond with a JSON representation of a greeting, as the following listing shows:

You can customize the greeting with an optional name parameter in the query string, as the following listing shows:

The name parameter value overrides the default value of World and is reflected in the response, as the following listing shows:

What You Need

About 15 minutes

A favorite text editor or IDE

You can also import the code straight into your IDE:

How to complete this guide

Like most Spring Getting Started guides, you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.

To start from scratch, move on to Starting with Spring Initializr.

To skip the basics, do the following:

Download and unzip the source repository for this guide, or clone it using Git: git clone https://github.com/spring-guides/gs-rest-service.git

cd into gs-rest-service/initial

When you finish, you can check your results against the code in gs-rest-service/complete .

Starting with Spring Initializr

For all Spring applications, you should start with the Spring Initializr. The Initializr offers a fast way to pull in all the dependencies you need for an application and does a lot of the setup for you. This example needs only the Spring Web dependency.

The following listing shows the pom.xml file that is created when you choose Maven:

The following listing shows the build.gradle file that is created when you choose Gradle:

Create a Resource Representation Class

Now that you have set up the project and build system, you can create your web service.

Begin the process by thinking about service interactions.

The service will handle GET requests for /greeting , optionally with a name parameter in the query string. The GET request should return a 200 OK response with JSON in the body that represents a greeting. It should resemble the following output:

The id field is a unique identifier for the greeting, and content is the textual representation of the greeting.

To model the greeting representation, create a resource representation class. To do so, provide a plain old Java object with fields, constructors, and accessors for the id and content data, as the following listing (from src/main/java/com/example/restservice/Greeting.java ) shows:

Create a Resource Controller

In Spring’s approach to building RESTful web services, HTTP requests are handled by a controller. These components are identified by the @RestController annotation, and the GreetingController shown in the following listing (from src/main/java/com/example/restservice/GreetingController.java ) handles GET requests for /greeting by returning a new instance of the Greeting class:

This controller is concise and simple, but there is plenty going on under the hood. We break it down step by step.

The @GetMapping annotation ensures that HTTP GET requests to /greeting are mapped to the greeting() method.

@RequestParam binds the value of the query string parameter name into the name parameter of the greeting() method. If the name parameter is absent in the request, the defaultValue of World is used.

The implementation of the method body creates and returns a new Greeting object with id and content attributes based on the next value from the counter and formats the given name by using the greeting template .

A key difference between a traditional MVC controller and the RESTful web service controller shown earlier is the way that the HTTP response body is created. Rather than relying on a view technology to perform server-side rendering of the greeting data to HTML, this RESTful web service controller populates and returns a Greeting object. The object data will be written directly to the HTTP response as JSON.

This code uses Spring @RestController annotation, which marks the class as a controller where every method returns a domain object instead of a view. It is shorthand for including both @Controller and @ResponseBody .

The Greeting object must be converted to JSON. Thanks to Spring’s HTTP message converter support, you need not do this conversion manually. Because Jackson 2 is on the classpath, Spring’s MappingJackson2HttpMessageConverter is automatically chosen to convert the Greeting instance to JSON.

@SpringBootApplication is a convenience annotation that adds all of the following:

@Configuration : Tags the class as a source of bean definitions for the application context.

@EnableAutoConfiguration : Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, if spring-webmvc is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up a DispatcherServlet .

@ComponentScan : Tells Spring to look for other components, configurations, and services in the com/example package, letting it find the controllers.

The main() method uses Spring Boot’s SpringApplication.run() method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.

Build an executable JAR

You can run the application from the command line with Gradle or Maven. You can also build a single executable JAR file that contains all the necessary dependencies, classes, and resources and run that. Building an executable jar makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.

If you use Gradle, you can run the application by using ./gradlew bootRun . Alternatively, you can build the JAR file by using ./gradlew build and then run the JAR file, as follows:

If you use Maven, you can run the application by using ./mvnw spring-boot:run . Alternatively, you can build the JAR file with ./mvnw clean package and then run the JAR file, as follows:

Logging output is displayed. The service should be up and running within a few seconds.

Test the Service

Now that the service is up, visit http://localhost:8080/greeting , where you should see:

Provide a name query string parameter by visiting http://localhost:8080/greeting?name=User . Notice how the value of the content attribute changes from Hello, World! to Hello, User! , as the following listing shows:

This change demonstrates that the @RequestParam arrangement in GreetingController is working as expected. The name parameter has been given a default value of World but can be explicitly overridden through the query string.

Notice also how the id attribute has changed from 1 to 2 . This proves that you are working against the same GreetingController instance across multiple requests and that its counter field is being incremented on each call as expected.

Summary

Congratulations! You have just developed a RESTful web service with Spring.

See Also

The following guides may also be helpful:

Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.

Get the Code

Projects

Table of contents

Get ahead

VMware offers training and certification to turbo-charge your progress.

Get support

Spring Runtime offers support and binaries for OpenJDK™, Spring, and Apache Tomcat® in one simple subscription.

Upcoming events

App modernization. Kubernetes. Microservices.

The best Cloud-Native Java content brought directly to you.