Что такое Spring HATEOAS и для чего он используется?

Spring HATEOAS — это модуль Spring, упрощающий реализацию принципа HATEOAS (Hypermedia as the Engine of Application State) в REST API. HATEOAS делает API самоописываемым, добавляя гипермедийные ссылки к ресурсам, что позволяет клиенту динамически обнаруживать доступные действия.

Ключевые абстракции:

• RepresentationModel — базовый класс для ресурсов с ссылками.
• EntityModel<T> — обёртка для отдельной сущности.
• CollectionModel<T> — обёртка для коллекции ресурсов.
• Link — объект, представляющий гипермедийную ссылку.

Пример контроллера:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public EntityModel<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        // Создание ресурса с ссылками
        return EntityModel.of(user,
            linkTo(methodOn(UserController.class).getUser(id)).withSelfRel(),
            linkTo(methodOn(UserController.class).getAllUsers()).withRel("users")
        );
    }
}

Результат (JSON в формате HAL по умолчанию):

{
  "id": 1,
  "name": "John Doe",
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/users/1"
    },
    "users": {
      "href": "http://localhost:8080/api/users"
    }
  }
}

Преимущества: Клиент не «зашивает» в код URL, а следует по ссылкам из ответа, что повышает устойчивость API к изменениям и улучшает документацию.