Какие знаешь аннотации для обработки http запросов?

Аннотации для обработки HTTP запросов в Java

Основные аннотации Spring Web

В Spring Framework существует набор аннотаций для создания REST контроллеров и обработки HTTP запросов. Я работал с этими инструментами на протяжении многих лет.

1. @RequestMapping - Универсальная аннотация

@RequestMapping — основная аннотация для маршрутизации запросов:

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // Обработка GET запроса
    @RequestMapping(method = RequestMethod.GET)
    public List<User> getAllUsers() {
        return userService.findAll();
    }
    
    // Обработка POST запроса
    @RequestMapping(method = RequestMethod.POST)
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }
}

2. @GetMapping, @PostMapping и другие методы

Сокращённые аннотации для конкретных HTTP методов (рекомендуется использовать):

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // GET запрос на получение всех пользователей
    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }
    
    // GET запрос на получение пользователя по ID
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.findById(id);
    }
    
    // POST запрос на создание пользователя
    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }
    
    // PUT запрос на обновление пользователя
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userService.save(user);
    }
    
    // DELETE запрос на удаление пользователя
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
    }
    
    // PATCH запрос на частичное обновление
    @PatchMapping("/{id}")
    public User partialUpdate(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
        return userService.partialUpdate(id, updates);
    }
}

3. @PathVariable - Параметры в URL пути

@PathVariable используется для извлечения переменных из URL пути:

@GetMapping("/api/users/{userId}/posts/{postId}")
public Post getPost(
    @PathVariable Long userId,
    @PathVariable Long postId) {
    return postService.findByUserAndId(userId, postId);
}

// Альтернатива с явным указанием имени
@GetMapping("/api/users/{user_id}")
public User getUser(@PathVariable("user_id") Long userId) {
    return userService.findById(userId);
}

4. @RequestParam - Параметры запроса (Query String)

@RequestParam для получения параметров из query string:

@GetMapping("/api/users")
public List<User> searchUsers(
    @RequestParam String name,
    @RequestParam(required = false) Integer age,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int pageSize) {
    return userService.search(name, age, page, pageSize);
}

// Использование: GET /api/users?name=John&age=30&page=1

5. @RequestBody - Тело запроса

@RequestBody для десериализации JSON/XML тела запроса в объект:

@PostMapping("/api/users")
public User createUser(@RequestBody User user) {
    // user автоматически десериализуется из JSON
    return userService.save(user);
}

// Пример запроса:
// POST /api/users
// Content-Type: application/json
// {"name": "John", "email": "john@example.com"}

6. @ResponseBody и @RestController

@ResponseBody указывает, что возвращаемое значение нужно сериализовать в JSON:

import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    @ResponseBody // Сериализует результат в JSON
    public List<User> getAllUsers() {
        return userService.findAll();
    }
}

// Эквивалентно использованию @RestController:
@RestController // Содержит @Controller + @ResponseBody на уровне класса
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    public List<User> getAllUsers() { // @ResponseBody уже применена
        return userService.findAll();
    }
}

7. @RequestHeader - Заголовки запроса

@RequestHeader для получения значений заголовков HTTP:

@PostMapping("/api/users")
public User createUser(
    @RequestBody User user,
    @RequestHeader("Authorization") String token,
    @RequestHeader("X-Client-ID") String clientId,
    @RequestHeader(value = "X-Custom-Header", required = false) String customHeader) {
    
    validateToken(token);
    return userService.save(user);
}

8. @CookieValue - Значения из Cookie

@CookieValue для получения значений из cookies:

@GetMapping("/api/profile")
public UserProfile getProfile(
    @CookieValue("session_id") String sessionId,
    @CookieValue(value = "preferences", required = false) String preferences) {
    
    User user = userService.findBySessionId(sessionId);
    return userService.buildProfile(user, preferences);
}

9. @ModelAttribute - Привязка данных формы

@ModelAttribute для привязки данных HTML формы к объекту:

@PostMapping("/api/users/form")
public String createUserFromForm(@ModelAttribute User user) {
    // Данные из формы автоматически привязаны к User
    userService.save(user);
    return "redirect:/users";
}

// HTML форма:
// <form method="post" action="/api/users/form">
//   <input name="name" type="text"/>
//   <input name="email" type="email"/>
// </form>

10. @ExceptionHandler - Обработка исключений

@ExceptionHandler для обработки исключений в контроллере:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.findById(id);
    }
    
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException e) {
        ErrorResponse error = new ErrorResponse("User not found", e.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

11. @ResponseStatus - Статус ответа

@ResponseStatus для установки HTTP статуса ответа:

@PostMapping("/api/users")
@ResponseStatus(HttpStatus.CREATED) // Вернёт 201 вместо 200
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT) // Вернёт 204
public void deleteUser(@PathVariable Long id) {
    userService.deleteById(id);
}

12. @Valid и @Validated - Валидация данных

@Valid для валидации объектов на основе аннотаций (JSR-303/JSR-380):

import javax.validation.Valid;
import org.hibernate.validator.constraints.Email;

@PostMapping("/api/users")
public User createUser(@Valid @RequestBody User user) {
    // Если валидация не пройдена, вернётся 400 Bad Request
    return userService.save(user);
}

public class User {
    @NotBlank(message = "Name cannot be blank")
    private String name;
    
    @Email(message = "Email must be valid")
    private String email;
    
    @Min(18)
    @Max(120)
    private Integer age;
}

Практический пример полного контроллера

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }
    
    @GetMapping
    public List<User> getAllUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {
        return userService.findAll(page, size);
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
    
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public User createUser(
        @Valid @RequestBody User user,
        @RequestHeader("X-Source") String source) {
        return userService.save(user);
    }
    
    @PutMapping("/{id}")
    public User updateUser(
        @PathVariable Long id,
        @Valid @RequestBody User user) {
        user.setId(id);
        return userService.save(user);
    }
    
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
    }
    
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleNotFound(UserNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(e.getMessage());
    }
}

Summary

Основные аннотации для обработки HTTP запросов:

• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping — для маршрутизации
• @PathVariable — параметры URL пути
• @RequestParam — параметры query string
• @RequestBody — тело запроса
• @RequestHeader — заголовки
• @CookieValue — cookies
• @Valid — валидация данных
• @ResponseStatus — установка статуса ответа

Эти аннотации критически важны для создания чистых и выразительных REST API в Spring приложениях.