Возврат данных в формате JSON (Jackson, ResponseEntity)

Возврат данных в формате JSON (Jackson, ResponseEntity)

Автоматический JSON: Spring Boot включает Jackson по умолчанию, поэтому объекты (POJO) возвращаемые из @RestController сериализуются в JSON без дополнительного кода.
ResponseEntity: специальный тип ответа, инкапсулирующий тело, статус и заголовки HTTP-ответа. Используется для явного управления кодом статуса или доп. информацией в ответе.
Примеры статусов: 200 OK (успех по умолчанию), 201 Created (создан новый ресурс), 204 No Content (успех без тела), и т.д.
Совет: возвращайте сущности или DTO – Spring сам сконвертирует их в JSON. Используйте ResponseEntity при необходимости указать нестандартный статус или заголовки.

Пояснение:

В Spring MVC, благодаря аннотации @RestController (или @ResponseBody), возвращаемое значение метода контроллера отправляется прямо в тело HTTP-ответа. Если возвращается простой тип (String, число) – будет возвращен как текст/JSON-скаляр. Если возвращается объект или список – Spring автоматически превратит его в JSON с помощью библиотеки Jackson (которая входит в состав spring-boot-starter-web).
По умолчанию Spring Boot включает Jackson 2 как JSON-парсер. Поэтому достаточно вернуть из метода обычный Java объект (POJO), и он будет сериализован в JSON и отправлен клиенту. Например, если метод контроллера возвращает объект User (с полями id, name, email), клиент получит ответ с Content-Type: application/json и телом вида:
{ "id": 42, "name": "Ivan", "email": "ivan@example.com" }
Jackson осуществляет сериализацию рефлексивно – глядя на геттеры или поля объекта. Можно настраивать этот процесс через аннотации (@JsonProperty, @JsonIgnore и т.д.), но по умолчанию достаточно иметь публичные поля или методы get/set. Для коллекций Jackson создаст JSON-массив. Для Map – JSON-объект с ключами-значениями.
При возврате списков или массивов объектов, результат также будет в формате JSON. Например, List<User> превратится в JSON-массив пользователей. Важно отметить, что названия полей в JSON соответствуют свойствам объекта (если не настроено иначе). В 2025 г. Jackson поддерживает многие современные типы Java (например, java.time API для дат, record-типы и пр.), что облегчает передачу данных.
Теперь про коды состояния (HTTP Status). Если мы просто возвращаем объект из контроллера, Spring MVC по умолчанию установит 200 OK в статусе ответа (предполагая, что операция успешна). Но во многих случаях нам нужно вернуть другой код – например, 201 Created при создании ресурса, 204 No Content если тело ответа пустое, или какие-то ошибки (4xx/5xx). Чтобы задать статус вручную, есть несколько способов:
Аннотация @ResponseStatus над методом контроллера – задает фиксированный код для ответа этого метода. Однако в случае REST это не очень гибко (чаще используют для исключений, о чем далее).
Возврат специального объекта ResponseEntity. ResponseEntity<T> – обертка, которая содержит в себе не только тело ответа (объект типа T), но и статус и заголовки. Если метод возвращает ResponseEntity, то вы полностью контролируете HTTP-ответ. Например:
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
User created = userService.save(user);
URI location = ...; // URI нового ресурса, например "/users/{id}"
return ResponseEntity.created(location)       // статус 201 Created
.body(created);          // тело ответа - созданный пользователь
}
Здесь мы использовали метод-хелпер ResponseEntity.created(URI) для построения ответа с кодом 201 и заголовком Location. Также можно использовать ResponseEntity.ok(obj) для 200 OK, ResponseEntity.status(HttpStatus.NO_CONTENT).build() для 204 и т.д. ResponseEntity удобен, когда нужно вернуть нестандартный статус или дополнительные заголовки (например, Location, Content-Type, Custom-Header и т.п.). В остальных случаях вполне можно возвращать просто объект – будет 200 OK автоматически.
С помощью выброса исключений Spring (например, ResponseStatusException) – об этом далее, в разделе обработки ошибок.
Как правило, лучшей практикой является: для успешных операций возвращать смысловой статус и данные. Например, при создании ресурса – 201 и объект или хотя бы идентификатор; при успешном удалении – 204 (без тела); при обычном получении данных – 200 и JSON; при поиске и отсутствии результата – 404 и сообщение об ошибке. Ниже приведены несколько распространенных кодов и их назначение:
200 OK – запрос успешно выполнен, тело содержит ответ (для GET/PUT).
201 Created – успешно создан новый ресурс (обычно для POST), в заголовке Location может быть URL нового ресурса.
204 No Content – запрос успешно выполнен, но тело пустое (например, успешный DELETE или PUT без возвращаемых данных).
400 Bad Request – клиент отправил неверный запрос (синтаксическая ошибка, неверные данные – например, не пройдена валидация).
401 Unauthorized – требуется аутентификация (например, не передан или неверен токен авторизации).
403 Forbidden – доступ запрещен, у клиента нет прав на ресурс (при корректной аутентификации).
404 Not Found – ресурс не найден (например, запрошен /users/999, а такого нет).
500 Internal Server Error – на сервере произошла ошибка при обработке.
Правильное использование кодов состояния – часть контрактa REST API. Клиент по коду быстро понимает общий результат, а детали может получить из тела ответа (например, сообщение об ошибке).
Jackson позволяет настраивать формат JSON: можно глобально конфигурировать ObjectMapper (например, через application.properties в Spring Boot, задавая формат дат, свойство spring.jackson.*), либо использовать mixins/дто для разных представлений. В современных Spring приложениях часто используются DTO (Data Transfer Objects) или проекции вместо прямой отдачи JPA-entity, чтобы контролировать какие поля сериализуются. Jackson поддерживает механизм @JsonView для отдачи разных "видов" данных в разных ситуациях.
Также Spring MVC поддерживает конвертацию исходящих данных в альтернативные форматы при наличии соответствующих библиотек – например, XML (через Jackson XML extension) или YAML. Формат можно выбирать через Content Negotiation (заголовок Accept). Но JSON де-факто стандарт для REST API в 2025 году, и Spring Boot настроен на него из коробки.
В итоге, для разработчика все просто: пишем метод, возвращаем объекты – и сразу получаем JSON-ответы без дополнительного кода. Когда нужен особый ответ – заворачиваем в ResponseEntity и указываем нужный статус/заголовки. Это сочетание гибкости и простоты – одна из причин популярности Spring для создания RESTful сервисов.