Spring Boot REST API — пошаговое руководство

Главная иллюстрация: концепция REST API и Spring Boot

Пояснение терминов:

REST — представление состояния ресурса через HTTP.
API — интерфейс для взаимодействия приложений.

Что такое REST API и почему Spring Boot

REST API — это служба, которая передаёт запросы и ответы между двумя программными системами через HTTP. Архитектура REST использует URL и набор стандартных глаголов HTTP: POST (создать), GET (прочитать), PUT (обновить) и DELETE (удалить). Spring Boot ускоряет создание таких сервисов за счёт автоконфигурации, встроенного веб-сервера и простых интеграций с JPA и СУБД.

Важно: этот пример ориентирован на обучающую минимальную реализацию. Для продакшн‑проекта добавляйте валидацию, обработку ошибок, аутентификацию и мониторинг.

Начальная инициализация проекта Spring Boot

Создайте новый проект Spring Boot (Spring Initializr или IDE).
Добавьте зависимости: Spring Web, Spring Data JPA, драйвер MySQL (mysql-connector-java). При необходимости добавьте Spring Boot DevTools и Spring Security.
Организуйте проект в стандартные пакеты: model, repository, controller, service (при расширении).

Структура файлов (пример):

Структура проекта: model, repository, controller

Создание модели (Entity)

Ниже — класс модели Customer. Он хранит логику данных и аннотации JPA.

package com.onlineshopaholics.api.model;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Table(name="customer")
@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Integer id;

    @Column(name="customername")
    private String name;

    private String email;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

Кратко о важных аннотациях:

@Entity: помечает класс как JPA‑сущность.
@Table: задаёт имя таблицы в базе данных.
@Id: указывает уникальный идентификатор сущности.
@GeneratedValue/@GenerationType: стратегия авто‑генерации значения для id.
@Column: настраивает имя колонки в таблице.

Когда это не подойдёт: для сложных доменных моделей с бизнес‑логикой лучше разделять Entity и DTO. Также для больших схем имеет смысл управлять миграциями через Flyway/Liquibase.

Репозиторий (Data Access)

Репозиторий предоставляет CRUD‑операции через Spring Data.

package com.onlineshopaholics.api.repository;

import org.springframework.data.repository.CrudRepository;
import com.onlineshopaholics.api.model.Customer;

public interface CustomerRepository extends CrudRepository {}

Пояснение: CrudRepository уже содержит стандартные методы (save, findAll, findById, deleteById и т.д.). При необходимости можно добавлять кастомные запросы через методы с соглашениями по именам или @Query.

Альтернативы: JpaRepository предоставляет дополнительные возможности (paging & sorting). Если нужен более гибкий доступ — используйте Spring Data JPA с Specification или QueryDSL.

Контроллер (REST интерфейс)

Контроллер связывает HTTP‑запросы с операциями над репозиторием.

package com.onlineshopaholics.api.controller;

import java.util.Optional;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.onlineshopaholics.api.model.Customer;
import com.onlineshopaholics.api.repository.CustomerRepository;

@RestController
@RequestMapping("/customers")
public class CustomerController {
    @Autowired
    private CustomerRepository customerRepository;

    // create new customer
    @PostMapping("/add")
    public Customer addNewCustomer(@RequestBody Customer newCustomer){
        Customer user = new Customer();
        user.setName(newCustomer.getName());
        user.setEmail(newCustomer.getEmail());
        customerRepository.save(user);
        return user;       
    }

    // view all customers
    @GetMapping("view/all")
    public @ResponseBody Iterable getAllCustomers(){
        return customerRepository.findAll();
    }

    // view specific customer
    @GetMapping("view/{id}")
    public Optional getCustomer(@PathVariable Integer id) {
        return customerRepository.findById(id);
    }

    // update an existing customer
    @PutMapping("/edit/{id}")
    public String update( @RequestBody Customer updateCustomer, @PathVariable Integer id) {
        return customerRepository.findById(id)
                  .map(customer -> {
                       customer.setName(updateCustomer.getName());
                       customer.setEmail(updateCustomer.getEmail());
                       customerRepository.save(customer);
                       return "Customer details have been successfully updated!";
                  }).orElseGet(() -> {
                       return "This customer doesn't exist";
                  });
    }

    // delete customer
    @DeleteMapping("delete/{id}")
    public String delete(@PathVariable("id")Integer id) {
        customerRepository.deleteById(id);     
        return "Customer has been successfully deleted!";
    }
}

Ключевые аннотации:

@RestController: комбинирует @Controller + @ResponseBody — все методы возвращают тело ответа.
@RequestMapping: базовый путь для контроллера.
@GetMapping/@PostMapping/@PutMapping/@DeleteMapping: соответствуют HTTP‑глаголам.
@RequestBody: преобразует JSON в объект.
@PathVariable: извлекает часть пути как параметр.
@ResponseBody: позволяет вернуть сущность как тело ответа.

Советы по улучшению контроллера:

Перенесите логику в сервисный слой (service) для тестируемости.
Добавьте DTO для входных/выходных представлений.
Обрабатывайте ошибки через @ControllerAdvice.
Валидация: используйте javax/hibernate validator (@Valid, @NotNull и т.д.).

Подключение базы данных (application.properties)

Для подключения к MySQL поместите настройки в src/main/resources/application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.open-in-view=false
spring.datasource.url=jdbc:mysql://${MYSQL_HOST:localhost}:3306/onlineshopaholics
spring.datasource.username=root
spring.datasource.password=securepw
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Пояснения:

spring.jpa.hibernate.ddl-auto — стратегия создания/обновления схемы (validate/update/create/create-drop). Для продакшна используйте миграции (Flyway/Liquibase) вместо update.
Используйте переменные окружения для секретов (паролей) и хостов, не храните их в git.

