📄 [문서] DTO 예외처리 및 Spring Validation

[Chuseok22]

❌ 문제 상황

No response

📝 핵심 내용과 방향성

DTO 예외처리

• Request DTO내부에서 Spring Validation 어노테이션 사용 시 MethodArgumentNotValidException을 핸들링

GlobalExceptionHandler

• GlobalExceptionHandler내부에 @ExceptionHandler(MethodArgumentNotValidException.class)적용

  @RestControllerAdvice
  @Slf4j
  public class GlobalExceptionHandler {
  
      /**
       * 1) Validation 예외 처리
       */
      @ExceptionHandler(MethodArgumentNotValidException.class)
      public ResponseEntity<ApiResponse<?>> handleValidationException(MethodArgumentNotValidException e) {
          // Validation 에러 정보를 담을 Map 생성
          Map<String, String> validation = new HashMap<>();
          for (FieldError fieldError : e.getFieldErrors()) {
              validation.put(fieldError.getField(), fieldError.getDefaultMessage());
          }
  
          // 공통 응답 DTO를 활용해 반환
          // ErrorCode.INVALID_REQUEST -> 400
          ApiResponse<?> response = ApiResponse.errorWithValidation(
                  String.valueOf(HttpStatus.BAD_REQUEST.value()), // "400"
                  "잘못된 요청입니다.",
                  validation
          );
  
          return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
      }
  }

DTO

• Request DTO 설계시 @NotBlank, @Email등의 Spring Validation 어노테이션 사용

• @NotBlank: 해당 필드가 null또는 ""공백인 경우

• @Email: 해당 필드가 이메일 형식에 어긋나는 경우

• @Pattern(regexp = "정규식", message = "오류 메시지": 정규식 패턴 검증

  @ToString
  @AllArgsConstructor
  @Getter
  @Setter
  @Builder
  public class SignUpRequest {
  
      @NotBlank(message = "이메일을 입력하세요")
      @Email(message = "이메일 형식이 아닙니다")
      @Schema(defaultValue = "[email protected]")
      private String username; // 이메일
  
      @NotBlank(message = "비밀번호를 입력하세요")
      @Schema(defaultValue = "pw12345")
      private String password; // 비밀번호
  
      @NotBlank(message = "닉네임을 입력하세요")
      @Schema(defaultValue = "nickname123")
      private String nickname; // 닉네임
  
      @NotBlank(message = "생년월일을 입력하세요")
      @Schema(defaultValue = "19980114")
      private String birth; // 생년월일 (ex.19980114)
  
      @NotBlank(message = "전화번호를 입력하세요")
      @Schema(defaultValue = "01012345678")
      private String phone; // 전화번호
  }

  {
    "success": false,
    "data": null,
    "errorDetail": {
      "errorCode": "400",
      "errorMessage": "잘못된 요청입니다.",
      "validation": {
        "nickname": "닉네임을 입력하세요",
        "username": "이메일 형식이 아닙니다"
      }
    }
  }

Controller

• 해당 DTO Spring Validation을 적용하기 위해서는 컨트롤러단에 @Valid어노테이션 작성

  public class AuthController implements AuthControllerDocs {
  
      private final MemberService memberService;
  
      @Override
      @PostMapping("/signup")
      public ResponseEntity<ApiResponse<Void>> signUp(@Valid SignUpRequest request) {
          return ResponseEntity.ok(memberService.signUp(request));
      }
  }

---

정규식 (RegEx)

1. 기본 구조

• ^: 문자열 시작을 의미
• $: 문자열 끝을 의미
• .: 임의의 한 문자(any character)를 의미 (개행 제외)
• [...]: 문자 클래스. 대괄호 안에 있는 문자들 중 하나와 매칭
• [^...]: 문자 클래스의 부정. 대괄호 안에 있는 문자를 제외한 모든 문자와 매칭
• |: OR 연산자 (또는)
• (): 그룹(Group)을 형성하거나 캡처(Capture) 용도로 사용

예를 들어, ^[A-Za-z]+$ 라는 정규식은 문자열 처음(^)부터 끝($)까지 알파벳 대소문자(AZ, az)만(+) 존재해야 매칭됩니다.

2. 반복(Quantifier)

• : 0번 이상 반복
• +: 1번 이상 반복
• ?: 0번 또는 1번 (있어도 되고 없어도 됨)
• {m,n}: 최소 m번, 최대 n번 반복
• {m}: 정확히 m번 반복

예:

• [0-9]+ : 숫자(0~9)가 1개 이상
• [A-Za-z]{2,6} : 알파벳 대소문자가 2~6자

3. 자주 쓰는 예시

3.1 이메일 패턴 예시

^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}$

