전체 메뉴

테마

Chapter 06

검증과 예외 처리

Bean Validation으로 요청을 검증하고 사용자 제약과 RestControllerAdvice를 구현해 성공과 오류 응답을 일관된 형식으로 만듭니다.

난이도
입문
예상 학습
110분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 06입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch06-validation 폴더에서 확인할 수 있습니다.

밤늦게 모니터의 짧은 오류 응답을 보며 원인을 찾지 못해 고민하는 아빠와 아들 개발자
검증 실패를 막는 것에서 그치지 않고 원인을 읽을 수 있는 공통 오류 응답으로 발전시킵니다.

Learning goals

오늘 배울 내용

  • 잘못된 입력을 API 경계에서 검증해야 하는 이유 설명하기
  • DTO 제약과 @Valid로 본문·경로·쿼리 값 검증하기
  • 사용자 정의 제약 애노테이션과 검증기 구현하기
  • @RestControllerAdvice로 검증·비즈니스·프레임워크 예외 응답 통일하기
  • 예상하지 못한 오류에서 내부 정보가 노출되지 않게 처리하기
  1. 경계에서 입력 검증
  2. 표준 제약 선언
  3. 사용자 제약 구현
  4. 검증 테스트
  5. 공통 오류 응답
  6. 예외 정보 보호
이 Chapter의 진행 흐름

막는 일과 알리는 일을 함께 다룹니다

Chapter 05에서 만든 API는 이름을 빈 문자열로 보내도, 나이에 -1을 넣어도 그대로 저장했습니다. 이 Chapter는 두 가지를 다룹니다. 요청을 받는 가장 바깥에서 잘못된 값을 막는 일(검증), 그리고 막힌 결과와 모든 오류를 클라이언트가 읽기 쉬운 하나의 모양으로 알리는 일(예외 처리)입니다.

검증을 붙이면 400이 돌아옵니다. 막는 데는 성공했지만 응답을 열어 보면 무엇이 틀렸는지가 없습니다. 이 불편함이 Chapter 후반의 출발점입니다.

이 Chapter에서 완성할 것

만드는 것 설명
요청 DTO 제약 @NotBlank, @Size, @Email, @Min, @Max 등을 겹쳐 선언
@AllowedEmailDomain 표준에 없는 규칙을 직접 만든 제약 애노테이션과 검증기
ApiResponse, ApiError 성공과 실패를 같은 세 칸(success, data, error)에 담는 공통 응답
ErrorCode, BusinessException 오류 종류를 모은 목록과 서비스가 던지는 예상된 실패
GlobalExceptionHandler @RestControllerAdvice로 모든 예외를 한곳에서 변환
테스트 31건 검증 15건(ch06), 예외 처리 16건(ch07)

예제 모듈은 두 개입니다

JDK 21과 Spring Boot 4.1.1을 기준으로 하며, 저장소 루트에서 Gradle Wrapper를 사용합니다. 이 Chapter는 공개 저장소의 예제 모듈 두 개를 번갈아 씁니다.

절 예제 모듈 다루는 파일
“입력 검증은 왜 가장 바깥에서 하나”부터 “검증 테스트와 막혔지만 이유 없는 400”까지 examples/ch06-validation CreateUserRequest, PatchUserRequest, AllowedEmailDomain, AllowedEmailDomainValidator, 테스트 3종
“@RestControllerAdvice로 응답 모양 통일하기”부터 “자주 만나는 오류와 해결 방법”까지 examples/ch07-exception-handling ApiResponse, ApiError, ErrorCode, BusinessException, GlobalExceptionHandler, DemoController, 테스트 3종

모듈 이름의 번호가 Chapter 번호와 한 칸 어긋나 있는 것은 저장소의 예제 번호가 Chapter 번호와 별개이기 때문입니다. 실행 명령마다 모듈 경로를 적었으므로 그대로 따라가면 됩니다. 실행 결과는 컨테이너에서 JAR로 직접 실행해 얻은 값이고, 검증 문구 중 영어는 실행 환경의 로케일 때문입니다. Windows 실행은 검증하지 못했습니다.

입력 검증은 왜 가장 바깥에서 하나

Chapter 05의 API에 이름이 빈 문자열인 사용자나 나이가 -1인 사용자를 만들 수 있었습니다. 지금은 메모리에 저장될 뿐이라 문제가 눈에 띄지 않지만, 이 값이 데이터베이스 제약에 걸려 터지거나 화면에 이상한 값으로 나가기 시작하면 원인 추적이 어렵습니다.

이 절에서는 검증을 어디에서 해야 하는지를 먼저 정합니다. 코드는 아래 “제약 애노테이션을 선언하고 @Valid로 켜기” 절부터 나옵니다.

검증이 없으면

Chapter 05의 POST /users에 이런 요청을 보낼 수 있었습니다.

POST /users {"name":"","email":"not-an-email","age":-1}

이름이 비었고, 이메일 형식이 아니며, 나이가 음수입니다. 그런데 서버는 201로 저장합니다. 이 데이터가 이후에 만나는 곳마다 방어 코드가 필요해집니다.

  • 화면에서 이름을 보여 줄 때 빈 값 처리
  • 이메일을 보낼 때 형식 확인
  • 통계를 낼 때 음수 나이 제외

방어 코드가 퍼지면 어디에서 막았고 어디는 빠졌는지 알 수 없습니다.

가장 바깥에서 막는다

요청을 받는 순간 잘못된 값을 걸러 내면 안쪽 계층(Service, Repository)은 “값은 이미 올바르다”고 가정하고 쓸 수 있습니다. 검증 규칙이 한 곳에 모이므로 규칙을 바꿀 때도 한 곳만 고칩니다. 안쪽에서 매번 확인하는 방식과 비교하면 코드가 단순해지고 빠뜨릴 위험이 줄어듭니다.

입력 검증과 업무 규칙은 다르다

구분 예 어디서 다루는 절
입력 검증 이름이 비었다, 이메일 형식이 아니다, 나이가 음수다 요청 DTO의 제약 “제약 애노테이션을 선언하고 @Valid로 켜기”
업무 규칙 이미 쓰고 있는 이메일이다, 없는 사용자다 Service가 판단하고 예외를 던짐 “ErrorCode로 검증 오류를 필드별로 알리기”

입력 검증은 값 자체만 보면 판단할 수 있습니다. 업무 규칙은 저장된 데이터나 현재 상태를 알아야 판단할 수 있습니다. 중복 이메일은 저장소를 조회해야 알 수 있으므로 입력 검증으로 할 수 없습니다. 둘을 구분해서 전자는 DTO에, 후자는 Service에 둡니다.

클라이언트도 검증하는데 서버가 또 하는 이유

화면(클라이언트)에서도 입력 검사를 합니다. 하지만 서버는 화면이 검사했다고 믿으면 안 됩니다. API는 curl이나 다른 프로그램으로도 호출되기 때문입니다. 화면 검증은 사용자 편의, 서버 검증은 데이터의 안전을 위한 것입니다.

직접 확인해 보기

Chapter 05의 서버(examples/ch05-crud-api)를 켜고 이 절의 잘못된 요청을 그대로 보내 보세요.

curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"","email":"not-an-email","age":-1}'

응답이 201이면 이 절이 말하는 문제가 재현된 것입니다. 이 요청은 “제약 애노테이션을 선언하고 @Valid로 켜기” 절부터 400으로 막습니다.

검증 방법 세 가지 비교

방법 어디서 장점 단점
컨트롤러 안의 if문 메서드 본문 단순함 중복과 누락, 응답 형식이 제각각
DTO 제약 선언(@NotBlank 등) 요청 객체 규칙이 데이터 옆에 있고 재사용 가능 저장된 데이터가 필요한 규칙은 못 함
Service의 업무 규칙 검사 서비스 DB 조회 같은 상태 기반 판단 가능 입력 형식까지 여기서 하면 안쪽 계층이 어지러워짐

이 Chapter는 입력 형식은 DTO 제약, 상태가 필요한 규칙은 Service로 나눕니다.

자주 하는 오해

오해 사실
화면에서 검사하니 서버는 안 해도 된다 화면을 거치지 않고 API를 직접 호출할 수 있으므로 서버 검증은 필수
검증을 Service 안에서 하면 된다 안쪽에서 하면 잘못된 값이 여러 계층을 지나고, 응답도 일관되지 않음
검증은 한 번에 하나씩 틀린 것을 알려 준다 제약 검사는 모든 위반을 한 번에 모음(“제약 애노테이션을 선언하고 @Valid로 켜기” 절)

