[Spring] AntPathMatcher 정리 – URL 패턴 매칭 방식과 사용 시점 (2026 업데이트)

이 글은 2017년에 작성했던 AntPathMatcher 예제를
최신 Spring 기준으로 정리한 리뉴얼 글이다.

---

1. AntPathMatcher란 무엇인가

AntPathMatcher는
Spring Framework에서 제공하는 경로(Path) 패턴 매칭 유틸리티 클래스이다.

주로 다음과 같은 상황에서 사용된다.

• URL 패턴과 실제 요청 경로가 매칭되는지 확인할 때
• Spring MVC, Spring Security 내부에서 경로 비교가 필요할 때
• ant-style path pattern 문법을 사용할 때

 

Spring에서는
org.springframework.util.AntPathMatcher 클래스를 통해 이를 제공한다.

---

2. Ant 스타일 경로 패턴(Ant-style Path Pattern)

AntPathMatcher는 Ant 스타일 경로 패턴을 기반으로 동작한다.

자주 사용하는 패턴 문법은 다음과 같다.

 

패턴	의미
?	한 글자와 매칭
*	0개 이상의 문자와 매칭
**	0개 이상의 디렉토리 레벨과 매칭

예시

패턴	매칭 예
/api/?/users	/api/v/users
/api/*/users	/api/v1/users
/api/**	/api/v1/users/1

---

3. AntPathMatcher 기본 사용 예제

다음은 가장 단순한 사용 예제이다.

import org.springframework.util.AntPathMatcher;

public class AntPathMatcherExample {

    public static void main(String[] args) {
        AntPathMatcher matcher = new AntPathMatcher();

        String pattern = "/a/**";
        String path = "/a/b/c/d/e.xml";

        boolean match = matcher.match(pattern, path);
        System.out.println(match); // true
    }
}

• pattern에 정의한 경로 규칙과
• 실제 path가 일치하면 true를 반환한다.

---

4. 실무에서 자주 헷갈리는 포인트

* 와 ** 의 차이

/a/*   → /a/b (O)
       → /a/b/c (X)

/a/**  → /a/b (O)
       → /a/b/c (O)

• * 는 한 단계
• ** 는 여러 단계(재귀적 디렉토리)

Spring Security 설정에서 가장 많이 실수하는 부분이기도 하다.

---

5. Spring Security에서의 AntPathMatcher

Spring Security에서 경로 권한 설정 시
다음과 같은 형태를 본 적이 있을 것이다.

http
    .authorizeHttpRequests()
    .requestMatchers("/api/**").authenticated()
    .requestMatchers("/admin/**").hasRole("ADMIN");

 

이때 내부적으로 사용되는 패턴 매칭 방식이
AntPathMatcher 기반이다. (Spring 5.x 기준)

---

6. ⚠️ 중요: Spring 5.3 이후 변화

여기서 반드시 짚고 가야 할 부분이 있다.

AntPathMatcher는 현재 권장 방식이 아니다

Spring 5.3 이후부터는
다음 클래스 사용이 권장된다.

 

PathPatternParser

 

차이점 요약

항목	AntPathMatcher	PathPatternParser
패턴 문법	Ant 스타일	전용 Path 패턴
성능	상대적으로 느림	빠름
객체 생성	런타임 파싱	사전 컴파일
권장 여부	❌ 레거시	✅ 권장

 

Spring 공식 문서에서도
신규 프로젝트에서는 PathPatternParser 사용을 권장하고 있다.

---

7. 그럼 AntPathMatcher는 언제 써야 할까?

다음과 같은 경우에는 여전히 사용된다.

• 기존 레거시 Spring 프로젝트 유지보수
• Ant 스타일 패턴에 의존하는 코드 수정
• 간단한 유틸성 경로 비교 로직

 

반대로,

• 신규 Spring Boot 프로젝트
• 성능이 중요한 라우팅 처리
• WebFlux / 최신 MVC 환경

에서는 PathPatternParser를 사용하는 것이 적절하다.

---

8. 면접에서 나올 수 있는 질문

Q. AntPathMatcher와 PathPatternParser의 차이는?

AntPathMatcher는 문자열 기반 패턴 매칭 방식이고,
PathPatternParser는 패턴을 사전에 파싱하여
성능과 안정성을 개선한 방식이다.

---

Q. * 와 ** 의 차이는?

*는 한 디렉토리 레벨,
**는 여러 디렉토리 레벨을 포함하여 매칭한다.

---

9. 정리

• AntPathMatcher는 Ant 스타일 경로 패턴 매칭 유틸리티이다.
• 오래된 방식이지만 여전히 레거시 환경에서는 사용된다.
• Spring 5.3 이후 신규 개발에서는 PathPatternParser 사용이 권장된다.
• 기존 코드를 이해하거나 유지보수하는 관점에서는 반드시 알고 있어야 할 개념이다.

---

10. 마무리

현재 Spring 기준에 맞게 보완한 리뉴얼 정리이다.

레거시 코드 분석이나
Spring 내부 동작을 이해하는 데 참고 자료로 활용하면 충분하다.

 

2017.12.04 - [IT/Backend] - [Spring] 스프링 AntPathMatcher 사용 예제

[Spring] 스프링 AntPathMatcher 사용 예제