REST API를 개발할 때 반드시 알아야 할 주요 애노테이션(Annotation)

1. 컨트롤러 및 매핑 관련 함수 (Annotations)

요청을 받고 응답을 반환하는 엔드포인트를 정의할 때 사용하는 핵심 함수(애노테이션)들입니다.

• @RestController: 해당 클래스가 REST API를 처리하는 컨트롤러임을 선언합니다. @Controller와 @ResponseBody가 결합된 형태입니다.
• @RequestMapping("/api/v1"): 공통으로 사용되는 URL 경로를 클래스 레벨에서 지정합니다.
• @GetMapping("{id}"): HTTP GET 요청을 처리합니다. (조회)
• @PostMapping: HTTP POST 요청을 처리합니다. (생성)
• @PutMapping("{id}"): HTTP PUT 요청을 처리합니다. (전체 수정)
• @PatchMapping("{id}"): HTTP PATCH 요청을 처리합니다. (부분 수정)
• @DeleteMapping("{id}"): HTTP DELETE 요청을 처리합니다. (삭제)

2. 요청 데이터 파싱 함수

클라이언트가 전송한 데이터(파라미터, 본문, 헤더 등)를 자바 객체나 변수로 바인딩할 때 사용합니다.

• @PathVariable: URL 경로에 포함된 변수를 가져옵니다. (예: /users/{id} -> userId)
• @RequestParam: Query Parameter나 폼 데이터를 가져옵니다. (예: /users?page=1&size=10)
• @RequestBody: HTTP 요청의 본문(Body, 주로 JSON)을 자바 객체로 변환합니다.
• @RequestHeader: HTTP 요청 헤더의 값을 가져옵니다. (예: 인증 토큰 등)
• @Valid: 입력값 검증(Validation)을 수행할 때 사용합니다.

3. 응답 제어 관련 함수 (ResponseEntity)

HTTP 상태 코드, 헤더, 본문을 세밀하게 제어하여 응답할 때 사용하는 클래스입니다.

• ResponseEntity.ok(body): 성공(200 OK) 응답과 데이터 반환.
• ResponseEntity.status(HttpStatus.CREATED).body(body): 리소스 생성 성공(201 Created) 응답 반환.
• ResponseEntity.badRequest().body(error): 잘못된 요청(400 Bad Request) 응답 반환.
• ResponseEntity.notFound().build(): 리소스를 찾지 못함(404 Not Found) 응답 반환.

4. 외부 API 호출을 위한 클라이언트 함수

Spring Boot에서 다른 서버의 REST API를 호출할 때 사용하는 도구입니다.

• RestClient (Spring 6 / Spring Boot 3.2+ 권장):
  • 최근 표준으로 권장되는 동기식 HTTP 클라이언트입니다.
  • 예시: restClient.get().uri("/users/{id}", id).retrieve().body(User.class);
• WebClient (Spring WebFlux):
  • 비동기/논블로킹(Reactive) 방식의 HTTP 호출이 필요할 때 사용합니다.
• RestTemplate (Legacy):
  • 기존에 많이 쓰이던 방식이지만, 향후 유지보수를 위해 점진적으로 RestClient로 전환되는 추세입니다.

5. 예외 처리를 위한 함수

API 전역에서 발생하는 에러를 깔끔하게 처리하기 위한 함수들입니다.

• @RestControllerAdvice: 전역 예외 처리를 담당하는 클래스를 지정합니다.
• @ExceptionHandler(Exception.class): 특정 예외 타입이 발생했을 때 실행될 메서드를 지정합니다.

6. JSON 직렬화/역직렬화 함수 (Jackson)

자바 객체와 JSON 문자열 간의 변환을 제어할 때 주로 사용하는 라이브러리(Jackson)의 설정입니다.

• @JsonProperty("field_name"): JSON 키 이름과 자바 필드 이름이 다를 때 매핑합니다.
• @JsonIgnore: 특정 필드가 JSON 변환에서 제외되도록 합니다.
• @JsonFormat(pattern = "yyyy-MM-dd"): 날짜 및 시간 데이터의 포맷을 지정합니다.

7. DTO 필드에 검증 애노테이션 선언

클라이언트가 보내는 요청 데이터(JSON Body 등)를 받는 DTO 클래스에 원하는 검증 규칙을 애노테이션으로 붙입니다. (주로 jakarta.validation.constraints 패키지 제공)

• @NotNull: null을 허용하지 않습니다.
• @NotEmpty: null과 빈 문자열("")을 허용하지 않습니다.
• @NotBlank: null, 빈 문자열, 공백만 있는 문자열(" ")을 허용하지 않습니다.
• @Size(min, max): 문자열이나 컬렉션의 크기/길이를 제한합니다.
• @Min(value) / @Max(value): 숫자의 최솟값과 최댓값을 지정합니다.
• @Email: 이메일 형식인지 검증합니다.
• @Pattern(regexp): 정규식 패턴에 일치하는지 검증합니다.

Java

 

public class UserCreateRequest {

    @NotBlank(message = "이름은 필수입니다.")
    private String name;

    @Email(message = "올바른 이메일 형식이 아닙니다.")
    private String email;

    @Min(value = 18, message = "나이는 18세 이상이어야 합니다.")
    private int age;
}

8. 컨트롤러에서 @Valid 적용하기

요청을 받는 컨트롤러의 메서드 파라미터 앞에 @Valid (또는 @Validated)를 붙여줍니다.

Java

 

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ResponseEntity<String> createUser(@RequestBody @Valid UserCreateRequest request) {
        // 검증을 통과한 경우에만 이 코드가 실행됩니다.
        return ResponseEntity.ok("회원 생성 성공");
    }
}

동작 방식: 클라이언트가 유효하지 않은 데이터를 보내면, Spring은 내부적으로 MethodArgumentNotValidException 예외를 발생시키고 요청을 차단합니다.

9. 검증 실패 예외 처리하기 (@RestControllerAdvice)

검증에 실패했을 때 클라이언트에게 친절한 에러 메시지를 전달하려면 전역 예외 처리기를 작성해야 합니다.

Java

 

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        
        // 발생한 모든 에러 필드와 메시지를 추출
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        
        return ResponseEntity.badRequest().body(errors);
    }
}