확인 문제

  1. “이미 가입된 이메일”은 입력 검증과 업무 규칙 중 어느 쪽인가요?
  2. 검증을 가장 바깥에서 하면 Service 코드가 어떻게 달라지나요?

답: 1) 업무 규칙입니다. 저장된 데이터를 조회해야 알 수 있습니다. 2) 값이 이미 올바르다고 가정하고 업무 로직에 집중할 수 있습니다.

직접 해 보기

  1. 위에서 만든 잘못된 사용자가 목록 조회에 그대로 나오는지 확인하고, 이 데이터를 이용하는 코드가 어떤 방어를 해야 할지 두 가지 적어 보세요.
  2. 입력 검증과 업무 규칙으로 나눠 보세요: “비밀번호는 8자 이상”, “이미 가입한 이메일”, “나이는 0~150”, “탈퇴한 회원은 주문 불가”.

제약 애노테이션을 선언하고 @Valid로 켜기

검증 규칙은 컨트롤러 안의 if문이 아니라 DTO의 필드에 선언합니다. 표준인 Jakarta Validation이 제공하는 애노테이션을 겹쳐 붙이고, 컨트롤러에서 @Valid로 검사를 켭니다.

의존성

검증 기능은 스타터 하나로 추가합니다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
}

이 의존성을 빼면 jakarta.validation 패키지가 없어서 컴파일 단계에서 error: package jakarta.validation does not exist로 막힙니다. 스타터를 지운 복사본에서 이 메시지를 확인했습니다(아래 “자주 만나는 오류와 해결 방법” 절).

제약 애노테이션

애노테이션 의미 null이면
@NotNull null이 아니어야 함 위반
@NotBlank null, 빈 문자열, 공백만 있는 문자열이 아니어야 함 위반
@Size(min, max) 문자열 길이 범위 통과
@Email 이메일 형식 통과
@Min, @Max 숫자 범위 통과

null이면 통과한다

표의 마지막 열이 중요합니다. @Size나 @Min은 값이 있을 때만 검사하고, 값이 반드시 있어야 하는지는 @NotNull이나 @NotBlank가 따로 책임집니다. “값이 있는지”와 “값이 올바른지”를 분리한 설계입니다. 이 성질이 아래 “본문, 경로 변수, 쿼리 파라미터를 검증하기” 절의 PATCH 검증에 그대로 쓰입니다.

DTO에 선언하기

생성 요청 DTO입니다. record의 컴포넌트에 바로 붙입니다.

public record CreateUserRequest(
        @NotBlank @Size(min = 2, max = 20) String name,
        @NotBlank @Email @AllowedEmailDomain({"example.com", "corp.com"}) String email,
        @NotNull @Min(0) @Max(150) Integer age) {
}

주요 코드 설명

  • name: 비어 있으면 안 되고(@NotBlank) 길이가 2~20자여야 합니다(@Size).
  • email: 비어 있으면 안 되고, 이메일 형식이어야 하며, 허용된 도메인이어야 합니다. @AllowedEmailDomain은 아래 “나만의 제약 만들기” 절에서 직접 만듭니다.
  • age: 반드시 있어야 하고(@NotNull) 0~150이어야 합니다.
  • 제약은 겹쳐서 쓸 수 있고, 모두 만족해야 통과합니다.

age가 int가 아니라 Integer인 이유

처음에는 int로 두면 값을 안 보냈을 때 0이 되어 그대로 통과할 것이라고 짐작했습니다. 확인해 보니 달랐습니다. int 필드를 빼고 보내면 Jackson이 Cannot map null into type int로 요청 자체를 거부해서 검증 단계에 오기도 전에 400이 됩니다. 그러면 “age가 비어 있다”는 사실이 @NotNull 위반이 아니라 JSON 변환 오류로 처리되어, 필드별로 일관된 위반 목록을 만들 수 없습니다. 그래서 Integer로 선언하고 @NotNull로 직접 잡습니다. Chapter 05의 PATCH에서 본 Integer 이야기와 이어집니다.

@Valid로 검사를 켠다

제약을 선언만 해서는 아무 일도 일어나지 않습니다. 컨트롤러에서 @Valid를 붙여야 검사가 실행됩니다.

@PostMapping
public ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest request) {
    User created = service.create(request);
    return ResponseEntity.created(URI.create("/users/" + created.id())).body(UserResponse.from(created));
}

@Valid는 “이 객체 내부의 제약을 검사하라”는 표시입니다. 검사는 첫 위반에서 멈추지 않고 모든 필드의 위반을 모아서 한 번에 알립니다.

위반이 있으면 컨트롤러 메서드는 호출되지 않고 MethodArgumentNotValidException이 발생해 기본 응답은 400입니다. 이 예외를 읽기 좋은 응답으로 바꾸는 방법은 “ErrorCode로 검증 오류를 필드별로 알리기” 절에서 봅니다.

제약별 통과·실패 예

제약 통과하는 값 실패하는 값 null일 때
@NotBlank "kim" "", " ", null 실패
@Size(min=2, max=20) "kim" "k", 21자 이상 통과
@Email "kim@example.com" "not-an-email" 통과
@Min(0) @Max(150) 28 -1, 151 통과
@NotNull 0, "" null 실패

@NotBlank와 @NotNull의 차이를 눈여겨보세요. @NotNull은 빈 문자열을 통과시키고, @NotBlank는 빈 문자열과 공백만 있는 문자열까지 막습니다. 문자열 필수 입력에는 @NotBlank를 씁니다.

따라 하기

  1. examples/ch06-validation을 bootRun으로 켭니다.
  2. 아래 요청을 보내 400을 확인합니다.
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"k","email":"kim@gmail.com","age":-1}'
  1. 이름이 짧고, 이메일 도메인이 허용되지 않고, 나이가 음수라 세 가지 위반이 있습니다. 응답에는 이유가 없다는 한계가 있고, 이 한계는 “ErrorCode로 검증 오류를 필드별로 알리기” 절에서 해결합니다.
  2. {"name":"kim","email":"kim@example.com","age":28}을 보내 201이 되는지 확인합니다.

자주 하는 실수

실수 증상 해결
제약만 선언하고 @Valid를 빠뜨림 잘못된 값이 그대로 통과(201) 컨트롤러 파라미터에 @Valid
의존성(spring-boot-starter-validation) 누락 package jakarta.validation does not exist 스타터 추가
@Size만 붙이고 필수라고 생각함 null이 통과 @NotBlank나 @NotNull과 함께 사용

확인 문제

  1. name을 필수이며 2~20자로 하려면 어떤 제약을 붙이나요?
  2. 한 요청에서 이름과 나이가 모두 틀리면 위반은 몇 개 보고되나요?

답: 1) @NotBlank @Size(min = 2, max = 20)입니다. 2) 검사는 첫 위반에서 멈추지 않으므로 둘 다 보고됩니다.

직접 해 보기

  1. @Size(min = 2, max = 20)을 @Size(min = 3)으로 바꾸고 이름 "ab"로 요청해 보세요. 400이 되는지 확인합니다.
  2. name에서 @NotBlank를 빼고 이름 없이 요청하면 통과하는지 예측하고 확인하세요(null이면 @Size가 통과하기 때문입니다). 확인 후 되돌립니다.
  3. @Max(150)을 @Max(100)으로 바꿔 나이 120이 막히는지 확인하세요.

본문, 경로 변수, 쿼리 파라미터를 검증하기

요청 값은 세 곳으로 들어옵니다. 본문(JSON), 경로 변수, 쿼리 파라미터입니다. 이 셋의 검증 방법과 실패 시 예외가 조금씩 다릅니다. 또 같은 DTO라도 PUT과 PATCH는 검증 규칙이 달라야 합니다.

검증은 두 곳에서 일어난다

위치 선언 실패 시 예외
요청 본문 @Valid @RequestBody CreateUserRequest MethodArgumentNotValidException
경로 변수, 쿼리 파라미터 @PathVariable @Positive long id, @RequestParam @Min(1) int limit HandlerMethodValidationException

위치에 따라 예외 종류가 다르다는 점이 중요합니다. “ErrorCode로 검증 오류를 필드별로 알리기” 절에서 응답을 통일할 때 두 예외를 각각 처리합니다.

두 경우 모두 컨트롤러 메서드가 실행되기 전에 막히고 기본 응답은 400입니다. 본문에서는 @Valid를 붙여야 내부 필드의 제약이 검사되고, 인자에는 제약을 직접 붙입니다.

컨트롤러의 선언

@PostMapping
public ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest request) { ... }

@GetMapping
public List<UserResponse> list(@RequestParam(defaultValue = "10") @Min(1) int limit) { ... }

