REST API – это стандарт взаимодействия между клиентом и сервером, использующий HTTP методы. Для создания микросервиса на Java с использованием Spring Framework необходимо придерживаться принципов REST, включая разделение на клиент и сервер, отсутствие состояния на сервере, использование кэширования, единообразие интерфейса, слоевую систему и передачу кода по запросу. RESTful сервис соблюдает эти ограничения. В статье описан процесс создания микросервиса для инцидентов, с использованием сущности «Инцидент» с полями идентификатора, имени, описания, дат создания и закрытия, идентификаторов аналитика и инициатора, статуса, приоритета, категории и ответственного сервиса.
Для передачи данных между слоями приложения и через API используются DTO (Data Transfer Object). DTO скрывают внутреннюю структуру сущностей, упрощают и стандартизируют передаваемые данные, изолируя внешний контракт от внутренней реализации. Сервисный слой отвечает за бизнес-логику и использует интерфейсы для гибкости, тестирования и ясности. Реализация сервисного слоя включает логирование, обработку исключений и маппинг между DTO и сущностями. Пагинация данных реализована для предотвращения перегрузки системы при запросе больших объемов данных. Spring Data JPA по умолчанию реализует транзакции для методов репозитория, что устраняет необходимость дублирования аннотации @Transactional.
Контроллер REST API должен принимать данные и формировать ответы, используя стандартные HTTP методы: GET (получение), POST (создание), PUT (полное обновление), PATCH (частичное обновление) и DELETE (удаление). Методы GET, PUT, PATCH и DELETE должны быть идемпотентными. API должен возвращать стандартные HTTP коды ответов, такие как 200, 201, 204 (успех), 400, 403, 404, 422 (ошибки клиента) и 500, 501 (ошибки сервера). URI должны быть понятными и следовать REST конвенциям. В ответах должен использоваться формат JSON с заголовком Content-Type: application/json; charset=UTF-8. Контроллеры должны разделять логику, минимизировать логирование, делегируя эту задачу в сервисный слой и обработчики исключений.
Глобальная обработка исключений с @ControllerAdvice позволяет централизованно обрабатывать исключения, избегая дублирования кода и обеспечивая единообразие ответов об ошибках. Глобальный обработчик исключений использует кастомные исключения, понятные сообщения об ошибках, правильные HTTP статусы и стандартизирует формат ответов (например, в виде ErrorResponse). Применяется логирование ошибок и сокрытие деталей реализации для непредусмотренных ошибок сервера. Использование DTO для возврата данных клиенту, как и для получения их от клиента, позволяет избежать зависимости внешнего контракта от внутренней реализации, а также обеспечивает гибкость в изменении структуры данных без нарушения работы API.
Изображение носит иллюстративный характер
Для передачи данных между слоями приложения и через API используются DTO (Data Transfer Object). DTO скрывают внутреннюю структуру сущностей, упрощают и стандартизируют передаваемые данные, изолируя внешний контракт от внутренней реализации. Сервисный слой отвечает за бизнес-логику и использует интерфейсы для гибкости, тестирования и ясности. Реализация сервисного слоя включает логирование, обработку исключений и маппинг между DTO и сущностями. Пагинация данных реализована для предотвращения перегрузки системы при запросе больших объемов данных. Spring Data JPA по умолчанию реализует транзакции для методов репозитория, что устраняет необходимость дублирования аннотации @Transactional.
Контроллер REST API должен принимать данные и формировать ответы, используя стандартные HTTP методы: GET (получение), POST (создание), PUT (полное обновление), PATCH (частичное обновление) и DELETE (удаление). Методы GET, PUT, PATCH и DELETE должны быть идемпотентными. API должен возвращать стандартные HTTP коды ответов, такие как 200, 201, 204 (успех), 400, 403, 404, 422 (ошибки клиента) и 500, 501 (ошибки сервера). URI должны быть понятными и следовать REST конвенциям. В ответах должен использоваться формат JSON с заголовком Content-Type: application/json; charset=UTF-8. Контроллеры должны разделять логику, минимизировать логирование, делегируя эту задачу в сервисный слой и обработчики исключений.
Глобальная обработка исключений с @ControllerAdvice позволяет централизованно обрабатывать исключения, избегая дублирования кода и обеспечивая единообразие ответов об ошибках. Глобальный обработчик исключений использует кастомные исключения, понятные сообщения об ошибках, правильные HTTP статусы и стандартизирует формат ответов (например, в виде ErrorResponse). Применяется логирование ошибок и сокрытие деталей реализации для непредусмотренных ошибок сервера. Использование DTO для возврата данных клиенту, как и для получения их от клиента, позволяет избежать зависимости внешнего контракта от внутренней реализации, а также обеспечивает гибкость в изменении структуры данных без нарушения работы API.