• ^[A-Za-z0-9._%+-]+: 이메일 “@” 앞부분(아이디)에서, 알파벳/숫자/특정 특수 문자(._%+-)를 한글자 이상 허용
• @: “@” 문자
• [A-Za-z0-9.-]+: “@” 뒤 도메인 이름에 알파벳/숫자/./ 등이 한글자 이상
• \.[A-Za-z]{2,6}$: 최종적으로 “.”을 찍고, 알파벳이 2~6자리로 끝나야 함(예: .com, .co.kr, .net 등)

이메일 정규식은 RFC 표준을 완전히 만족시키려면 훨씬 복잡해질 수 있습니다.

일반적인 상황에서는 위 정도의 패턴을 자주 사용합니다.

3.2 휴대폰 번호(국내) 예시

^01[0-9]{1}-?[0-9]{3,4}-?[0-9]{4}$

• ^ : 문자열 시작
• 01[0-9]{1} : “01”로 시작하고, 뒤에 숫자 1자리 (ex. 010, 011, 019 등)
• ? : “-”가 있을 수도 있고, 없을 수도 있음
• [0-9]{3,4} : 그 다음 숫자 3자리 또는 4자리
• ? : 다시 “-”가 있을 수도, 없을 수도 있음
• [0-9]{4}$ : 마지막 숫자 4자리로 끝
• $ : 문자열 끝

예)

• 010-1234-5678 : OK
• 01012345678 : OK
• 019-345-6789 : OK
• 0212345678 : NO (02는 일반 유선 전화 국번)

3.3 생년월일(YYYYMMDD) 예시

^(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$

• ^(19|20) : 1900대 또는 2000대
• \d{2} : 연도 마지막 두 자리(예: 19xx, 20xx)
• (0[1-9]|1[0-2]) : 월(MM) → 0109 또는 1012
• (0[1-9]|[12]\d|3[01]) : 일(DD) → 0109, 1029, 30~31
• $ : 끝

예)

• 19980114 : OK (1998년 1월 14일)
• 20200229 : OK (2020년 2월 29일, 윤년)
• 20201301 : NO (13월은 없음)

---

4. @Pattern 애노테이션 적용 예시

@Pattern(
    regexp = "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,6}$",
    message = "이메일 형식이 아닙니다"
)
private String email;

• 엔터프라이즈 환경에서 Java Bean Validation과 함께 사용 시,
  • 해당 필드가 정규식에 맞지 않으면 MethodArgumentNotValidException이 발생.
  • 전역 예외 처리(GlobalExceptionHandler)에서 JSON 응답으로 에러 정보를 내려줄 수 있음.

---

5. 공백, null, 빈 문자열 처리

• *@Pattern*은 순수하게 문자열이 정규식에 부합되는지 **‘형식’**만 검사합니다.

• 만약 공백, null, 빈 문자열을 허용하고 싶지 않다면, 반드시 @NotBlank(또는 @NotNull)와 함께 사용하세요.

  @NotBlank(message = "이메일은 필수 입력값입니다")
  @Pattern(regexp = "...", message = "이메일 형식이 아닙니다")
  private String email;

• 이렇게 하면 아예 입력이 없거나(null) 공백문자만 있는 경우에는 @NotBlank가 우선적으로 에러를 내고,입력은 했지만 패턴이 다른 경우에는 @Pattern이 에러를 냅니다.

---

6. 테스트 & 학습 리소스

• 온라인 테스트 툴:
  • [Regex101](https://regex101.com/)
  • [Regexr](https://regexr.com/)
  • 정규식 입력하고, 예시 문자열을 넣으면 어느 부분이 매칭되는지 시각적으로 볼 수 있어 편리합니다.
• 주요 정규 표현식 문법:
  • [공식 문서(Oracle, 자바)](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)
  • java.util.regex.Pattern 클래스 설명서에서 다양한 스니펫과 문법을 참고할 수 있습니다.

---

결론

1. *^...$*로 문자열 전체를 검증하고자 할 때는 반드시 양 끝에 앵커(^, $)를 붙여야 합니다.
2. 반복, 문자 클래스, 그룹 등을 적절히 조합해 원하는 형식을 정확히 필터링할 수 있습니다.
3. Bean Validation의 @Pattern(regexp="...")로 DTO의 해당 필드가 특정 정규식에 부합하는지를 검사할 수 있습니다.
4. 공백/빈 문자열/널도 막고 싶으면 @NotBlank나 @NotNull 등과 함께 써야 합니다.

📚 트러블슈팅 및 기대효과

No response

🔗 관련 자료

No response

🙋‍ 담당자

• 백엔드: @nayoung04 @Chuseok22 @HyerimH
• 프로트엔드: 이름
• 디자인: 이름