1. Обзор
В этой статье будут объяснены основы Spring Data REST и показано, как использовать его для создания простого REST API.
В целом, Spring Data REST построен на основе проекта Spring Data и позволяет легко создавать веб-службы REST на основе гипермедиа, которые подключаются к репозиториям Spring Data — все с использованием HAL в качестве управляющего типа гипермедиа.
Это отнимает много ручной работы, обычно связанной с такими задачами, и делает реализацию базовых функций CRUD для веб-приложений довольно простой.
2. Зависимости Maven
Для нашего простого приложения требуются следующие зависимости Maven:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId
<artifactId>spring-boot-starter-data-rest</artifactId></dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
</dependency>
Мы решили использовать Spring Boot для этого примера, но классический Spring тоже подойдет. Мы также решили использовать встроенную базу данных 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<WebsiteUser, Long> {
List<WebsiteUser> findByName(@Param("name") String name);
}
Это интерфейс, позволяющий выполнять различные операции с объектами WebsiteUser . Мы также определили пользовательский запрос, который предоставит список пользователей на основе заданного имени.
Аннотация @RepositoryRestResource является необязательной и используется для настройки конечной точки REST. Если бы мы решили опустить его, Spring автоматически создал бы конечную точку в « /websiteUsers » вместо « /users ».
Наконец, мы напишем стандартный основной класс Spring Boot для инициализации приложения :
@SpringBootApplication
public class SpringDataRestApplication {
public static void main(String[] args) {
SpringApplication.run(SpringDataRestApplication.class, args);
}
}
Вот и все! Теперь у нас есть полнофункциональный REST API. Давайте посмотрим на это в действии.
4. Доступ к REST API
Если мы запустим приложение и перейдем по адресу http://localhost:8080/ в браузере, мы получим следующий JSON:
{
"_links" : {
"users" : {
"href" : "http://localhost:8080/users{?page,size,sort}",
"templated" : true
},
"profile" : {
"href" : "http://localhost:8080/profile"
}
}
}
Как видите, доступна конечная точка « /users », и у нее уже есть параметры « ?page », « ?size » и « ?sort ».
Существует также стандартная конечная точка « /profile », которая предоставляет метаданные приложения. Важно отметить, что ответ структурирован в соответствии с ограничениями стиля архитектуры REST. В частности, он обеспечивает унифицированный интерфейс и самоописательные сообщения. Это означает, что каждое сообщение содержит достаточно информации, чтобы описать, как обрабатывать сообщение.
В нашем приложении еще нет пользователей, поэтому переход по адресу http://localhost:8080/users покажет пустой список пользователей. Давайте используем curl для добавления пользователя.
$ curl -i -X POST -H "Content-Type:application/json" -d '{ "name" : "Test", \
"email" : "test@test.com" }' http://localhost:8080/users
{
"name" : "test",
"email" : "test@test.com",
"_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" : "test@test.com",
"_links" : {
"self" : {
"href" : "http://localhost:8080/users/1"
},
"websiteUser" : {
"href" : "http://localhost:8080/users/1"
}
}
}
Вы также можете использовать curl или любой другой клиент REST для выполнения запросов PUT, PATCH и DELETE. Также важно отметить, что Spring Data REST автоматически следует принципам HATEOAS. HATEOAS — это одно из ограничений стиля архитектуры REST, и это означает, что для поиска пути через API следует использовать гипертекст.
Наконец, давайте попробуем получить доступ к пользовательскому запросу, который мы написали ранее, и найти всех пользователей с именем «test». Это можно сделать, перейдя по адресу http://localhost:8080/users/search/findByName?name=test.
{
"_embedded" : {
"users" : [ {
"name" : "test",
"email" : "test@test.com",
"_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 .