@GetMapping("/{id}")
public ResponseEntity<UserResponse> get(@PathVariable @Positive long id) { ... }
  • @Min(1) int limit: 개수는 1 이상이어야 합니다. Chapter 04에서 검증하지 않았던 limit=0이 이제 막힙니다.
  • @Positive long id: id는 양수여야 합니다. GET /users/-1이 막힙니다.
  • @PathVariable, @RequestParam은 Chapter 04에서 배운 그대로이고 제약만 더해졌습니다.

같은 DTO라도 PUT과 PATCH는 다르다

Chapter 05에서 PUT은 전체 교체, PATCH는 보낸 것만 수정이라고 했습니다. 이 차이는 검증 규칙에도 그대로 나타납니다.

PUT 요청은 생성과 같은 규칙을 모든 필드에 적용합니다. PATCH는 이렇습니다.

public record PatchUserRequest(
        @Size(min = 2, max = 20) String name,
        @Email @AllowedEmailDomain({"example.com", "corp.com"}) String email,
        @Min(0) @Max(150) Integer age) {
}

@NotBlank와 @NotNull을 쓰지 않았습니다. 보내지 않은 필드는 null로 들어오는데 @Size, @Email, @Min은 null을 통과시키므로 “보낸 필드만 검증”하는 효과가 납니다. “제약 애노테이션을 선언하고 @Valid로 켜기” 절에서 본 “null이면 통과” 규칙이 여기서 쓰입니다.

생성/PUT PATCH
필수 제약(@NotBlank, @NotNull) 있음 없음
형식 제약(@Size, @Email, @Min) 있음 있음
보내지 않은 필드 위반 통과(변경 없음)
보낸 필드의 값이 틀림 위반 위반

같은 규칙을 한 DTO로 억지로 맞추지 않고 요청 종류별로 DTO를 나눈 이유가 여기서 다시 확인됩니다.

따라 하기

curl -i "http://localhost:8080/users?limit=0"       # @Min(1) 위반 → 400
curl -i http://localhost:8080/users/-1              # @Positive 위반 → 400
curl -i -X PATCH http://localhost:8080/users/1 -H "Content-Type: application/json" -d '{}'   # 보낸 필드 없음 → 통과
curl -i -X PATCH http://localhost:8080/users/1 -H "Content-Type: application/json" -d '{"age":-5}'  # 보낸 age가 틀림 → 400

앞의 두 줄은 Chapter 04에서 막지 못했던 limit=0을 이제 막는다는 점을 보여 줍니다. 마지막 두 줄은 PATCH가 “보낸 필드만 검증”한다는 규칙을 확인합니다. PATCH 대상 사용자가 없으면 404가 나올 수 있으므로 먼저 사용자를 생성하세요.

자주 하는 실수

실수 증상 해결
PATCH DTO에 @NotBlank를 붙임 보내지 않은 필드가 위반으로 처리됨 PATCH에는 필수 제약을 쓰지 않음
@RequestParam에 제약만 붙이고 defaultValue 누락 파라미터 생략 시 400 기본값 지정
경로·쿼리 제약을 DTO처럼 @Valid로 검사하려 함 검증되지 않음 파라미터에 제약을 직접 붙이기

확인 문제

  1. PUT과 PATCH의 검증 규칙이 다른 이유를 한 문장으로 설명해 보세요.
  2. 쿼리 파라미터 위반과 본문 위반은 예외 클래스가 어떻게 다른가요?

답: 1) PUT은 모든 필드가 필수이고 PATCH는 보낸 필드만 의미가 있기 때문입니다. 2) 본문은 MethodArgumentNotValidException, 경로·쿼리는 HandlerMethodValidationException입니다.

직접 해 보기

  1. GET /users?limit=0과 GET /users/-1을 보내 400을 확인하세요. 응답 본문은 아직 이유가 없습니다.
  2. PATCH /users/1에 {"email":"bad"}를 보내 400을 확인하고, {"age":29}를 보내 200인지 확인하세요.
  3. PatchUserRequest의 name에 @NotBlank를 추가하면 {"age":29}가 왜 400이 되는지 설명해 보세요. 확인 후 되돌립니다.

나만의 제약 만들기

표준 제약으로 표현할 수 없는 규칙도 있습니다. “이메일은 example.com이나 corp.com 도메인만 허용”이 그 예입니다. 이런 규칙을 컨트롤러에 if문으로 쓰는 대신, 제약 애노테이션으로 직접 만들면 표준 제약과 똑같이 DTO에 선언할 수 있습니다.

두 부분으로 구성된다

직접 만든 제약은 선언(애노테이션)과 로직(검증기)으로 나뉩니다.

필드에 붙인 애노테이션이 검증기와 연결되고, 검증기의 isValid 결과가 통과와 위반을 가릅니다.

애노테이션 선언

@Constraint(validatedBy = AllowedEmailDomainValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
public @interface AllowedEmailDomain {
    String message() default "허용되지 않는 이메일 도메인입니다";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
    String[] value() default {"example.com"};
}
  • @Constraint(validatedBy = ...): 이 애노테이션의 검사 로직을 담당할 클래스를 연결합니다.
  • @Target: 붙일 수 있는 위치입니다. 이 예제는 record 컴포넌트에 붙이므로 RECORD_COMPONENT까지 적었습니다. 실제로 RECORD_COMPONENT를 빼고 FIELD, PARAMETER만 남겨도 컴파일과 테스트가 모두 통과했습니다(record 컴포넌트의 애노테이션은 필드, 매개변수 등으로 함께 전파됩니다). 그래도 “record에 붙인다”는 의도를 드러내는 표기로 남겨 둡니다.
  • @Retention(RUNTIME): 실행 중에도 애노테이션을 읽을 수 있게 합니다. 검증은 실행 중에 일어나므로 필수입니다.
  • message, groups, payload: 제약 애노테이션이 반드시 가져야 하는 세 속성(Jakarta Validation 명세의 약속)입니다. 지금은 groups와 payload를 쓰지 않지만 선언해야 합니다.
  • value: 이 제약만의 설정입니다. 허용 도메인 목록이며 기본은 example.com입니다.

검증기

public class AllowedEmailDomainValidator implements ConstraintValidator<AllowedEmailDomain, String> {

    private List<String> domains;

    @Override
    public void initialize(AllowedEmailDomain annotation) {
        this.domains = Arrays.asList(annotation.value());
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext context) {
        if (email == null) {
            return true;
        }
        int at = email.lastIndexOf('@');
        return at >= 0 && domains.contains(email.substring(at + 1));
    }
}

주요 코드 설명

  • ConstraintValidator<AllowedEmailDomain, String>: 첫 번째 타입은 담당 애노테이션, 두 번째는 검사할 값의 타입입니다. 이메일이 문자열이므로 String입니다.
  • initialize: 애노테이션에서 설정(허용 도메인 목록)을 꺼내 보관합니다. 한 번 호출됩니다.
  • isValid: 값이 올바르면 true, 위반이면 false입니다. 마지막 @ 뒤의 도메인이 허용 목록에 있는지 봅니다.
  • email == null이면 true: 값이 없는 것은 이 제약이 책임지지 않습니다. “값이 있는지”는 @NotBlank에 맡깁니다. 표준 제약과 같은 방식(“제약 애노테이션을 선언하고 @Valid로 켜기” 절의 null 통과 규칙)입니다.

사용

@NotBlank @Email @AllowedEmailDomain({"example.com", "corp.com"}) String email

표준 제약과 똑같이 겹쳐 씁니다. @AllowedEmailDomain 없이 @Email만 있으면 kim@gmail.com도 통과하고, 있으면 kim@gmail.com은 위반입니다.

왜 제약으로 만드나

if문으로도 같은 일을 할 수 있지만 제약으로 만들면 얻는 것이 있습니다.

  • 재사용: 생성 DTO, PUT DTO, PATCH DTO에서 한 줄로 씁니다.
  • 일관된 처리: 위반 결과가 표준 제약과 같은 경로(MethodArgumentNotValidException)로 나와 같은 방식으로 응답에 담깁니다.
  • 단위 테스트: 컨트롤러가 아니라 DTO 하나로 검사할 수 있습니다(아래 “검증 테스트와 막혔지만 이유 없는 400” 절).

따라 하기

curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"kim","email":"kim@gmail.com","age":28}'     # 400: 허용되지 않은 도메인
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"kim","email":"kim@corp.com","age":28}'      # 201: 허용 도메인

@Email 형식은 모두 맞지만 gmail.com만 도메인 규칙에서 걸리는 것이 사용자 정의 제약이 필요한 이유입니다.

자주 하는 실수

실수 증상 해결
애노테이션에 message, groups, payload를 빠뜨림 검증 시점에 제약 정의 오류(ConstraintDefinitionException) 세 속성 모두 선언
@Retention(RUNTIME)을 빠뜨림 실행 중에 애노테이션을 읽지 못해 검증이 동작하지 않음 RUNTIME 지정
isValid에서 null이면 false를 반환 선택 필드(PATCH)에서도 위반 null은 true, 필수는 @NotBlank에 맡김
허용 도메인을 코드에 고정 환경별로 바꾸기 어려움 value 속성으로 받음(이 예제)

확인 문제

  1. 검증기에서 null을 통과시키는 이유는 무엇인가요?
  2. @Retention(RetentionPolicy.RUNTIME)을 빼면 어떻게 될까요?

답: 1) “값이 있는가”는 @NotBlank가 맡고 이 제약은 값이 있을 때의 형식만 책임지도록 역할을 나누기 위해서입니다. 2) 실행 중에 애노테이션을 읽을 수 없어 제약이 적용되지 않고, 잘못된 도메인이 그대로 통과합니다.

직접 해 보기

  1. @AllowedEmailDomain({"example.com"})로 줄이고 corp.com 이메일이 막히는지 확인하세요.
  2. 검증기에서 도메인 비교를 대소문자 무시로 바꿔 보세요(equalsIgnoreCase 또는 소문자로 변환). kim@EXAMPLE.com이 통과하는지 확인합니다.
  3. 전화번호가 숫자와 하이픈만으로 이루어져 있는지 보는 @PhoneNumber 제약을 같은 구조로 만들어 보세요.

검증 테스트와 막혔지만 이유 없는 400

제약을 선언했으니 동작을 확인합니다. 두 가지를 합니다. Spring 없이 DTO 하나로 제약을 검사하는 단위 테스트, 그리고 서버를 켜서 잘못된 요청을 직접 보내는 실행입니다. 실행 결과에서 이 Chapter의 첫 번째 문제, “막기는 했는데 이유가 없다”를 만납니다.

제약 단위 테스트

제약은 컨트롤러가 아니라 DTO에 붙어 있으므로 객체 하나로 검사할 수 있습니다.

private final Validator validator = Validation.buildDefaultValidatorFactory().getValidator();

private static Set<String> violated(Set<? extends ConstraintViolation<?>> violations) {
    return violations.stream()
            .map(v -> v.getPropertyPath() + ":" + v.getConstraintDescriptor().getAnnotation().annotationType().getSimpleName())
            .collect(Collectors.toSet());
}

@Test
void missingValuesAreRejectedOnCreate() {
    Set<String> result = violated(validator.validate(new CreateUserRequest(null, null, null)));

    assertEquals(Set.of("name:NotBlank", "email:NotBlank", "age:NotNull"), result);
}

@Test
void customConstraintRejectsOtherDomains() {
    Set<String> result = violated(validator.validate(new CreateUserRequest("kim", "kim@gmail.com", 28)));

    assertEquals(Set.of("email:AllowedEmailDomain"), result);
}

@Test
void patchSkipsFieldsThatWereNotSent() {
    assertTrue(validator.validate(new PatchUserRequest(null, null, null)).isEmpty());
    assertEquals(Set.of("age:Min"), violated(validator.validate(new PatchUserRequest(null, null, -1))));
}

주요 코드 설명

  • Validation.buildDefaultValidatorFactory().getValidator(): 스프링 없이 Jakarta Validation을 직접 쓰는 방법입니다.
  • validator.validate(객체): 위반 목록을 돌려줍니다. 비어 있으면 통과입니다.
  • violated(...): 위반을 "필드:제약 종류" 문자열로 바꿉니다. 예를 들어 name:NotBlank입니다.
  • 메시지 문구를 비교하지 않는 이유: 문구는 로케일에 따라 달라집니다. 이번 실행 환경은 영어 로케일이라 기본 제약의 메시지가 영어였고, 직접 만든 제약의 메시지는 코드에 적은 한국어 그대로였습니다. 문구로 비교하면 환경에 따라 테스트가 깨지므로 “어느 필드가 어떤 제약을 위반했나”만 비교합니다.
  • patchSkipsFieldsThatWereNotSent: 아무것도 보내지 않은 PATCH는 통과하고, 보낸 age가 틀리면 그것만 위반입니다. “본문, 경로 변수, 쿼리 파라미터를 검증하기” 절의 “보낸 필드만 검증”을 증명합니다.

서버를 켜서 잘못된 요청 보내기

OS 실행 이 모듈만 빌드
Linux / macOS ./gradlew :examples:ch06-validation:bootRun ./gradlew :examples:ch06-validation:build
Windows gradlew.bat :examples:ch06-validation:bootRun gradlew.bat :examples:ch06-validation:build

JAR를 실행해 정상 요청 하나와 잘못된 요청 다섯 개를 보냈습니다.

POST /users  {"name":"kim","email":"kim@example.com","age":28}
201 Location: /users/1

POST /users  {"name":"k","email":"kim@gmail.com","age":-1}
400 {"timestamp":"2026-10-17T03:46:38.746Z","status":400,"error":"Bad Request","path":"/users"}

POST /users  {}
400 {"timestamp":"2026-10-17T03:46:38.806Z","status":400,"error":"Bad Request","path":"/users"}

GET /users?limit=0
400 {"timestamp":"2026-10-17T03:46:38.977Z","status":400,"error":"Bad Request","path":"/users"}

GET /users/-1
400 {"timestamp":"2026-10-17T03:46:39.043Z","status":400,"error":"Bad Request","path":"/users/-1"}

PATCH /users/1  {"email":"bad"}
400 {"timestamp":"2026-10-17T03:46:39.109Z","status":400,"error":"Bad Request","path":"/users/1"}

막혔지만 이유가 없다

잘못된 값은 모두 막혔습니다. 그런데 name, email, age 세 가지가 다 틀린 첫 요청과 필드가 하나도 없는 요청이 같은 모양의 응답을 받습니다. timestamp, status, error, path뿐이고 어느 필드가 왜 틀렸는지가 없습니다.

테스트에서는 MethodArgumentNotValidException을 꺼내 세 필드가 모두 보고된 것을 확인했지만, 클라이언트는 그 정보를 받지 못합니다. 화면에서 “어느 칸이 틀렸나요”를 알려 주려면 이 정보가 응답에 실려야 합니다.

검증은 성공했는데 사용자에게 도움이 되는 응답은 아닌 상황입니다. 이 문제를 “@RestControllerAdvice로 응답 모양 통일하기” 절부터 푸는 것이 이 Chapter의 후반입니다.

API 테스트

서버 없이 같은 확인을 MockMvc로 자동화합니다. ch06-validation의 API 테스트는 7건입니다.

테스트 확인하는 것
invalidBodyReturns400AndNamesTheFields 본문 위반이 400이고 세 필드를 보고함
missingFieldsReturn400 필드를 모두 생략해도 400
validBodyIsStillAccepted 올바른 요청은 계속 201
putRequiresEveryField PUT은 모든 필드 필수
patchValidatesOnlySentFields PATCH는 보낸 필드만 검증
pathVariableConstraintReturns400 경로 변수 제약
requestParamConstraintReturns400 쿼리 파라미터 제약

단위 테스트 7건, API 테스트 7건, 컨텍스트 로딩 1건으로 ch06-validation 모듈의 테스트 15건이 모두 통과했습니다.

두 종류 테스트의 역할

DTO에 제약을 잘못 선언한 문제는 단위 테스트에서, @Valid를 빠뜨린 문제는 API 테스트에서 잡힙니다. 같은 입력에 대해 두 계층을 모두 확인하는 이유입니다.

따라 하기

  1. ./gradlew :examples:ch06-validation:test를 실행합니다. 15건이 통과하면 성공입니다.
  2. CreateUserRequest에서 @Max(150)를 지우고 다시 실행합니다. 어느 테스트가 실패하는지 확인하고 되돌립니다.

확인 문제

  1. 위반 목록을 “필드:제약 종류”로 비교하는 이유는 무엇인가요?
  2. 테스트가 400까지만 확인하고 이유는 확인하지 못하는 한계는 어느 절에서 해결하나요?

답: 1) 메시지 문구는 로케일에 따라 달라지기 때문입니다. 2) “@RestControllerAdvice로 응답 모양 통일하기” 절의 공통 응답과 “ErrorCode로 검증 오류를 필드별로 알리기” 절의 필드별 details가 해결합니다.

직접 해 보기

  1. ConstraintTests에 name이 21자인 케이스를 추가해 name:Size가 나오는지 확인하세요.
  2. 서버를 켜고 curl -i로 400 응답을 받아 본문에 위반 정보가 정말 없는지 확인하세요.
  3. 시스템 로케일을 바꿔(예: -Duser.language=ko) 실행했을 때 기본 제약의 메시지 문구가 달라지는지 관찰해 보세요. 단, 이 Chapter에서는 직접 확인하지 않았습니다.

@RestControllerAdvice로 응답 모양 통일하기

Chapter 04에서는 404에 본문이 없었고, “검증 테스트와 막혔지만 이유 없는 400” 절에서는 400에 이유가 없었습니다. 405는 또 다른 모양이었습니다. 같은 서버가 오류마다 다른 모양으로 답하면 클라이언트는 상태 코드마다 따로 해석하는 코드를 써야 합니다.

이 절에서는 모든 응답을 success, data, error 세 칸의 같은 모양으로 맞추고, 예외는 한 곳에서 받아 이 모양으로 바꿉니다.

공통 응답 껍데기

record 하나로 정의합니다. 성공이면 data가, 실패면 error가 채워지고 다른 쪽은 null입니다.

성공이든 실패든 같은 세 칸이므로 클라이언트는 success를 먼저 보고, 실패면 error.code로 분기합니다.

public record ApiResponse<T>(boolean success, T data, ApiError error) {

    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, data, null);
    }

    public static ApiResponse<Void> fail(ApiError error) {
        return new ApiResponse<>(false, null, error);
    }
}

public record ApiError(String code, String message, List<Detail> details) {
    public record Detail(String field, String message) { }
}

주요 코드 설명

  • ApiResponse<T>: 제네릭이라 data에 어떤 타입이든 담을 수 있습니다. 사용자 한 명이면 ApiResponse<UserResponse>입니다.
  • ok(data), fail(error): 정적 팩토리 메서드로 성공과 실패 응답을 만듭니다.
  • ApiError: 오류의 code(기계가 읽는 값), message(사람이 읽는 설명), details(필드별 사유)입니다.
  • Detail은 ApiError 안에 중첩한 record입니다.

클라이언트는 응답이 무엇이든 success부터 보면 됩니다. 실패일 때는 error.code로 분기하고, error.details에 필드별 사유가 있으면 입력 칸 옆에 보여 줍니다.

응답 예

JAR를 실행해 보낸 요청과 응답입니다.

POST /users {"name":"kim","email":"kim@example.com","age":28}
  -> 201 Location: /users/1 {"success":true,"data":{"id":1,"name":"kim","email":"kim@example.com","age":28},"error":null}

POST /users {"name":"kim","email":"kim@example.com","age":28}
  -> 409 {"success":false,"data":null,"error":{"code":"DUPLICATE_EMAIL","message":"이미 사용 중인 이메일입니다. email=kim@example.com","details":[]}}

GET /users/999
  -> 404 {"success":false,"data":null,"error":{"code":"NOT_FOUND","message":"사용자를 찾을 수 없습니다. id=999","details":[]}}

성공 응답에도 "error":null이 그대로 실립니다. 이 예제는 null 필드를 생략하지 않고 항상 세 칸을 보내는 쪽을 택했습니다. 칸이 항상 있으면 클라이언트가 키 존재 여부를 따로 검사하지 않아도 됩니다.

예외를 한곳에서 받는다

컨트롤러나 서비스에서 던진 예외를 @RestControllerAdvice 클래스가 받습니다. 예외 타입마다 @ExceptionHandler 메서드를 두고 같은 모양으로 바꿉니다.

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static ResponseEntity<ApiResponse<Void>> respond(ErrorCode code, String message, List<ApiError.Detail> details) {
        return ResponseEntity.status(code.status())
                .body(ApiResponse.fail(new ApiError(code.name(), message, details)));
    }

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiResponse<Void>> handleBusiness(BusinessException e) {
        return respond(e.code(), e.getMessage(), List.of());
    }
    // ...
}
  • @RestControllerAdvice: 모든 컨트롤러에 적용되는 예외 처리 클래스입니다. Bean으로 등록되므로 컴포넌트 스캔에 잡혀야 합니다.
  • @ExceptionHandler(BusinessException.class): 이 예외가 던져지면 이 메서드가 실행됩니다.
  • respond(...): 오류 코드에서 상태를 꺼내 ApiResponse.fail로 감싸는 공통 도우미입니다. 모든 핸들러가 같은 모양을 만들도록 한 곳에 모았습니다.

핸들러 선택 규칙

핸들러는 가장 구체적인 예외 타입이 먼저 선택됩니다. 그래서 맨 아래의 Exception 핸들러가 “나머지 전부”를 맡을 수 있습니다.

따라 하기

  1. examples/ch07-exception-handling을 bootRun으로 켭니다.
  2. 같은 요청을 두 번 보냅니다.
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"kim","email":"kim@example.com","age":28}'     # 201, success:true
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"kim","email":"kim@example.com","age":28}'     # 409, DUPLICATE_EMAIL
  1. 두 번째 응답의 본문이 {"success":false,"data":null,"error":{"code":"DUPLICATE_EMAIL",...}} 모양이면 성공입니다.

자주 하는 실수

실수 증상 해결
@RestControllerAdvice를 @ControllerAdvice로만 씀 반환값이 JSON이 아니라 뷰 이름으로 처리될 수 있음 JSON API는 @RestControllerAdvice
핸들러 패키지가 시작 클래스 바깥 핸들러가 등록되지 않아 기본 응답으로 돌아감 시작 클래스 패키지 아래에 두기(컴포넌트 스캔)
성공 응답만 껍데기로 감쌈 실패 응답과 모양이 달라 클라이언트 처리가 갈림 성공·실패 모두 같은 껍데기

확인 문제

  1. Exception 핸들러를 맨 아래 하나만 둬도 되는데 구체적인 핸들러를 따로 두는 이유는 무엇인가요?
  2. 응답의 success와 HTTP 상태 코드는 중복 아닌가요?

답: 1) 상태 코드와 오류 코드, 사유를 예외 종류별로 다르게 돌려주기 위해서입니다. 2) 상태 코드는 HTTP 수준의 결과이고, success는 본문만 보는 클라이언트가 한 번에 판단하도록 돕는 보조 값입니다.

직접 해 보기

  1. ApiResponse.ok로 성공 응답을 감싸 보고, 같은 엔드포인트의 응답이 "error":null을 포함하는지 확인하세요.
  2. respond 도우미를 쓰지 않고 핸들러마다 직접 응답을 만든다면 어떤 문제가 생길지 적어 보세요(모양이 달라질 위험).
  3. @RestControllerAdvice를 @ControllerAdvice로 바꾸면 응답 본문이 어떻게 되는지 예측해 보세요. 이 Chapter에서는 실행해 보지 않았습니다.

ErrorCode로 검증 오류를 필드별로 알리기

공통 껍데기를 만들었으니 안에 무엇을 담을지 정합니다. 오류의 종류는 ErrorCode로 한곳에 모으고, 서비스는 예상된 실패를 예외로 던집니다. 그리고 “검증 테스트와 막혔지만 이유 없는 400” 절에서 “이유가 없다”던 검증 오류에 필드별 사유를 담습니다.

ErrorCode: 오류 종류의 목록

public enum ErrorCode {
    VALIDATION_FAILED(HttpStatus.BAD_REQUEST),
    MALFORMED_REQUEST(HttpStatus.BAD_REQUEST),
    NOT_FOUND(HttpStatus.NOT_FOUND),
    METHOD_NOT_ALLOWED(HttpStatus.METHOD_NOT_ALLOWED),
    UNSUPPORTED_MEDIA_TYPE(HttpStatus.UNSUPPORTED_MEDIA_TYPE),
    DUPLICATE_EMAIL(HttpStatus.CONFLICT),
    INTERNAL_ERROR(HttpStatus.INTERNAL_SERVER_ERROR);
    // ...
}

서비스는 의미 있는 예외를 던지기만 하고, 상태 코드와 응답 모양은 핸들러와 ErrorCode가 정합니다.

각 항목이 상태 코드를 하나씩 가집니다. 오류의 이름(code)과 HTTP 상태를 한곳에서 관리하므로, 새 오류를 추가할 때 이 목록만 보면 됩니다. 클라이언트는 메시지 문구가 아니라 code 값으로 분기해야 합니다. 문구는 바뀔 수 있지만 코드는 계약이기 때문입니다.

BusinessException: 예상된 실패

서비스가 던지는 “예상된 실패”는 BusinessException을 상속합니다.

public class BusinessException extends RuntimeException {

    private final ErrorCode code;

    public BusinessException(ErrorCode code, String message) {
        super(message);
        this.code = code;
    }

    public ErrorCode code() {
        return code;
    }
}

public class UserNotFoundException extends BusinessException {

    public UserNotFoundException(long id) {
        super(ErrorCode.NOT_FOUND, "사용자를 찾을 수 없습니다. id=" + id);
    }
}

어떤 오류인지는 ErrorCode가, 사람이 읽을 설명은 메시지가 담습니다. UserNotFoundException과 DuplicateEmailException은 코드와 메시지만 정해 확장한 얇은 클래스입니다.

Service가 예외를 던지면 Controller가 단순해진다

Chapter 05까지는 Service가 “없으면 빈 값(Optional)“을 돌려주고 컨트롤러가 404로 바꿨습니다. 이제는 Service가 의미 있는 예외를 던지고, 상태 코드와 응답 모양은 핸들러가 정합니다.

public User get(long id) {
    return repository.findById(id).orElseThrow(() -> new UserNotFoundException(id));
}

public User create(CreateUserRequest request) {
    assertEmailAvailable(request.email(), -1);
    return repository.save(request.name(), request.email(), request.age());
}

private void assertEmailAvailable(String email, long selfId) {
    repository.findByEmail(email)
            .filter(found -> found.id() != selfId)
            .ifPresent(found -> {
                throw new DuplicateEmailException(email);
            });
}
  • orElseThrow: 값이 없으면 예외를 던집니다. 컨트롤러에서 if/else와 ResponseEntity 조립이 사라집니다.
  • assertEmailAvailable: 같은 이메일을 쓰는 다른 사용자가 있으면 거절합니다. selfId는 수정 대상 자신을 제외하기 위한 값입니다. 자기 이메일을 그대로 두고 수정하는 것은 허용되어야 하기 때문입니다.
  • 이메일 중복은 저장소를 조회해야 알 수 있으므로 “입력 검증은 왜 가장 바깥에서 하나” 절에서 말한 업무 규칙입니다. 입력 검증(DTO의 제약)이 아니라 Service가 판단합니다.

검증 오류가 필드별로 나온다

“검증 테스트와 막혔지만 이유 없는 400” 절에서 이유 없는 400을 받았던 요청을 다시 보냈습니다.

POST /users {"name":"k","email":"kim@gmail.com","age":-1}
  -> 400 {"success":false,"data":null,"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않습니다","details":[{"field":"name","message":"size must be between 2 and 20"},{"field":"age","message":"must be greater than or equal to 0"},{"field":"email","message":"허용되지 않는 이메일 도메인입니다"}]}}

GET /users?limit=0
  -> 400 {"success":false,"data":null,"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않습니다","details":[{"field":"limit","message":"must be greater than or equal to 1"}]}}

세 필드가 모두 사유와 함께 담겼습니다.

아침 햇살이 드는 책상에서 정리된 오류 응답 목록을 확인하며 안도하는 아빠와 아들 개발자

이유 없는 400 앞에서 막막했던 상황이 풀린 장면입니다. 이 응답을 만드는 핸들러는 두 개입니다.

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ApiResponse<Void>> handleBodyValidation(MethodArgumentNotValidException e) {
    List<ApiError.Detail> details = e.getBindingResult().getFieldErrors().stream()
            .map(error -> new ApiError.Detail(error.getField(), error.getDefaultMessage()))
            .toList();
    return respond(ErrorCode.VALIDATION_FAILED, "요청 값이 올바르지 않습니다", details);
}

@ExceptionHandler(HandlerMethodValidationException.class)
public ResponseEntity<ApiResponse<Void>> handleParameterValidation(HandlerMethodValidationException e) {
    List<ApiError.Detail> details = e.getParameterValidationResults().stream()
            .flatMap(result -> result.getResolvableErrors().stream()
                    .map(error -> new ApiError.Detail(
                            result.getMethodParameter().getParameterName(), error.getDefaultMessage())))
            .toList();
    return respond(ErrorCode.VALIDATION_FAILED, "요청 값이 올바르지 않습니다", details);
}
  • 본문 검증 예외에서는 필드 오류(getFieldErrors)를 꺼내 필드 이름과 메시지를 Detail로 만듭니다.
  • limit처럼 쿼리 파라미터의 제약 위반은 HandlerMethodValidationException이라는 다른 예외로 나오기 때문에 핸들러를 따로 두었고, 파라미터 이름을 field에 담습니다. “본문, 경로 변수, 쿼리 파라미터를 검증하기” 절에서 구분한 두 예외 종류가 여기서 쓰입니다.

알아 둘 두 가지

  • details의 순서: name, age, email 순으로 나왔는데 DTO에 선언한 순서(name, email, age)와 다릅니다. 순서를 보장하는 계약이 아니라서 테스트도 containsInAnyOrder로 필드 집합만 확인합니다.
  • 메시지 언어: 기본 제약의 문구(size must be between 2 and 20)는 실행 환경의 로케일을 따라 영어로 나왔고, 직접 만든 제약의 문구는 코드에 적은 한국어입니다. 클라이언트가 message를 사용자에게 그대로 보여 주려면 메시지 설정을 통일해야 하는데, 이 Chapter에서는 다루지 않았습니다.

따라 하기

curl -i http://localhost:8080/users/999                       # 404, NOT_FOUND
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"k","email":"kim@gmail.com","age":-1}'          # 400, VALIDATION_FAILED + details 3개
curl -i "http://localhost:8080/users?limit=0"                 # 400, VALIDATION_FAILED

두 번째 응답의 details에 name, email, age 세 필드가 각각 사유와 함께 담기면 성공입니다.

자주 하는 실수

실수 증상 해결
서비스가 Optional.empty()를 돌려주고 컨트롤러에서 404를 조립 컨트롤러마다 같은 분기 반복 orElseThrow로 예외 던지기
쿼리 파라미터 위반의 핸들러가 없음 본문 위반만 필드별로 나오고 limit은 기본 응답 HandlerMethodValidationException 핸들러 추가
details 순서에 의존하는 클라이언트 선언 순서와 달라 오작동 순서가 아니라 field 값으로 찾기

확인 문제

  1. 이메일 중복 검사를 DTO 제약이 아니라 Service에 두는 이유는 무엇인가요?
  2. ErrorCode를 enum으로 모으면 무엇이 좋아지나요?

답: 1) 저장된 데이터를 조회해야 알 수 있는 업무 규칙이기 때문입니다. 2) 오류 이름과 상태 코드가 한곳에서 관리되어 일관성이 유지되고 오타를 컴파일러가 잡습니다.

직접 해 보기

  1. 같은 이메일로 사용자를 두 번 만들어 409와 DUPLICATE_EMAIL을 확인하세요.
  2. 사용자 A의 이메일을 사용자 B의 이메일로 PUT해서 409가 되는지, A가 자기 이메일 그대로 PUT하면 200인지 확인하세요.
  3. ErrorCode에 FORBIDDEN(HttpStatus.FORBIDDEN)을 추가하고 이를 쓰는 BusinessException 하위 클래스를 만들어 보세요.

프레임워크 예외와 예상 못한 오류를 안전하게 응답하기

검증 실패와 업무 예외는 우리가 만든 예외입니다. 그 밖에 프레임워크가 던지는 예외(깨진 JSON, 지원하지 않는 메서드 등)와, 아무도 예상하지 못한 예외도 있습니다. 이 절에서는 이 둘을 같은 모양으로 받고, 특히 예상하지 못한 오류에서 내부 정보가 응답에 새지 않게 하는 방법을 봅니다.

프레임워크 예외도 같은 모양으로

Chapter 04에서 모양이 제각각이던 응답들도 핸들러를 추가해 같은 껍데기에 넣었습니다.

예상 가능한 실패는 의미 있는 코드로, 예상하지 못한 오류는 일반 문구로 응답하고 상세는 서버 로그에만 남깁니다.

POST /users {not json
  -> 400 {"success":false,"data":null,"error":{"code":"MALFORMED_REQUEST","message":"요청 본문을 읽을 수 없습니다","details":[]}}

GET /users/abc
  -> 400 {"success":false,"data":null,"error":{"code":"MALFORMED_REQUEST","message":"'id' 값의 형식이 올바르지 않습니다","details":[]}}

DELETE /users
  -> 405 {"success":false,"data":null,"error":{"code":"METHOD_NOT_ALLOWED","message":"지원하지 않는 HTTP 메서드입니다: DELETE","details":[]}}

GET /no/such/path
  -> 404 {"success":false,"data":null,"error":{"code":"NOT_FOUND","message":"존재하지 않는 경로입니다","details":[]}}

각 응답을 만드는 핸들러는 예외 타입과 오류 코드의 짝입니다.

예외 오류 코드 상황
HttpMessageNotReadableException MALFORMED_REQUEST 깨진 JSON
MethodArgumentTypeMismatchException MALFORMED_REQUEST /users/abc처럼 타입이 안 맞음
HttpRequestMethodNotSupportedException METHOD_NOT_ALLOWED 지원하지 않는 메서드
HttpMediaTypeNotSupportedException UNSUPPORTED_MEDIA_TYPE Content-Type 문제
NoResourceFoundException NOT_FOUND 매핑이 없는 경로

깨진 JSON의 응답에는 파서가 낸 내부 메시지를 싣지 않았습니다. 라이브러리의 문구가 그대로 나가면 내부 구현이 드러나고 문구도 마음대로 바뀝니다. 존재하지 않는 경로는 NoResourceFoundException이라는 예외로 올라오기 때문에 이것도 핸들러로 받을 수 있었습니다.

예상하지 못한 오류는 일반 문구만

마지막 Exception 핸들러는 가장 조심해서 썼습니다.

@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Void>> handleUnexpected(Exception e) {
    log.error("Unhandled exception", e);
    return respond(ErrorCode.INTERNAL_ERROR, "서버 내부 오류가 발생했습니다", List.of());
}
  • log.error("...", e): 원인과 스택 트레이스는 서버 로그에만 남깁니다. 개발자는 로그에서 원인을 찾습니다.
  • 응답에는 "서버 내부 오류가 발생했습니다"라는 일반 문구만 담습니다.

예외 메시지에는 SQL, 파일 경로, 비밀값 같은 내부 정보가 섞일 수 있습니다. 응답에 그대로 내보내면 공격자에게 힌트를 줍니다. 이를 확인하려고 /demo/error가 일부러 이런 예외를 던지게 했습니다.

@GetMapping("/demo/error")
public String error() {
    throw new IllegalStateException("db password is hunter2");
}
GET /demo/error
  -> 500 {"success":false,"data":null,"error":{"code":"INTERNAL_ERROR","message":"서버 내부 오류가 발생했습니다","details":[]}}

응답에는 비밀번호가 보이지 않습니다. 테스트도 이 문구가 응답에 없는지를 확인합니다. 이 /demo/error는 학습용이며 실제 서비스에는 두지 않습니다.

로그와 응답의 역할

서버 로그 응답
읽는 사람 개발자, 운영자 클라이언트 개발자, 사용자
담는 것 원인, 스택 트레이스, 상세 오류 코드, 안전한 설명, 필드별 사유
내부 정보 포함해도 됨(접근 통제 하에) 포함하면 안 됨

로그를 체계적으로 남기는 방법은 Chapter 22에서 다룹니다.

테스트 결과

GlobalExceptionHandlerTests가 위 시나리오를 모두 고정합니다. 12건의 핸들러 테스트에 ApiResponseTests 3건과 컨텍스트 로딩 1건을 더해 ch07-exception-handling 모듈의 테스트 16건이 모두 통과했습니다.

OS 실행 이 모듈만 빌드
Linux / macOS ./gradlew :examples:ch07-exception-handling:bootRun ./gradlew :examples:ch07-exception-handling:build
Windows gradlew.bat :examples:ch07-exception-handling:bootRun gradlew.bat :examples:ch07-exception-handling:build

따라 하기

curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" -d '{not json'   # 400 MALFORMED_REQUEST
curl -i http://localhost:8080/users/abc                                                        # 400 MALFORMED_REQUEST
curl -i http://localhost:8080/demo/error                                                       # 500 INTERNAL_ERROR

세 번째 응답에 “db password is hunter2”라는 예외 메시지가 보이지 않고 일반 문구만 있어야 합니다. 서버 콘솔에서는 Unhandled exception 로그와 함께 원인을 볼 수 있습니다.

자주 하는 실수

실수 증상 해결
e.getMessage()를 응답에 그대로 담음 SQL, 경로, 비밀값 같은 내부 정보 노출 일반 문구 + 서버 로그
예외를 삼키고 로그를 남기지 않음 장애 원인을 찾을 수 없음 log.error("...", e)로 스택 트레이스 기록
프레임워크 예외 핸들러를 빠뜨림 일부 4xx가 기본 응답 모양으로 남음 예외 타입별 핸들러 추가

확인 문제

  1. 500 응답에 상세 메시지를 넣지 않는 이유는 무엇인가요?
  2. 로그와 응답이 담는 내용은 각각 어떻게 다른가요?

답: 1) 내부 구현과 비밀값이 외부에 노출될 수 있기 때문입니다. 2) 로그는 원인과 스택 트레이스를 개발자용으로, 응답은 안전한 설명과 오류 코드를 클라이언트용으로 담습니다.

직접 해 보기

  1. GET /demo/error를 호출하고 서버 콘솔에서 Unhandled exception 로그와 스택 트레이스를 찾아 보세요. 응답에는 없고 로그에는 있는 정보를 확인합니다.
  2. Exception 핸들러에서 e.getMessage()를 응답에 담도록 바꿔 보고, 비밀 문구가 새는 것을 확인한 뒤 되돌리세요.
  3. GET /no/such/path와 DELETE /users의 응답이 같은 세 칸 모양인지 확인하세요.

자주 만나는 오류와 해결 방법

검증은 통과해 버리는 것이 가장 위험하고, 예외 처리는 처리기가 조용히 빠지는 것이 가장 찾기 어렵습니다. 이 절에서는 이 Chapter의 대표적인 오류 세 가지를 일부러 만들어 증상과 해결을 확인합니다. 아래는 예제를 한 군데씩 바꿔 테스트를 돌린 결과이고, 바꾼 코드는 되돌렸습니다.

오류 1: @Valid를 빠뜨리면 검증이 건너뛰어진다

create(@Valid @RequestBody ...)에서 @Valid를 지웠습니다. 요청 DTO의 제약은 그대로인데 아무도 검사하지 않습니다. 테스트 15건 중 2건이 실패했습니다.

invalidBodyReturns400AndNamesTheFields()
Status expected:<400> but was:<201>
missingFieldsReturn400()
NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because the return value of "CreateUserRequest.age()" is null

잘못된 입력이 201(생성됨)으로 통과했고, 필드를 생략한 요청은 한참 뒤 서비스에서 NPE로 터졌습니다. 오류 메시지에 @Valid라는 말은 없습니다. 입력이 틀렸는데 400이 아니라 201이나 500이 나온다면 컨트롤러 파라미터의 @Valid를 먼저 봅니다.

오류 2: 검증 어노테이션이 컴파일되지 않는다

spring-boot-starter-validation 의존성을 빼면 제약 애노테이션이 있는 파일이 컴파일되지 않습니다.

AllowedEmailDomain.java:9: error: package jakarta.validation does not exist

jakarta.validation 패키지가 없다는 메시지는 이 스타터를 확인하라는 신호입니다.

오류 3: 처리기가 등록되지 않았다

GlobalExceptionHandler에서 @RestControllerAdvice를 지웠습니다. @ExceptionHandler 메서드는 그대로인데 컨트롤러 밖의 예외를 받지 못합니다. 예외 처리 모듈(ch07-exception-handling)의 테스트 16건 중 11건이 실패했습니다.

notFoundBecomes404WithCode()
ServletException: Request processing failed: com.jqdom.curriculum.ch07.UserNotFoundException: 사용자를 찾을 수 없습니다. id=999999
missingContentTypeBecomes415()
No value at JSON path "$.error.code"

예외가 정의한 응답 형식이 아니라 Spring의 기본 오류 처리로 흘러가 본문이 비거나 모양이 달라졌습니다. 단서는 스택 트레이스에 우리가 만든 예외 이름이 그대로 보인다는 점입니다. 처리기 메서드가 있는데 호출되지 않으면 클래스의 @RestControllerAdvice(또는 @ControllerAdvice)를 확인하고, 같은 패키지 아래에서 컴포넌트 스캔에 잡히는지 봅니다(Chapter 03의 스캔 범위).

세 오류의 공통점

세 오류는 모두 오류 없이 조용히 잘못 동작하거나 기본 처리로 돌아가는 형태입니다.

아래 점검표를 위에서부터 차례로 확인하세요. @Valid 누락처럼 겉으로 오류가 없는 경우를 찾는 가장 좋은 방법은 잘못된 입력을 일부러 보내 400이 나오는지 보는 테스트입니다.

증상별 점검표

증상 가장 먼저 볼 것
잘못된 입력이 201 컨트롤러 파라미터의 @Valid
필드를 생략했는데 NPE(500) @Valid와 @NotNull
package jakarta.validation does not exist spring-boot-starter-validation
응답 본문이 기본 오류 모양 @RestControllerAdvice, 스캔 범위
스택 트레이스에 우리 예외가 그대로 처리기 메서드의 @ExceptionHandler 대상 타입

직접 해 보기

  1. 복사한 저장소에서 @Valid를 지우고 몇 건이 실패하는지 세어 보세요. 확인 후 되돌립니다.
  2. 의존성에서 검증 스타터를 지워 컴파일 오류 메시지를 직접 읽어 보세요.
  3. @RestControllerAdvice를 지운 상태에서 GET /users/999가 어떤 응답을 주는지 관찰하세요. 이 응답은 이 Chapter에서 확인한 값이 아니므로 직접 본 결과를 적어 보세요.

용어와 참고 자료

이 Chapter에 나온 용어와 참고 사이트를 모았습니다. Chapter 04와 Chapter 05에서 설명한 용어는 다시 쓰지 않습니다.

참고한 자료

검증

용어 설명
입력 검증 값 자체만 보고 판단하는 검증입니다. 이름이 비었는지, 형식이 맞는지 등입니다.
업무 규칙 저장된 데이터나 상태를 알아야 판단하는 규칙입니다. 중복 이메일 등입니다.
Jakarta Validation 객체 필드에 제약을 애노테이션으로 선언하는 표준입니다. 구현체는 Hibernate Validator입니다.
@NotNull / @NotBlank null 불가 / null, 빈 문자열, 공백만 있는 문자열 불가입니다.
@Size / @Email / @Min / @Max 길이 범위 / 이메일 형식 / 숫자 최소·최대입니다. 값이 null이면 통과합니다.
@Positive 0보다 큰 수여야 합니다.
@Valid 이 객체 내부의 제약 검사를 켜라는 표시입니다. 요청 본문에 붙입니다.
spring-boot-starter-validation 검증 기능을 추가하는 스타터 의존성입니다.
MethodArgumentNotValidException @Valid 본문 검증이 실패했을 때 발생하는 예외입니다.
HandlerMethodValidationException 경로 변수나 쿼리 파라미터의 인자 제약이 실패했을 때 발생하는 예외입니다.
@Constraint 직접 만드는 제약 애노테이션에 붙여 검증기를 연결합니다.
ConstraintValidator 직접 만든 제약의 검사 로직을 담는 인터페이스입니다.
Validator Spring 없이 제약을 직접 검사하는 Jakarta Validation의 진입 객체입니다.
로케일 언어와 지역 설정입니다. 기본 제약 메시지의 언어가 이를 따릅니다.

예외 처리

용어 설명
공통 응답 성공과 실패를 같은 껍데기(success, data, error)에 담는 응답 형식입니다.
@RestControllerAdvice 모든 컨트롤러의 예외를 한곳에서 처리하는 클래스에 붙입니다. 결과를 JSON 본문으로 씁니다.
@ExceptionHandler 특정 예외 타입을 받아 응답으로 바꾸는 메서드에 붙입니다. 가장 구체적인 타입이 먼저 선택됩니다.
ErrorCode 오류 종류와 상태 코드를 한곳에 모은 목록입니다. 클라이언트가 분기할 때 쓰는 계약입니다.
BusinessException 서비스가 던지는 예상된 실패입니다. 오류 코드를 함께 가집니다.
409 Conflict 요청이 현재 자원의 상태와 충돌할 때의 상태 코드입니다. 이 Chapter에서는 이메일 중복입니다.
HttpMessageNotReadableException 깨진 JSON 등 본문을 읽을 수 없을 때의 예외입니다.
MethodArgumentTypeMismatchException 경로·쿼리 값의 타입 변환 실패 예외입니다.
NoResourceFoundException 매핑이 없는 경로로 요청했을 때의 예외입니다.
정보 노출 예외 메시지에 섞인 내부 정보(SQL, 경로, 비밀값)가 응답에 새어 나가는 일입니다.

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
생성 요청 DTO CreateUserRequest.java
컨트롤러 UserController.java
빌드 파일 build.gradle
PATCH 요청 DTO PatchUserRequest.java
제약 애노테이션 AllowedEmailDomain.java
검증기 AllowedEmailDomainValidator.java
제약 단위 테스트 ConstraintTests.java
API 테스트 UserValidationApiTests.java
예외 핸들러 GlobalExceptionHandler.java
공통 응답 ApiResponse.java
오류 코드 ErrorCode.java
비즈니스 예외 BusinessException.java
서비스 UserService.java
데모 컨트롤러 DemoController.java
핸들러 테스트 GlobalExceptionHandlerTests.java

직접 해보기

  1. ./gradlew :examples:ch06-validation:test와 ./gradlew :examples:ch07-exception-handling:build를 실행해 테스트 15건과 16건이 모두 통과하는지 확인하세요.
  2. 두 모듈의 서버를 차례로 켜고 같은 잘못된 요청 {"name":"k","email":"kim@gmail.com","age":-1}을 보내 보세요. ch06-validation은 이유 없는 400을, ch07-exception-handling은 필드별 details가 담긴 400을 돌려주는지 비교합니다.
  3. PatchUserRequest에 @NotBlank를 붙였다가 되돌리며, 보내지 않은 필드가 위반으로 바뀌는 과정을 “제약 애노테이션을 선언하고 @Valid로 켜기” 절의 “null이면 통과” 규칙으로 설명해 보세요.
  4. “자주 만나는 오류와 해결 방법” 절의 세 가지 중 하나를 재현하고, 증상별 점검표만 보고 원인을 찾은 뒤 원래 코드로 되돌리세요.

이번 장의 정리

  • 잘못된 입력은 요청을 받는 가장 바깥에서 막습니다. 값만 보고 판단하는 입력 검증은 DTO 제약에, 저장된 상태가 필요한 업무 규칙은 Service에 둡니다.
  • 제약은 DTO에 애노테이션으로 선언하고 @Valid로 켭니다. @Size, @Email, @Min 등은 null을 통과시키므로 필수 여부는 @NotNull이나 @NotBlank가 맡고, PATCH는 이 성질로 보낸 필드만 검증합니다.
  • 본문 위반은 MethodArgumentNotValidException, 경로 변수와 쿼리 파라미터 위반은 HandlerMethodValidationException으로 나옵니다.
  • 표준에 없는 규칙은 @Constraint와 ConstraintValidator로 직접 만들며, 애노테이션은 message, groups, payload를 반드시 가집니다.
  • 성공과 실패를 success, data, error 세 칸으로 통일하고, @RestControllerAdvice의 @ExceptionHandler가 예외를 이 모양으로 바꿉니다. 오류 종류와 상태 코드는 ErrorCode가 한곳에서 관리합니다.
  • 예상하지 못한 오류는 원인을 서버 로그에만 남기고 응답에는 일반 문구만 돌려줍니다.
  • @Valid 누락과 @RestControllerAdvice 누락은 오류 없이 조용히 잘못 동작하므로, 잘못된 입력을 일부러 보내는 테스트로 잡습니다.

여기까지의 저장소는 메모리입니다. 다음 Chapter 07 DataSource와 H2에서 메모리 저장소를 벗어나 데이터베이스를 연결합니다.

FAQ

자주 묻는 질문

DTO에 제약 애노테이션을 붙이면 검증이 자동으로 실행되나요?

요청 본문에는 컨트롤러 매개변수의 @Valid가 필요합니다. 경로 변수와 쿼리 파라미터는 메서드 검증 방식과 발생 예외가 다르므로 각각 테스트해야 합니다.

@NotNull과 @NotBlank는 어떻게 다른가요?

@NotNull은 null만 막고 빈 문자열은 허용합니다. @NotBlank는 null, 빈 문자열, 공백만 있는 문자열을 모두 막습니다.

오류 응답을 공통 형식으로 만드는 이유는 무엇인가요?

클라이언트가 상태 코드마다 다른 본문을 추측하지 않고 success, data, error라는 같은 구조로 성공과 실패를 처리할 수 있습니다.

모든 Exception을 한 핸들러에서 처리하면 되나요?

마지막 안전망은 필요하지만 예상 가능한 예외를 먼저 구체적으로 처리해야 올바른 상태와 오류 코드를 줄 수 있습니다. 예상하지 못한 오류는 내부 메시지를 숨긴 500으로 변환합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토