[TroubleShooting] Spring MVC에서 정적 경로가 동적 경로로 인식되어 엔드포인트가 동작하지 않을 때

👀 현재 상황 및 배경 설명

🔽 SecurityConfig API 요청 흐름

API 요청은 공개 접근 필터 체인과 인증이 필요한 필터 체인을 순차적으로 거친다.

1. 공개 접근 필터 체인: 로그인 없이도 접근 가능한 엔드포인트를 처리한다.
2. 인증이 필요한 필터 체인: 로그인이 반드시 요구되는 엔드포인트를 처리한다.

🔽 회원 정보 조회 엔드포인트

현재 프로젝트에서는 회원 정보 조회를 위한 두 가지 API를 제공한다.

• 동적 경로 API: 특정 회원 정보를 조회하는 API로, @PathVariable을 사용하여 memberId 값을 동적으로 전달받는다.
• 정적 경로 API: 자신의 정보를 조회하는 API로, 문자열 "self"를 정적으로 경로에 사용한다.

위 두 경로는 서로 다른 역할을 수행하지만, Spring MVC의 URL 매핑 방식 때문에 경로 충돌이 발생할 가능성이 있다. 정적 경로는 문자열로 고정되어 있는 반면, 동적 경로는 memberId라는 변수로 정의되어 있기 때문에 self가 동적 경로의 일부로 인식되어 충돌이 발생할 수 있다.

 

▶ 구현 코드

🔽 SecurityConfig 클래스

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    // 공개 접근 endpoint
    private RequestMatcher[] publicRequestMatchers() {
        List<RequestMatcher> requestMatchers = List.of(
                antMatcher(GET, "/members/{memberId}"),
                
                ...
        );
        return requestMatchers.toArray(RequestMatcher[]::new);
    }

    // 인증 및 권한이 필요한 endpoint
    private RequestMatcher[] authenticatedRequestMatchers() {
        List<RequestMatcher> requestMatchers = List.of(
                antMatcher(GET, "/members/self"),
                
                ...
        );
        return requestMatchers.toArray(RequestMatcher[]::new);
    }
    
    ...
    
}

🔽 MemberController 클래스

@RestController
@RequestMapping("members")
@RequiredArgsConstructor
public class MemberController {

    private final MemberService memberService;
    
    @GetMapping("/self")
    public ResponseEntity<BfResponse<MemberInfoResponse>> getSelf(
            @AuthenticationPrincipal PrincipalDetails principalDetails
    ) {
        MemberInfoResponse memberInfoResponse = memberService.getMember(Long.parseLong(principalDetails.getUsername()));
        return ResponseEntity.ok(new BfResponse<>(memberInfoResponse));
    }
    
    @GetMapping("/{memberId}")
    public ResponseEntity<BfResponse<MemberInfoResponse>> getMember(
            @PathVariable Long memberId
    ) {
        MemberInfoResponse memberInfoResponse = memberService.getMember(memberId);
        return ResponseEntity.ok(new BfResponse<>(memberInfoResponse));
    }
    
    ...
    
}

 

 

🚨 문제 상황

/members/self 경로가 /members/{memberId} 경로와 충돌하여, 정적 경로로 매핑되지 않고 동적 경로로 잘못 인식되는 문제가 발생했다. 이로 인해, "self"가 memberId 변수로 처리되어 /members/{memberId} 경로의 로직으로 전달되었다. 하지만, 로직 상 memberId는 숫자만 허용되므로, "self" 문자열을 처리할 수 없어 에러가 발생한다.

 

 

✏️ 원인 분석

동적 경로와 정적 경로에 대해 알지 못했던 탓에, 이번 트러블슈팅 과정에서 다소 헤맸다.

▶ 왜 members/self만 에러가 발생했을까?

1. Security 인증 필터에서 members/{memberId}가 공개 필터 체인에서 우선 처리되어, members/self가 동작하지 않는 걸까?
   • self를 공개 접근 체인에서 먼저 선언해도 동일한 에러가 발생했다.
2. self, me, my가 {memberId}로 인식되는 걸까?
   
   • 다른 문자열(current, my-profile 등)을 사용해 테스트했을 때도 동일한 에러가 발생했다. 이를 통해 단순히 특정 문자열의 문제라기보다는, 정적 경로와 동적 경로의 처리 방식에 문제가 있음을 검색하면서 알게 되었다.
3. 동적 경로와 정적 경로가 충돌이 나는 걸까?
   • 단순히 우선순위 충돌 문제는 아니었다. Spring이 /members/self를 정적 경로로 인식하지 않고, 동적 경로 /members/{memberId}의 일부로 해석했기 때문이다. 결과적으로 "self"라는 문자열이 memberId 변수로 전달되어, /members/{memberId} 경로의 메서드로 매핑되면서 문제가 발생했다.

Spring URL 매핑 우선순위
1. 정적 경로: 정확히 일치하는 경로
2. 동적 경로: {}와 같은 변수로 정의된 경로
3. 와일드카드 경로: *(단일 경로) 또는 **(다중 경로)를 포함한 경로

 

 

🔨 해결 방법

▶ 1. 정적 경로와 동적 경로 명확히 구분

/members/self는 정적 경로로, /members/id/{memberId}는 동적 경로로 정의하여 경로를 명확히 분리한다.

🔽 구현 코드

@RestController
@RequestMapping("members")
@RequiredArgsConstructor
public class MemberController {

    private final MemberService memberService;
    
    @GetMapping("/self")
    public ResponseEntity<BfResponse<MemberInfoResponse>> getSelf( ... ) { ... }
    
    @GetMapping("/id/{memberId}") // 동적 경로 명확히 구분
    public ResponseEntity<BfResponse<MemberInfoResponse>> getMember( ... ) { ... }
    
    ...
    
}

 

▶ 2. 컨트롤러에서 정규 표현식으로 동적 경로 제한

Spring 공식 문서에서 권장하는 방식으로, 컨트롤러에서 동적 경로의 값을 정규 표현식으로 제한하여 예상치 못한 문자열 매칭을 방지할 수 있다. 이를 통해 동적 경로와 정적 경로 간 충돌 문제를 해결할 수 있다.

🔽 구현 코드

@RestController
@RequestMapping("members")
@RequiredArgsConstructor
public class MemberController {

    private final MemberService memberService;
    
    @GetMapping("/self")
    public ResponseEntity<BfResponse<MemberInfoResponse>> getSelf( ... ) { ... }
    
    @GetMapping("/members/{memberId:[0-9]+}") // 동적 경로를 정규 표현식으로 제한
    public ResponseEntity<BfResponse<MemberInfoResponse>> getMember( ... ) { ... }
    
    ...
    
}

🔽 문제점

현재 로직에서는 API를 개발할 때 Spring Security를 통해 모든 엔드포인트를 등록해야 하므로, 이 방법만으로는 문제를 해결할 수 없었다.

 

▶ 3. Spring Security에서 정규 표현식 동적 경로 명시적 등록

Spring 공식 문서에서 명시적 등록(Explicit Registrations)이라는 개념을 알게 되었다. 이를 보며 SecurityConfig에서도 정규 표현식을 활용하여 문제를 해결할 수 있겠다는 생각이 들었다. 이후 Spring Security 설정에서 동적 경로에 허용되는 값을 정규 표현식으로 제한하는 방법을 적용하여 문제를 해결할 수 있었다.

🔽 구현 코드

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    // 공개 접근 endpoint
    private RequestMatcher[] publicRequestMatchers() {
        List<RequestMatcher> requestMatchers = List.of(
                antMatcher(GET, "/members/{memberId:\\d+}"), // 동적 경로를 정규 표현식으로 제한
                
                ...
        );
        return requestMatchers.toArray(RequestMatcher[]::new);
    }

    // 인증 및 권한이 필요한 endpoint
    private RequestMatcher[] authenticatedRequestMatchers() {
        List<RequestMatcher> requestMatchers = List.of(
                antMatcher(GET, "/members/self"),
                
                ...
        );
        return requestMatchers.toArray(RequestMatcher[]::new);
    }
    
    ...
    
}

 

 

🔍 결과 관찰

• /members/self 경로가 동적으로 매칭되지 않고 정적으로 매칭되었다.
• /members/{memberId} 경로는 여전히 동적으로 동작하며, 경로 간 충돌이 발생하지 않았다.

 

 

💡 고찰

• 이번 트러블슈팅을 통해 Spring MVC의 동적 경로와 정적 경로 매핑에 대한 개념을 배웠다. 이전에는 해당 개념을 알지 못하고 API를 개발했었기 때문에, 이 경험을 통해 의미 있는 지식을 습득하게 된 것 같아 매우 기뻤다.
• 하지만 이후 모임 관련 API에서 /meetings/{meetingId}와 /meetings/{organizationId}처럼 비슷한 형식의 동적 경로가 필요할 때 경로 간 충돌 문제가 발생했다. 이번 사례는 /members/self처럼 문자열로 처리할 수 있는 엔드포인트였기 때문에, /members/{memberId}에서 memberId를 숫자로 제한하는 방식으로 해결할 수 있었다. 그러나 /meetings/{meetingId}와 /meetings/{organizationId}는 구조적으로 경로가 비슷해 이 방식이 적용되지 않았다.
• 결국, 해결 방법 1번을 적용하여 /meetings/organization/{organizationId}로 변경해 문제를 해결했다. 이 경험을 통해 RESTful API 설계 원칙에 대해 더 깊은 공부와 이해가 필요하다는 점을 느꼈다.

 

 

📍 참고 자료

• Spring 공식 문서: Mapping Requests - URI patterns
• Spring 공식 문서: Mapping Requests - Explicit Registrations
• 231012(목)_promise, API 라우팅 이슈
• Path Matching