Краткая методика развёртывания базы:

Создайте базу данных: CREATE DATABASE onlineshopaholics;
Настройте учётную запись с ограниченными правами для приложения.
Проверьте подключение через командную строку или клиент MySQL.

Тестирование REST API через Postman

Для проверки API удобно использовать Postman или curl. Ниже — примеры шагов и скриншоты интерфейса.

POST (создать клиента)

Укажите в заголовке: Content-Type: application/json

Скриншот заголовков запроса POST в Postman

В теле выберите raw → JSON и отправьте, например:

{ "name": "Janet Doe", "email": "janet@example.com" }

Скриншот тела POST запроса в Postman

Ответ будет содержать созданный объект с id:

Скриншот ответа POST с возвращённым объектом и id

GET (получить всех / по id)

Получение всех клиентов:

Скриншот ответа GET всех клиентов

Получение клиента по id:

Скриншот ответа GET по id с детальной информацией

PUT (обновить клиента)

Отправьте PUT /customers/edit/{id} с новым JSON. Пример результата:

Скриншот ответа PUT с подтверждением обновления

DELETE (удалить клиента)

Отправьте DELETE /customers/delete/{id}. Пример ответа:

Скриншот ответа DELETE с подтверждением удаления

Тестирование Spring REST API с помощью JUnit

Spring Boot интегрирует JUnit для тестирования. Базовый план тестов:

Контроллеры: тестируйте конечные точки с MockMvc.
Репозитории: интеграционные тесты с in-memory БД (H2) или тестовой MySQL.
Сервисный слой: юнит‑тесты с Mockito.

Пример простого теста контроллера с MockMvc (схема):

Аннотация @WebMvcTest(CustomerController.class).
Мокируйте CustomerRepository и подставляйте ответы.
Выполните запрос через MockMvc.perform(…) и проверьте статус/тело.

Важно: для интеграционных тестов используйте @SpringBootTest и @Transactional, чтобы откатывать изменения после теста.

Проверка и критерии приёмки

Критерии приёмки для минимального API:

POST /customers/add возвращает 201/200 и объект с ненулевым id.
GET /customers/view/all возвращает список (пустой или с записями).
GET /customers/view/{id} возвращает 200 и корректный объект, либо 404 при отсутствии.
PUT /customers/edit/{id} обновляет поля и возвращает подтверждение.
DELETE /customers/delete/{id} удаляет запись и возвращает подтверждение.

Тесты приёмки:

Юнит‑тесты для контроллера и сервиса.
Интеграционные тесты с тестовой БД.
Инструментальный тест через Postman/Newman для сценариев E2E.

Безопасность и жёсткость (hardening)

Рекомендации по безопасности:

Добавьте аутентификацию и авторизацию (Spring Security, JWT или OAuth2).
Включите валидацию входных данных (@Valid, javax.validation).
Ограничьте права БД учётки приложения до необходимых.
Защитите от SQL‑инъекций и XSS (в основном на клиенте).
Ограничьте скорость запросов и установите CORS‑политику.

Пара практик:

Используйте HTTPS в продакшне.
Логи не должны содержать секреты или пароли.
Храните секреты в менеджере секретов (Vault, облачные секции окружения).

Миграция и совместимость

Если проект расширяется:

Перейдите от spring.jpa.hibernate.ddl-auto=update к миграциям Flyway/Liquibase.
Замените CrudRepository на JpaRepository для более широких возможностей.
При миграции базы проверьте совместимость типов и кодировок (utf8mb4 для MySQL).

Роли и контрольные списки

Разработчик:

Создать Entity, Repository, Controller.
Написать юнит‑тесты.
Проверить работу с Postman.

DevOps:

Настроить CI с шагом тестирования и миграций БД.
Настроить переменные окружения и секреты.
Настроить мониторинг и алерты.

QA:

Прогнать сценарии E2E через Postman/Newman.
Написать тесты производительности и стресс‑тесты.

Шаблон быстрого контроля (cheat sheet)

Команды и конфигурации:

Запуск: mvn spring-boot:run или ./mvnw spring-boot:run
Тесты: mvn test
Локальная MySQL (пример): docker run -e MYSQL_ROOT_PASSWORD=securepw -e MYSQL_DATABASE=onlineshopaholics -p 3306:3306 mysql:8
Подключение через JDBC URL: jdbc:mysql://localhost:3306/onlineshopaholics

Маленький глоссарий (1‑строчные определения)

Entity — класс, отображаемый на таблицу БД.
Repository — слой доступа к данным.
Controller — слой работы с HTTP-запросами.
DTO — объект передачи данных между слоями.
JPA — Java Persistence API, стандарт ORM.

Когда этот подход не подходит

Если требуется сложная бизнес‑логика и строгая разделённость: применяйте многослойную архитектуру (Domain‑Driven Design).
Для очень высоких нагрузок: рассмотрите CQRS, шардирование БД и асинхронную обработку.

Итог и дальнейшие шаги

Ключевые действия после реализации минимального API:

Добавьте валидацию и обработку ошибок.
Введите аутентификацию/авторизацию.
Перенесите миграции схемы на Flyway или Liquibase.
Настройте CI/CD и мониторинг.

Важно: минимальная реализация хороша для прототипа и обучения. Для производства нужны дополнительные меры безопасности, тестирования и наблюдаемости.

Короткое резюме:

Spring Boot упрощает создание REST API.
Spring Data JPA даёт готовые CRUD‑методы.
Для продакшна необходимы миграции, безопасность и тестирование.

Источник: практический пример учебного REST API на Spring Boot.