[Spring Boot 3] @Pattern 정규표현식 검증 완벽 가이드 – 실전 예제로 배우는 유효성 검증

 

Spring Boot 3에서 사용자 입력값에 대한 유효성 검증은 필수적인 기능입니다. 특히 이메일, 비밀번호, 전화번호처럼 정해진 형식을 따라야 하는 입력값의 경우, 정규표현식(Regex) 을 활용한 검증이 필요합니다.
이때 가장 유용하게 사용되는 어노테이션이 바로 @Pattern입니다. 이 포스팅에서는 @Pattern 어노테이션의 기본 개념부터 실무에서 자주 사용하는 정규표현식 예제까지, Spring Boot 3 기준으로 자세히 소개합니다.

---

🔍 @Pattern 어노테이션이란?

@Pattern은 Java Bean Validation의 일부로, 입력된 문자열이 지정한 정규표현식에 부합하는지 검증합니다. 사용자의 입력이 형식에 맞지 않으면 예외를 발생시켜 잘못된 요청을 차단할 수 있습니다.

기본 사용 예시

@Pattern(regexp = "^[0-9]+$", message = "숫자만 입력할 수 있습니다.")
private String onlyNumber;

위 예제는 입력값이 오직 숫자로만 구성되어야 함을 의미하며, 조건에 맞지 않으면 "숫자만 입력할 수 있습니다." 라는 메시지가 반환됩니다.

---

📦 Spring Boot 3에서는 jakarta.validation 사용

Spring Boot 3부터는 기존의 javax.validation 패키지 대신, jakarta.validation 패키지가 사용됩니다.

따라서 기존에 다음과 같이 작성했다면:

import javax.validation.constraints.Pattern;

이제는 이렇게 변경해야 합니다:

import jakarta.validation.constraints.Pattern;

이 부분은 Spring Boot 3에서 유효성 검사를 설정할 때 반드시 확인해야 할 포인트입니다.

---

🧪 실전 예제로 보는 다양한 정규표현식 패턴

아래는 자주 사용되는 정규표현식 예제들을 @Pattern과 함께 적용한 코드입니다. 이 코드는 사용자의 요청 값이 패턴에 맞는지를 검증하는 컨트롤러 예시입니다.

@RestController
public class ValidAnnotationController {

    @PostMapping("/valid/pattern")
    public PatternValidObject checkPattern(@Valid @RequestBody PatternValidObject object) {
        return object;
    }

    @Getter
    @AllArgsConstructor
    public static class PatternValidObject {

        @Pattern(regexp = "^[0-9]$", message = "숫자만 입력할 수 있습니다.")
        private String onlyNumber;

        @Pattern(regexp = "^[a-zA-Z]*$", message = "영어 알파벳만 입력할 수 있습니다.")
        private String onlyEnglish;

        @Pattern(regexp = "^[a-zA-Z0-9]*$", message = "영어 알파벳과 숫자만 입력할 수 있습니다.")
        private String engAndNum;

        @Pattern(regexp = "^[가-힣]*$", message = "한글만 입력할 수 있습니다.")
        private String onlyKorean;

        @Pattern(regexp = "^[\\w!#$%&'*+/=?`{|}~^.-]+@[\\w.-]+\\.[a-zA-Z]{2,6}$", message = "이메일 형식이 올바르지 않습니다.")
        private String email;

        @Pattern(regexp = "^\\d{2,3}-\\d{3,4}-\\d{4}$", message = "전화번호 형식이 올바르지 않습니다.")
        private String phoneNumber;

        @Pattern(regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&#])[A-Za-z\\d@$!%*?&#]{8,}$", message = "비밀번호 형식이 올바르지 않습니다. 8자 이상, 대소문자 포함, 숫자 및 특수문자(@$!%*?&#) 포함")
        private String password;

        @Pattern(regexp = "^A.*", message = "'A'로 시작해야 합니다.")
        private String startsWithA;

        @Pattern(regexp = ".*A$", message = "'A'로 끝나야 합니다.")
        private String endsWithA;

        @Pattern(regexp = ".*ABC.*", message = "'ABC' 문자열을 포함해야 합니다.")
        private String containsABC;

        @Pattern(regexp = "^(?!.*ABC).*$", message = "'ABC' 문자열을 포함하면 안됩니다.")
        private String exceptABC;

        @Pattern(regexp = "^A.*A$", message = "'A'로 시작하고 'A'로 끝나야 합니다.")
        private String startAEndA;

        @Pattern(regexp = "^(?=.*ABC)(?!.*DEF).*$", message = "'ABC' 문자열을 포함하고 'DEF' 문자열을 포함하면 안됩니다.")
        private String containsABCExceptDEF;
    }
}

---

❗️ 사용 시 주의사항

1. 문자열(String) 타입에만 적용 가능

@Pattern 어노테이션은 문자열(String) 에만 사용할 수 있습니다. 만약 Integer, Long 등의 숫자형 타입에 적용하면 다음과 같은 오류가 발생합니다:

HV000030: No validator could be found for constraint 'jakarta.validation.constraints.Pattern' validating type 'java.lang.Integer'.

2. null 검증은 따로 해야 함

@Pattern은 입력 값이 null인 경우에는 검증을 수행하지 않습니다. 만약 null 값도 허용하지 않으려면, 다음과 같이 조합해서 사용해야 합니다:

@NotBlank
@Pattern(regexp = "^[a-zA-Z0-9]*$", message = "영어 알파벳과 숫자만 입력할 수 있습니다.")
private String username;

주요 Null 검증 어노테이션

• @NotNull: 값이 반드시 존재해야 함
• @NotEmpty: 빈 문자열("") 불가
• @NotBlank: 공백만 있는 문자열(" ") 불가

---

✅ 정규표현식 검증 예시 결과

입력값 정규식 조건 결과

abc123	영어+숫자	✅
1234	숫자만	✅
홍길동	한글만	✅
abc@naver.com	이메일 형식	✅
010-1234-5678	전화번호	✅
Password1!	비밀번호	✅
Astart	A로 시작	✅
endA	A로 끝남	✅
ABCD	ABC 포함	✅
DEF	ABC 제외 조건 위반	❌

---

🧠 정규표현식 요약 및 팁

검증 조건 정규식 설명

숫자만	^[0-9]*$	모든 자리가 숫자
영어만	^[a-zA-Z]*$	알파벳 대소문자만 허용
이메일	^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,6}$	일반적인 이메일 형식
비밀번호	^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&#]).{8,}$	보안 강한 패턴
특정 문자 포함	.*ABC.*	ABC를 포함해야 함
특정 문자 제외	^(?!.*ABC).*$	ABC가 없어야 함
시작 문자	^A.*	A로 시작해야 함
끝 문자	.*A$	A로 끝나야 함

---

📝 마무리 및 총평

Spring Boot 3에서 @Pattern 어노테이션을 활용하면 사용자의 입력값을 손쉽게 검증할 수 있으며, 복잡한 조건도 정규표현식을 통해 간단히 처리할 수 있습니다.
실무에서 자주 사용되는 이메일, 전화번호, 비밀번호와 같은 패턴들을 정리해 두면 재사용성이 높아지고, 유지보수 시에도 유리합니다.

Tip! 유효성 검증을 클라이언트와 백엔드 양쪽 모두에 구현하면, UX와 보안 모두를 향상시킬 수 있습니다.

---

📎 관련 태그

#SpringBoot3 #패턴검증 #정규표현식 #Pattern #SpringValidation #유효성검사 #자카르타 #SpringBootValidation