Rivalry2

HTML Diff

0 added 0 removed

Original 2026-01-01

Modified 2026-02-26

1 Spring Boot в основном используется для создания API. В этом уроке вы узнаете, что это такое, зачем нужно и как с этим работать.

2 По отношению к веб-приложениям, API - это набор маршрутов, созданных для использования другими сервисами или приложениями. API обычно возвращают данные в JSON-формате, чтобы их было удобно читать и обрабатывать.

3 Например, такой API есть у<a>GitHub</a>. Оно активно используется в редакторах c интеграцией с GitHub API, а также в онлайн-инструментах для создания десктопных приложений и даже<a>консольных утилит</a>:

4 Способов создавать API много. Самым распространенным и базовым считается<a>REST API</a>. Это архитектурный подход, очень сильно полагающийся на принципы работы самого HTTP. Далее мы будем изучать особенности этого подхода и строить наш код на его основе.

5 <h2>Ориентированность на ресурсы</h2>

6 В REST-подходе маршруты строятся вокруг ресурсов. Действия над ними в основном определяются HTTP-методами. Так выглядят маршруты типичного CRUD:

7 Здесь ресурс - это пользователь. Обычно во фреймворках берут имя ресурса, ставят его во множественное число и делают частью маршрута. А вот в коде все по-другому: обработчики одного ресурса помещают в общий класс, называемыйконтроллером. Сам класс располагают в соответствующей директории:

8 С точки зрения Spring Boot контроллером считается любой класс с аннотацией @RestController. Для пользователя он будет выглядеть так:

9 Это не означает, что все обработчики, связанные с каким-то ресурсом, находятся ровно в одном контроллере. У ресурсов бывают разные представления, которые требуют других обработчиков для одних и тех же действий. Представьте себе ссылку/companies/google/usersдля маршрута/companies/{id}/users. Такой маршрут может выводить сотрудников конкретной компании, у которых есть собственное представление и собственные действия. Здесь для работы с этими пользователями в коде будет свой контроллер:

10 <h3>Дополнительные действия</h3>

11 CRUD - это базовый набор операций, но в реальных проектах встречаются запуски процессов, переводы сущностей в новые состояния и другие дополнительные действия. Предположим, что мы хотим опубликовать статью на сайте. Чтобы это сделать, нужен дополнительный обработчик со своим маршрутом:

12 <h3>Префикс/api</h3>

13 Этот пункт не относится напрямую к понятию REST, но считается общепринятой практикой. Если маршрут считается частью API, то его располагают под префиксом/api. Например, маршрут/usersпревращается в/api/users. То же самое происходит со всеми остальными маршрутами. Иногда этого недостаточно и вводится версионирование:/api/v1/users.

14 В рамках курса мы остановимся на варианте/api/users. Чтобы добиться такого результата, можно добавить этот префикс в каждый маршрут, но получится дублирование. Упростить эту задачу можно с помощью аннотации @RequestMapping, которой можно пометить контроллер:

15 Если контроллеров больше одного, то придется задавать эту аннотацию в каждом контроллере.

16 Spring Boot дает возможность указать префикс на уровне всего приложения, но так лучше не делать, потому что пропадет возможность создавать что-то вне/api, и перестанет работать главная страница.

17 <h2>Коды ответа</h2>

18 Другой важный элемент в REST API - это коды ответа. В этой части REST API полностью полагается на правильное использование стандарта HTTP. Например, для созданного ресурса правильный код ответа - это 201, а не 200. Если произошла внутренняя ошибка - это 500, а если ошибка валидации - это 422. Подробнее об ошибках можно прочитать<a>здесь</a>.

19 В Spring Boot коды возврата можно задавать несколькими способами. Иногда это происходит через ResponseEntity, но в большинстве ситуаций для этого достаточно аннотации @ResponseStatus: