Как создать REST API контроллер в Spring Boot?

В Spring Boot для создания RESTful веб-сервиса используется аннотация @RestController. Она объединяет @Controller и @ResponseBody, автоматически сериализуя возвращаемые объекты в JSON/XML.

Базовый пример контроллера:

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;

@RestController // 1. Объявляет класс как REST-контроллер
@RequestMapping("/api/users") // 2. Базовый путь для всех методов
public class UserController {

    private final UserService userService;
    // 3. Внедрение зависимости через конструктор
    public UserController(UserService userService) {
        this.userService = userService;
    }

    // 4. Обработчик GET-запроса для получения сущности по ID
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
        UserDto user = userService.getUserById(id);
        return ResponseEntity.ok(user); // Возвращает 200 OK с телом
    }

    // 5. Обработчик POST-запроса для создания новой сущности
    @PostMapping
    public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserRequest request) {
        UserDto createdUser = userService.createUser(request);
        // Возвращает 201 Created с заголовком Location и телом
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(createdUser);
    }

    // 6. Обработчик PUT-запроса для полного обновления
    @PutMapping("/{id}")
    public ResponseEntity<UserDto> updateUser(@PathVariable Long id, 
                                              @Valid @RequestBody UpdateUserRequest request) {
        UserDto updatedUser = userService.updateUser(id, request);
        return ResponseEntity.ok(updatedUser);
    }

    // 7. Обработчик DELETE-запроса
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build(); // Возвращает 204 No Content
    }
}

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

• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping — определяют HTTP-метод и путь.
• @PathVariable — извлекает значение из URL-шаблона (/users/{id}).
• @RequestBody — десериализует тело запроса (JSON) в объект Java.
• @RequestParam — извлекает параметры из строки запроса (/users?name=John).
• @Valid — активирует валидацию входящих данных (JSR-380).
• ResponseEntity — предоставляет полный контроль над HTTP-ответом (статус, заголовки, тело).

Best practices:

• Используйте DTO (Data Transfer Object) для запросов и ответов, а не сущности JPA напрямую.
• Всегда возвращайте осмысленные HTTP-статусы (200, 201, 204, 400, 404, 500).
• Применяйте глобальную обработку исключений через @ControllerAdvice.
• Документируйте API с помощью SpringDoc OpenAPI (Swagger).