1. Обзор
В этой статье будут объяснены основы Spring Data REST и показано, как использовать его для создания простого REST API.
В целом, Spring Data REST построен поверх проекта Spring Data и позволяет легко создавать веб-сервисы REST, управляемые гипермедиа, которые подключаются к хранилищам данных Spring – все они используют HAL в качестве движущего типа гипермедиа.
Это отнимает много ручной работы, обычно связанной с такими задачами, и делает реализацию основных функций CRUD для веб-приложений довольно простой.
2. Зависимости Maven
Для нашего простого приложения требуются следующие зависимости Maven:
org.springframework.boot spring-boot-starter org.springframework.boot spring-boot-starter-data-restorg.springframework.boot spring-boot-starter-data-jpa com.h2database h2
Мы решили использовать Spring Boot для этого примера, но классическая пружина также будет отлично работать. Мы также решили использовать встроенную базу данных H2, чтобы избежать каких-либо дополнительных настроек, но пример может быть применен к любой базе данных.
3. Написание заявления
Мы начнем с написания объекта домена для представления пользователя нашего веб-сайта:
@Entity public class WebsiteUser { @Id @GeneratedValue(strategy = GenerationType.AUTO) private long id; private String name; private String email; // standard getters and setters }
У каждого пользователя есть имя и адрес электронной почты, а также автоматически сгенерированный идентификатор. Теперь мы можем написать простой репозиторий:
@RepositoryRestResource(collectionResourceRel = "users", path = "users") public interface UserRepository extends PagingAndSortingRepository{ List findByName(@Param("name") String name); }
Это интерфейс, который позволяет выполнять различные операции с Пользователем веб-сайта объектами. Мы также определили пользовательский запрос, который будет предоставлять список пользователей на основе заданного имени.
Аннотация @RepositoryRestResource является необязательной и используется для настройки конечной точки REST. Если мы решим опустить его, Spring автоматически создаст конечную точку в ” /пользователи веб-сайта “вместо” /пользователи “.
Наконец, мы напишем стандартный основной класс Spring Boot для инициализации приложения :
@SpringBootApplication public class SpringDataRestApplication { public static void main(String[] args) { SpringApplication.run(SpringDataRestApplication.class, args); } }
Вот так! Теперь у нас есть полнофункциональный REST API. Давайте посмотрим на это в действии.
4. Доступ к API REST
Если мы запустим приложение и перейдем в http://localhost:8080/ в браузере мы получим следующий JSON:
{ "_links" : { "users" : { "href" : "http://localhost:8080/users{?page,size,sort}", "templated" : true }, "profile" : { "href" : "http://localhost:8080/profile" } } }
Как вы можете видеть, есть доступная конечная точка ” /users “, и у нее уже есть ” ?страница “, ” ?размер ” и ” ?сортировка ” параметры.
Существует также стандартная конечная точка ” /профиль “, которая предоставляет метаданные приложения. Важно отметить, что ответ структурирован таким образом, чтобы соответствовать ограничениям стиля архитектуры REST. В частности, он обеспечивает единый интерфейс и самоописательные сообщения. Это означает, что каждое сообщение содержит достаточно информации, чтобы описать, как его обработать.
В нашем приложении пока нет пользователей, поэтому перейдем к http://localhost:8080/users просто покажет пустой список пользователей. Давайте используем curl для добавления пользователя.
$ curl -i -X POST -H "Content-Type:application/json" -d '{ "name" : "Test", \ "email" : "[email protected]" }' http://localhost:8080/users { "name" : "test", "email" : "[email protected]", "_links" : { "self" : { "href" : "http://localhost:8080/users/1" }, "websiteUser" : { "href" : "http://localhost:8080/users/1" } } }
Давайте также взглянем на заголовки ответов:
HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Location: http://localhost:8080/users/1 Content-Type: application/hal+json;charset=UTF-8 Transfer-Encoding: chunked
Вы заметите, что возвращаемый тип контента – ” application/hal+json “. HAL – это простой формат, который обеспечивает последовательный и простой способ гиперссылки между ресурсами в вашем API. Заголовок также автоматически содержит заголовок Location , который является адресом, который мы можем использовать для доступа к вновь созданному пользователю.
Теперь мы можем получить доступ к этому пользователю по адресу http://localhost:8080/users/1
{ "name" : "test", "email" : "[email protected]", "_links" : { "self" : { "href" : "http://localhost:8080/users/1" }, "websiteUser" : { "href" : "http://localhost:8080/users/1" } } }
Вы также можете использовать curl или любой другой клиент REST для выдачи запросов на установку, ИСПРАВЛЕНИЕ и УДАЛЕНИЕ. Также важно отметить, что весенний отдых данных автоматически следует принципам HATEOAS. HATEOAS является одним из ограничений стиля архитектуры REST, и это означает, что гипертекст должен использоваться для поиска вашего пути через API.
Наконец, давайте попробуем получить доступ к пользовательскому запросу, который мы написали ранее, и найти всех пользователей с именем “тест”. Это делается путем перехода на http://localhost:8080/users/search/findByName?name=test
{ "_embedded" : { "users" : [ { "name" : "test", "email" : "[email protected]", "_links" : { "self" : { "href" : "http://localhost:8080/users/1" }, "websiteUser" : { "href" : "http://localhost:8080/users/1" } } } ] }, "_links" : { "self" : { "href" : "http://localhost:8080/users/search/findByName?name=test" } } }
5. Заключение
В этом уроке были продемонстрированы основы создания простого REST API с помощью Spring Data REST. Пример, используемый в этой статье, можно найти в связанном проекте GitHub .