Что упрощает Spring HATEOAS

Spring HATEOAS: Упрощение REST API

Spring HATEOAS (Hypermedia As The Engine Of Application State) — это библиотека, которая упрощает создание RESTful API с гиперссылками. Она помогает разработчикам строить более гибкие и навигируемые API, где клиент может динамически обнаруживать доступные операции через ссылки в ответах.

Основные преимущества Spring HATEOAS

1. Упрощение создания ссылок

Bез HATEOAS разработчик вручную конструирует URL строки в ответах:

public class UserController {
  @GetMapping("/users/{id}")
  public Map<String, Object> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    Map<String, Object> response = new HashMap<>();
    response.put("id", user.getId());
    response.put("name", user.getName());
    response.put("_links", new HashMap<String, String>() {{
      put("self", "/api/users/" + id);
      put("all_users", "/api/users");
    }});
    return response;
  }
}

С HATEOAS это становится намного проще и типобезопаснее:

import org.springframework.hateoas.EntityModel;
import org.springframework.hateoas.Link;
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;

public class UserController {
  @GetMapping("/users/{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"));
  }
  
  @GetMapping("/users")
  public CollectionModel<EntityModel<User>> getAllUsers() {
    List<User> users = userService.findAll();
    return CollectionModel.of(
      users.stream()
        .map(u -> EntityModel.of(u,
          linkTo(methodOn(UserController.class).getUser(u.getId())).withSelfRel()))
        .toList(),
      linkTo(methodOn(UserController.class).getAllUsers()).withSelfRel());
  }
}

2. Автоматическая генерация URL

Mетод linkTo(methodOn(...)) автоматически строит правильные URL на основе методов контроллера. Если вы измените маршрут, ссылки обновятся автоматически.

3. Поддержка HAL (Hypertext Application Language)

Spring HATEOAS использует стандарт HAL, который определяет удобный формат для гиперссылок в JSON:

{
  "id": 1,
  "name": "John Doe",
  "_links": {
    "self": {
      "href": "http://api.example.com/users/1"
    },
    "users": {
      "href": "http://api.example.com/users"
    },
    "update": {
      "href": "http://api.example.com/users/1",
      "method": "PUT"
    },
    "delete": {
      "href": "http://api.example.com/users/1",
      "method": "DELETE"
    }
  }
}

Основные компоненты Spring HATEOAS

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

Практический пример с пагинацией

public class UserController {
  @GetMapping("/users")
  public PagedModel<EntityModel<User>> getAllUsers(
      @RequestParam(defaultValue = "0") int page,
      @RequestParam(defaultValue = "10") int size) {
    
    PageRequest pageRequest = PageRequest.of(page, size);
    Page<User> users = userService.findAll(pageRequest);
    
    List<EntityModel<User>> userModels = users.stream()
      .map(u -> EntityModel.of(u,
        linkTo(methodOn(UserController.class).getUser(u.getId())).withSelfRel()))
      .toList();
    
    PagedModel<EntityModel<User>> pagedModel = 
      PagedModel.of(userModels, new PageMetadata(size, page, users.getTotalElements()));
    
    pagedModel.add(linkTo(methodOn(UserController.class).getAllUsers(0, size)).withRel("first"));
    pagedModel.add(linkTo(methodOn(UserController.class).getAllUsers(page, size)).withSelfRel());
    
    return pagedModel;
  }
}

Заключение

Spring HATEOAS упрощает разработку true RESTful API путём автоматизации построения ссылок, обеспечения их типобезопасности и использования стандартного формата HAL. Это делает API более навигируемым и гибким для клиентов.