Введение в Spring Data REST

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 .