Rest controller spring что это
Подготовка к Spring Professional Certification. Spring REST
Сегодняшняя статья рассмотрит основные вопросы про REST в Spring. Она будет особенно полезна для начинающих программистов.
Официальный гид от Pivotal, в котором написано про темы для подготовки.
Spring REST — это часть Spring MVC. Поэтому многое из Spring MVC будет применяться в REST и наоборот. Для более подробного ознакомления со Spring MVC можно прочитать эту статью.
Чтобы понять концепцию REST, нужно разобрать акроним на его составляющие:
REST это передача состояний ресурса между сервером и клиентом.
Ресурс в REST — это все, что может быть передано между клиентом и сервером.
Вот несколько примеров ресурсов:
Самые часто-используемые обозначаются аббревиатурой CRUD:
По умолчанию REST не защищен.
Вы можете настроить безопасность с помощью Basic Auth, JWT, OAuth2
Это операции, которые не модифицируют ресурсы. Вот их список:
Идемпотентые методы — это методы, при каждом вызове которых результат будет одинаковый.
То есть, результат после 1 вызова такого метода будет такой же, как и результат после 10 вызовов этого метода.
Это важно для отказоустойчевого API. Предположим, что клиент хочет обновить ресурс с помощью POST-запроса? Если POST не идемпотентный метод, то при многократном вызове возникнут непредвиденные обновления ресурса. Используя идемпотентные методы, вы ограждаете себя от многих ошибок.
Да. REST хорошо масштабируется потому что он не хранит состояние.
Это значит что он не хранит информацию о пользовательских сессиях на сервере.
Информация о клиенте не должна хранится на стороне сервера, а должна передаваться каждый раз туда, где она нужна. Вот что значит ST в REST, State Transfer. Вы передаете состояние, а не храните его на сервере.
REST также интероперабельный — это значит, что на нем могут взаимодействовать разные программы написанные на разных языках. Это исходит из 2ух факторов:
HttpMessageConverter конвертирует запрос в объект и наоборот.
Spring имеет несколько реализаций этого интерфейса, а вы можете создать свою.
В этом случае DispatcherServlet не использует Model и View.
В REST вообще не существует Model и View. Есть только данные, поставляемые контроллером, и представление ресурса, когда сообщение конвертируется из медиа-типа(json, xml. ) в объект.
BufferedImageHttpMessageConverter — конвертирует BufferedImage в(из) код изображения.
Jaxb2RootElementHttpMessageConverter — конвертирует xml в(из) объект, помеченный jaxb2 аннотациями. Регистрируется, если jaxb2 находится в classpath.
MappingJackson2HttpMessageConverter — конвертирует JSON в(из) объект. Регистрируется, если Jackson 2 находится в classpath.
StringHttpMessageConverter — конвертирует все медиа-файлы в text/plain.
Теперь она используется только для указания URI до класса-контроллера.
Это более узкие аннотации для маппинга http-методов.
Все написанное ниже характерно также и для других аннотаций.
Аннотация @GetMapping — это просто аннотация которая содержит @RequestMapping(method = RequestMethod.GET).
Она также позволяет более глубоко настроить метод-обработчик.
Ее параметры(они конвертируются в аналогичные параметры @RequestMapping):
consumes — тип принимаемых данных. Используется в REST
По умолчанию аннотация принимает путь до метода.
@GetMapping(«managers») = @GetMapping(path = «managers»)
Эта аннотация используется для того, чтобы методы обработчики могли получить параметры из http-запроса.
Эта аннотация получает определенную часть из URI.
POST — 200 OK, 201 Created, 204 No Content
PUT — 200 OK, 201 Created, 204 No Content
DELETE — 204 No Content, 202 Accepted
Она позволяет устанавливать код ответа. Обычно Spring сам устанавливает нужный код ответа, но бывают моменты, когда это нужно переопределить.
Вместо использования аннотации можно возвращать ResponseEntity и вручную устанавливать код ответа.
Не рекомендуется использовать ResponseEntity и @ReponseStatus вместе.
Это специальный класс, который представляет http-ответ. Он содержит тело ответа, код состояния, заголовки. Мы можем использовать его для более тонкой настройки http-ответа.
Он является универсальным типом, и можно использовать любой объект в качестве тела:
Вы можете использовать аннотацию @RequestBody на параметре метода, для того чтобы тело запроса конвертировалось в этот параметр.
RestTemplate это специальный клиент в Spring для отправки http-запросов. Он предоставляет удобные API для легкого вызова конечных точек REST’а в одну строку.
Более подробно об использовании можно узнать в этой статье.
Построение REST сервисов с помощью Spring
REST быстро стал де-факто стандартом для создания web-сервисов, поскольку таким они легки для создания и обработки.
Существует большое обсуждение о том, как REST вписывается в мир микросервисов, но в этом уроке просто описывается создание RESTful сервисов.
Почему REST? Из REST на практике, заимствуется фраза Martin Flower: «Понятие того, что web является доказательством очень масштабируемой распределенной системы, которая работает действительно хорошо и мы можем брать идеи, исходя из того, чтобы создавать системы более легко.» Я думаю, что это довольно веская причина: REST охватывает указания самого web, его архитектуры и его приемуществ.
Какие преимущества? Главным образом все те, какие несет в себе HTTP как платформа сама по себе. Безопасность приложений(шифрование и аутентификация), для которой известно некоторое количество решений. Кеширование встроено в протокол. Маршрутизация, через DNS, гибкая и хорошо известная система уже поддерживается повсеместно.
REST, несмотря на повсеместность использования, не является стандартом, как таковой, а подходом, стилем, ограниечением HTTP протокола. Его реализация может различаться в стиле, подходе. Для клиента такого API это может быть разочарованием. Качество REST сервисов дико варьируется.
Dr. Leonard Richardson собрал воедино модель, которая объясняет различные уровни соответствующих понятий REST и сортирует их. Она описывает 4 уровня, начиная с level 0. Martin Fowler очень хорошо написал про модель
Начало работы
Spring Boot может работать с любой IDE. Вы можете использовать Eclipse, IntelliJ IDEA, Netbeans и другие. Spring Tool Suite является IDE с открытым исходным кодом, основанной на Eclipse, которая предоставляет расширенные возможности Java EE. Она включает возможности для ещё более простого создания Spring приложений. Но присмотритесь к нему, если вы хотите обрести дополнительное преимущество к вашим ключевым действиям. Ниже представлено видео, которое демонстрирует как начать работу с STS и Spring Boot. Это общая инструкция для ознакомления с инструментами.
В предыдущих сериях.
Мы не будем погружаться в слишком большое количество кода. Мы используем две JPA сущности для моделирования записи в БД. Мы используем стандартную SQL БД для сохранения наших записей, чтобы имелась возможность использовать их как можно большему числу клиентов.
Первый класс моделирует учетную запись пользователя.
Каждый Account может не иметь, либо иметь один или множество Bookmark сущностей. Это связь 1:N. Код сущности Bookmark показан ниже:
Мы будем использовать два Spring Data JPA репозитория для обработки рутинных взаимодействий с БД. Spring Data репозитории как правило являются интерфейсами с методами, поддерживающими чтение, обновление, удаление и создание записей. Некоторые репозитории также поддерживают разделение на страницы и сортировку. Spring Data реализации основанных на соглашении именования методов в интерфейсе. Существует множество реализаций репозиториев, кроме тех двух. Вы можете использовать Spring Data MongoDB, Spring Data GemFire, Spring Data Cassandra и другие.
Ниже представлен репозиторий для работы с Bookmark сущностью:
Мы можем использовать HTTP глаголы для манипуляции данными, представленными по этим URI.
Конечно, некоторые вещи идут не по плану. Скорее всего будет ошибка времени выполнения браузера или сервиса. Мы все получаем раздражающую 404(«Страница не найдена») ошибку, когда пытаемся открыть страницу, которая не существует или ссылка на которую неправильна. 404 является кодом статуса. Она передает информацию о состоянии действия. многие коды статуса разделены различными диапазонами по назначению. Когда вы делаете запрос к web-странице в браузере, он вызывает HTTP GET и если страница отображается, вернется 200 код статуса. 200 означает OK ; вы можете не знать этого, но это так и есть.
Создание REST сервиса
Во первых, REST сервис закладок должен поддерживать выборку и добавление закладок, а также чтение какой-либо конкретной из них. Ниже представлен первоначальный вид нашего REST сервиса:
В Spring MVC это делается простым написанием сервисно-ориентированного кода, в котором фигурирует чистый HttpServlet API. Этот код может быть легко протестирован, расширен через Spring AOP. Мы посмотрим, как протестировать эти Spring MVC компоненты в следующей секции.
Использование HTTP для указания ошибок
Тестирование REST сервиса
Для всех тестов указаны application/json content-type и ответы ожидаются такого же типа. Тесты используют метод MockMvcResultMatchers#jsonPath для проверки структуры и содержания JSON ответов, что в свою очередь использует Jayway JSON Path API для запуска обхода с тиле X-Path по JSON структурам, как мы делаем в различных частях unit-тестов.
Создание HATEOAS REST сервиса
Но мы можем сделать лучше. Сервисы остаются соответствовать задачам, но отсутствует. надежность. Как сказано в Википедии: Клиенты должны знать API. Изменения в API отталкивают клиентов и они не обращаются к документации сервиса. Гипермедиа как двигатель состояния приложения(a.k.a. HATEOAS) является ещё одним ограничением, который адресован и удаляет эту нестыковку. Клиенты создают состояния переходов только через действия, которые динамически идентифицируются в гипермедиа сервером.
Улучшенная обработка ошибок с использованием VndErrors
HATEOAS передает клиентам улучшенные метаданные о самом сервисе. Мы можем также улучшить ситуацию обработки ошибок. Коды HTTP статусов 400-499, к примеру, говорят клиенту, что клиент сделал что-то неправильнное, коды 500-599 говорят о чем-то нехорошем на стороне сервера. Если вы знаете ваши коды статусов, то это может быть началом к пониманию, как работать с API. Но мы можем сделать лучше. В конце концов, перед тем, как клиент запустится, кому-то необходимо разработать его и сообщения об ошибках могут быть бесценными для понимания API. Ошибки могут быть обработаны последовательным способом даже лучше!
Обеспечение защиты REST сервиса
До сих пор мы исходили из предположения, что все клиенты надежны и что они должны обладать полным доступом ко всем данным. На самом деле такое редко бывает. Открытое REST API незащищено. Хотя это нетрудно исправить. Spring Security предоставляет фундамент для защиты доступа к приложению. Spring Security необходимо иметь представление о пользователях вашего приложения и их правах. Эти права отвечают на вопрос: что может пользователь приложения видеть или делать?
Авторизация и аутентификация клиента в Open Web с использование Spring Security OAuth
Мы можем выпонить запросы аутентификации клиента бесчисленным количеством способов. Клиенты могут отправлять, к примеру имя пользователя и пароль в каждом HTTP-запросе. Они могут передавать х509 сертификат в каждом запросе. В действительности существует множество подходов, которые могут быть использованы здесь.
Наш API предназначен для работы поверх open-web. Он предназначен для использования всевозможных HTML5 и нативных мобильных и настольных клиентов, которые мы намерены создать. Мы будем использовать разнообразные клиенты с различной степенью защиты и любое решение какое бы мы не выбрали, должно соответствовать этому. Мы должны также отделить имя пользователя и пароль из сессии приложения. В итоге, если сбросить пароль на Twitter, не хочется, чтобы клиенту пришлось повторно аутентифицироваться. С другой стороны, если кто-то угонит его у одного из наших клиентов(к примеру, если пользователь потерял телефон), то мы не хотим, чтобы злоумышленник смог заблокировать нашего пользователя.
В этом примере любой старый клиент может обратиться к Facebook, а по окончании иметь ключ доступа. Этот ключ доступа передается через все последующие REST запросы, наподобие HTTP cookie. Имя пользователи и пароль не нужно будет передавать и клиент может кешировать ключ доступа на определенный или неопределенный период. Пользователям клиента нет необходимости повторно аутентифицироваться каждый раз при открытии приложения. А ещё лучше, ключ доступа определять к каждому клиенту. Это может быть использовано для определения того, что одному клиенту требуется больше разрешений, чем другим. В этом и есть преимущество, состоящее в том, что любая конфиденциальная информация, как имя пользователь и пароль, никогда не будет в открытом виде у ненадежных приложений, которые могут использовать её в злонамеренных целях. Мы можем быть уверены в том, что любой клиент будет дружественным. OAuth поддерживает простейший этап проверки подлинности пользователя( обычно отправляя имя пользователя и пароль) от клиента и сервис возвращает ключ доступа OAuth без необходимости перенаправления на доверенный домен. Этот подход мы и возьмем: результатом будет то, что наши клиенты будут иметь ключ доступа, который отделен от имени пользователя и пароля, и который может быть использован для присвоения различных уровней защиты различным клиентам.
OAuth очень гибок. Вы можете, к примеру, развернуть сервер авторизации, общий для множества REST API. В этом случае, наша OAuth реализация живет рядом с нашим REST API закладок, т.к. они одни и те же. Именно поэтому мы использовали оба @EnableResourceServer и @EnableAuthorizationServer в одном и том же конфигурационном классе.
Вы сказали что-то про Open Web?
Использование HTTPS (SSL/TLS) для предотвращения Man-in-the-Middle атак
Spring Boot предоставляет встроенный web-сервер(Apache Tomcat по умолчанию), который может быть настроен программно делать что-либо, что и отдельный Apache Tomcat web-сервер может делать. Раньше требовалось выполнить несколько нудных шагов для настройки HTTPS (SSL/TLS). Теперь, Spring Boot делает это супер просто. Для начала, создайте следующее:
HTTPS требует подписанный сертификат, который мы предъявляем, используя значения свойств. Для этого мы можем использовать из JDK keytool:
Собираем все вместе
Заключение
REST является наиболее естесственным способом для повсеместного, распределенного взаимодействия с клиентами. Он работает потому что работает HTTP. Когда вы поймете, как REST встраивается в приложение, тогда вам не трудно будет представить архитектуру с многочисленными, отдельновзятыми API, открытыми поверх REST, с балансировкой нагрузки, каким и должен быть любой другой HTTP сервис. Не удивительно, что REST(часто, но не обязательно) образует важнейшую основу для микросервисов, которые рассмотрены на протяжении всего урока.
Аннотации @Controller и @RestController в весенней загрузке
В этом уроке мы рассмотрим, в чем разница между @Controller и @RestController в Spring Boot, на примерах.
Вступление
В Spring Boot класс controller отвечает за обработку входящих запросов REST API, подготовку модели и возврат представления, которое будет отображаться в качестве ответа.
Рабочий процесс Spring Boot REST API
Прежде чем определить две аннотации, мы быстро рассмотрим рабочий процесс того, как Spring Boot обрабатывает запросы и процессы REST API и возвращает ответ:
Аннотация @Controller
Аннотация @Controller является специализацией общего стереотипа @Компонента аннотации, которая позволяет распознавать класс как компонент, управляемый Spring.
Сначала отметьте класс аннотацией @Controller вместе с @RequestMapping и укажите путь к /api/дереву :
В качестве альтернативы вы могли бы вместо этого аннотировать каждый тип ответа аннотацией @ResponseBody :
Из-за аннотации @ResponseBody поля из извлеченного объекта сериализуются в JSON и возвращаются клиенту, который его запросил.
Аннотация @RestController
Это на одно объявление аннотации меньше! Если вы также посмотрите на определение интерфейса двух аннотаций, чтобы увидеть разницу между ними:
Git Essentials
Ознакомьтесь с этим практическим руководством по изучению Git, содержащим лучшие практики и принятые в отрасли стандарты. Прекратите гуглить команды Git и на самом деле изучите это!
Используя пример контроллера TreeController выше, давайте сравним изменения при использовании этой аннотации:
Вывод
Помимо того факта, что @RestController существует для того, чтобы контроллеры Spring были на одну строку короче, между этими двумя аннотациями нет никаких существенных различий.
Основная функция обеих аннотаций состоит в том, чтобы разрешить распознавание класса как компонента, управляемого Spring, и разрешить обработку HTTP-запросов с использованием REST API.
Введение в Spring Boot: создание простого REST API на Java
Из-за громоздкой конфигурации зависимостей настройка Spring для корпоративных приложений превратилась в весьма утомительное и подверженное ошибкам занятие. Особенно это относится к приложениям, которые используют также несколько сторонних библиотек
Каждый раз, создавая очередное корпоративное Java-приложение на основе Spring, вам необходимо повторять одни и те же рутинные шаги по его настройке:
1. Представляем Spring Boot
Авторы Spring решили предоставить разработчикам некоторые утилиты, которые автоматизируют процедуру настройки и ускоряют процесс создания и развертывания Spring-приложений, под общим названием Spring Boot
Spring Boot — это полезный проект, целью которого является упрощение создания приложений на основе Spring. Он позволяет наиболее простым способом создать web-приложение, требуя от разработчиков минимум усилий по его настройке и написанию кода
2. Особенности Spring Boot
Spring Boot обладает большим функционалом, но его наиболее значимыми особенностями являются: управление зависимостями, автоматическая конфигурация и встроенные контейнеры сервлетов
2.1. Простота управления зависимостями
Чтобы ускорить процесс управления зависимостями, Spring Boot неявно упаковывает необходимые сторонние зависимости для каждого типа приложения на основе Spring и предоставляет их разработчику посредством так называемых starter-пакетов (spring-boot-starter-web, spring-boot-starter-data-jpa и т.д.)
Starter-пакеты представляют собой набор удобных дескрипторов зависимостей, которые можно включить в свое приложение. Это позволит получить универсальное решение для всех, связанных со Spring технологий, избавляя программиста от лишнего поиска примеров кода и загрузки из них требуемых дескрипторов зависимостей (пример таких дескрипторов и стартовых пакетов будет показан ниже)
Например, если вы хотите начать использовать Spring Data JPA для доступа к базе данных, просто включите в свой проект зависимость spring-boot-starter-data-jpa и все будет готово (вам не придется искать совместимые драйверы баз данных и библиотеки Hibernate)
Если вы хотите создать Spring web-приложение, просто добавьте зависимость spring-boot-starter-web, которая подтянет в проект все библиотеки, необходимые для разработки Spring MVC-приложений, таких как spring-webmvc, jackson-json, validation-api и Tomcat
Другими словами, Spring Boot собирает все общие зависимости и определяет их в одном месте, что позволяет разработчикам просто использовать их, вместо того, чтобы изобретать колесо каждый раз, когда они создают новое приложение
Следовательно, при использовании Spring Boot, файл pom.xml содержит намного меньше строк, чем при использовании его в Spring-приложениях
Обратитесь к документации, чтобы ознакомиться со всеми Spring Boot starter-пакетами
2.2. Автоматическая конфигурация
Второй превосходной возможностью Spring Boot является автоматическая конфигурация приложения
После выбора подходящего starter-пакета, Spring Boot попытается автоматически настроить Spring-приложение на основе добавленных вами jar-зависимостей
Например, если вы добавите Spring-boot-starter-web, Spring Boot автоматически сконфигурирует такие зарегистрированные бины, как DispatcherServlet, ResourceHandlers, MessageSource
Если вы используете spring-boot-starter-jdbc, Spring Boot автоматически регистрирует бины DataSource, EntityManagerFactory, TransactionManager и считывает информацию для подключения к базе данных из файла application.properties
Если вы не собираетесь использовать базу данных, и не предоставляете никаких подробных сведений о подключении в ручном режиме, Spring Boot автоматически настроит базу в памяти, без какой-либо дополнительной конфигурации с вашей стороны (при наличии H2 или HSQL библиотек)
Автоматическая конфигурация может быть полностью переопределена в любой момент с помощью пользовательских настроек
2.3. Встроенная поддержка сервера приложений — контейнера сервлетов
Каждое Spring Boot web-приложение включает встроенный web-сервер. Посмотрите на список контейнеров сервлетов, которые поддерживаются «из коробки»
Разработчикам теперь не надо беспокоиться о настройке контейнера сервлетов и развертывании приложения на нем. Теперь приложение может запускаться само, как исполняемый jar-файл с использованием встроенного сервера
Если вам нужно использовать отдельный HTTP-сервер, для этого достаточно исключить зависимости по умолчанию. Spring Boot предоставляет отдельные starter-пакеты для разных HTTP-серверов
Создание автономных web-приложений со встроенными серверами не только удобно для разработки, но и является допустимым решением для приложений корпоративного уровня и становится все более полезно в мире микросервисов. Возможность быстро упаковать весь сервис (например, аутентификацию пользователя) в автономном и полностью развертываемом артефакте, который также предоставляет API — делает установку и развертывание приложения значительно проще
3. Требования к установке Spring Boot
Для настройки и запуска Spring Boot приложений требуется следующее:
4. Создание Spring Boot приложения
Теперь давайте перейдем к практике и реализуем очень простой REST API для приема платежей, используя возможности Spring Boot
4.1. Создание web-проекта с использованием Maven
Создайте Maven-проект в используемой вами IDE, назвав его SpringBootRestService
Обязательно используйте версию Java 8+, поскольку Spring Boot не работает с более ранними версиями
4.2. Конфигурация pom.xml
Вторым шагом необходимо настроить Spring Boot в файле pom.xml
Все приложения Spring Boot конфигурируются от spring-boot-starter-parent, поэтому перед дальнейшим определением зависимостей, добавьте starter-parent следующим образом:
Т.к. мы создаем REST API, то необходимо в качестве зависимости использовать spring-boot-starter-web, которая неявно определяет все остальные зависимости, такие как spring-core, spring-web, spring-webmvc, servlet api, и библиотеку jackson-databind, поэтому просто добавьте в pom.xml следующее:
Теперь следующие jar-библиотеки автоматически импортируются в ваш проект:
Следующий шаг — добавляем Spring Boot плагин:
Последний шаг — сделать так, чтобы Maven генерировал исполняемый jar-файл при сборке:
Ниже приведен полный файл pom.xml:
Как видите, используя одну зависимость, мы можем создать полностью функциональное web-приложение
4.3. Создание ресурсов REST
Теперь мы собираемся создать контроллер платежей вместе с POJO-классами для запросов и ответов
Напишем класс запроса платежа:
А также класс, обрабатывающий базовый ответ, возвращаемый нашим сервисом:
А теперь создадим контроллер:
4.4. Создание основного класса приложения
Этот последний шаг заключается в создании класса конфигурации и запуска приложения. Spring Boot поддерживает новую аннотацию @SpringBootApplication, которая эквивалентна использованию @Configuration, @EnableAutoConfiguration и @ComponentScan с их атрибутами по умолчанию
Таким образом, вам просто нужно создать класс, аннотированный с помощью @SpringBootApplication, а Spring Boot включит автоматическую настройку и отсканирует ваши ресурсы в текущем пакете:
5. Развертывание приложения Spring Boot
Теперь давайте воспользуемся третьей замечательной особенностью Spring Boot — это встроенный сервер. Все, что нам нужно сделать — это создать исполняемый jar-файл с помощью Maven и запустить его, как обычное автономное приложение:
Наш REST API запущен и готов обслуживать запросы через порт 8080 (по умолчанию)
В этой статье мы рассмотрели возможности Spring Boot и создали полностью рабочий пример с использованием встроенного сервера
В переводе обновили информацию:
UPDATE:
Как заметил Lure_of_Chaos, теперь уже все можно сделать автоматически через SPRING INITIALIZR. Причем не выходя из любимой JetBrains IntelliJ IDEA.