이 글은 유저 식별자를 컨트롤러에 주입하는 방식을 헤더 직접 파싱 → SecurityContext 컨트롤러마다 직접 접근 → @CurrentUserId + HandlerMethodArgumentResolver 순서로 개선해 온 과정을 정리하고, 최종 설계와 적용 효과를 제시한다. 불필요한 중복과 보안/예외 처리 불일치를 제거하고, 컨트롤러 시그니처를 단순화하는 것이 목표이다.

---

✍️ 1. 왜 바꿨나

• 중복 로직이 누적된다: 컨트롤러/서비스마다 토큰 파싱과 예외 분기가 반복된다.
• 정책 불일치가 생긴다: 401/403, 만료/위조 구분, 로그 포맷이 제각각이 된다.
• 가독성/테스트 비용이 증가한다: 핵심 로직이 인증 보조 로직에 묻힘.
• 문서화 혼선이 발생한다: 어떤건 Swagger에 userId가 노출되어 있고, 어던 건 토큰에서 추출하도록 구현되어 있음.

목표는 단순하다. 유저 ID는 자동으로, 안전하게, 일관되게 주입하고, 컨트롤러는 비즈니스에만 집중하게 만든다.

---

🔁 2. 단계별 변화

A) 헤더에서 직접 추출

• 방식: Authorization: Bearer ...에서 토큰을 추출·검증해 userId를 얻는다.
• 한계: 모든 엔드포인트에 유사 코드가 흩어지고, 매번 헤더 파싱 코드가 필요하다. 예외·로그 표준화가 어렵다.

B) SecurityContext에서 직접 꺼냄

• 방식: JWT 필터에서 검증 후 Authentication을 세팅하고, 컨트롤러/서비스에서 SecurityContextHolder로 userId를 읽는다. 공용 유틸 SecurityContextProvider로 감싼다.
• 효과: 각 API 메서드마다 있던 헤더 파싱 코드가 사라지고 인증 실패 처리가 한 곳으로 모인다.
• 한계: 메서드마다 유틸 호출이 반복되고, 시그니처만 보고 인증 의존성을 파악하기 어렵다.

C) @CurrentUserId + 리졸버 (최종 설계)

• 방식: 파라미터에 @CurrentUserId Long userId만 선언하면 리졸버가 SecurityContext에서 안전하게 주입한다.
• 효과: 메서드 시그니처가 “로그인 필요”를 명시적으로 표현하고, 인증 파생 로직이 완전히 분리된다.

---

🧩 3. 최종 설계

아래는 최종 설계의 핵심 코드와 함께, 각 파일(클래스/설정/컨트롤러)에 대해 “무엇을/왜/어떻게/확장 포인트/주의점”을 구체적으로 설명하였다.

---

3.1 ✨ 애노테이션: @CurrentUserId

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface CurrentUserId {}

무엇을 하나

• 컨트롤러 메서드 파라미터 수준에서 “여기에는 인증된 사용자의 ID가 주입되어야 한다”는 의도를 선언한다.

왜 이렇게 하나

• ElementType.PARAMETER로 타깃을 제한해 잘못된 사용을 줄인다. (필드/메서드에 붙는 실수를 봉쇄해버림)
• RetentionPolicy.RUNTIME으로 리플렉션 시점에 리졸버가 애노테이션을 감지할 수 있게 한다. -> 런타임 시점까지 끌고감
• 자체 속성이 없는 marker annotation으로 단순/명확하게 의도를 표현한다.

동작 방식 요약

• 스프링 MVC는 파라미터를 해석할 때 등록된 HandlerMethodArgumentResolver에게 “이 파라미터를 네가 처리할 수 있나?”를 질의한다.
• supportsParameter()가 true를 반환하면 resolveArgument()가 호출되어 userId를 채워 넣는다.

주의점

• 애노테이션 자체에는 아무 정책도 담지 않는다. 정책은 리졸버가 책임진다.

---

3.2 🧠 리졸버: CurrentUserIdArgumentResolver

@Component
public class CurrentUserIdArgumentResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter p) {
        return p.getParameterAnnotation(CurrentUserId.class) != null
            && p.getParameterType().equals(Long.class);
    }
    @Override
    public Object resolveArgument(MethodParameter p, ModelAndViewContainer m,
                                  NativeWebRequest w, WebDataBinderFactory b) {
        try {
            return SecurityContextProvider.getAuthenticatedUserId();
        } catch (Exception e) {
            throw new CommonException(CommonErrorStatus.UNAUTHORIZED);
        }
    }
}

무엇을 하나

• @CurrentUserId가 붙은 Long 타입 파라미터를 감지하고, SecurityContext에서 검증된 userId를 추출해 주입한다.
• 인증 실패/부재 시 일관된 401 응답을 보장한다.

왜 이렇게 하나

• 타입을 Long으로 엄격히 고정해 API 표면을 명확히 유지한다. (컨트롤러 시그니처만 봐도 무엇이 들어오는지 분명해진다)

동작 순서

1) 스프링 MVC가 파라미터 해석 중 supportsParameter()를 호출한다.
2) 조건을 만족하면 resolveArgument()가 호출된다.
3) SecurityContextProvider.getAuthenticatedUserId()가 내부에서 Authentication의 principal(예: CustomUserDetails)에서 userId를 읽어온다.
4) 예외 발생 시 401로 통일한다.

확장 포인트

• 선택 인증 API를 위해 Optional<Long> 또는 @Nullable Long을 허용하는 두 번째 리졸버를 추가할 수 있다. 이 경우 실패를 401로 던지지 않고 null을 주입한다. -> 익명 유저 처리 같은 경우 사용할 수도 잇음.

보안/성능 고려

• SecurityContext 접근은 스레드 바운드이므로, 비동기 호출 시 컨텍스트 전파 설정을 사용해야 한다.
• 리졸버 자체는 가볍고, 요청당 1회 정도 호출되므로 병목이 되지 않는다.

주의점

• 파라미터 타입이 Long이 아니면 리졸버가 동작하지 않는다.
• 컨트롤러에서 임의로 userId를 입력받는 파라미터를 추가로 받지 않는다. -> 자동으로 해줌.

---

3.3 ⚙️ WebMvc 설정: WebMvcConfig

@Configuration
@RequiredArgsConstructor
public class WebMvcConfig implements WebMvcConfigurer {
    private final CurrentUserIdArgumentResolver currentUserIdArgumentResolver;
   
    @Override public void addArgumentResolvers(
    	List<HandlerMethodArgumentResolver> rs
	) { 
    	rs.add(currentUserIdArgumentResolver); 
    }
}

무엇을 하나

• CurrentUserIdArgumentResolver를 MVC에 등록해 주입이 가능하도록 한다.

왜 이렇게 하나

• 리졸버는 MVC 생명주기에 등록되어야 동작한다.

동작

• addArgumentResolvers에서 리졸버를 추가하면 스프링이 매 요청마다 파라미터를 해당 리졸버에 질의한다.

---

3.4 🧾 컨트롤러 예: 업로드 API

@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<SuccessResponse<Void>> uploadData(
        @Parameter(hidden = true)
        @CurrentUserId Long userId,
        
        @RequestPart("dataFile")
        MultipartFile dataFile,
        
        @RequestPart(value = "thumbnailFile", required = false)
        MultipartFile thumbnailFile,
        
        @RequestPart @Validated
        UploadDataWebRequest webRequest
) { /* ... */ }

무엇을 하나

• 인증 파생 데이터(userId)는 자동 주입하고, 컨트롤러는 비즈니스 입력만 받는다.
• 멀티파트 본문에서 파일(dataFile, thumbnailFile)과 JSON DTO(webRequest)를 함께 받는다.

왜 이렇게 하나

• “컨트롤러 시그니처 = API 스펙” 원칙을 지킨다.
  @CurrentUserId로 로그인 필요성이 시그니처에 드러나고, userId를 클라이언트가 임의 제공하지 못하도록 막는다.

문서화(OpenAPI)

• Authorization 헤더는 명시하고, userId 파라미터는 @Parameter(hidden = true)로 숨긴다.
  문서 소비자는 토큰만 준비하면 되고, 주입 파라미터는 노출되지 않는다.

주의점

• 컨트롤러에서 userId로 조회한 리소스 접근 시 인가(소유권/권한)를 서비스 레벨에서 재검증한다.

---

📌 요약: 클래스별 책임 한 줄 정리

• @CurrentUserId: “여기엔 인증된 사용자 ID가 들어온다”는 의도 선언을 담당한다.
• 리졸버: 선언된 의도를 실제 값으로 주입하고, 실패를 401 표준화한다.
• WebMvcConfig: 리졸버를 스프링 생태계에 연결한다.
• 컨트롤러: 비즈니스 파라미터만 받아 핵심 로직에 집중한다.

---

🧭 4. 동작 흐름

[Client] --Bearer 토큰-->
  [JWT 필터] --검증 OK-->
    [SecurityContext(Authentication)]
      └─> [ArgumentResolver] --@CurrentUserId 주입-->
           [Controller(Long userId)] → [Service] (비즈니스 로직만)

---

🚀 5. 적용 효과

• 컨트롤러 단순화: 인증 파생 로직 제거 → 시그니처가 비즈니스 중심으로 정리된다.
• 일관된 보안/예외: 인증 실패는 항상 401 UNAUTHORIZED로 통일한다.
• 테스트 비용 절감: SecurityContextProvider.setupSecurityContextForTest(...)로 인증 맥락을 손쉽게 구성한다.
• 문서 품질 향상: Swagger에서 Authorization만 요구, 내부 주입 파라미터는 숨겨 스펙이 간결해진다.
• 확장 용이성: 만약 @CurrentUserRole, @CurrentOrgId 등 리졸버를 추가해도 컨트롤러는 변하지 않는다.
• 실수 여지 축소: 직접 헤더 파싱/Principal 캐스팅 제거로 오남용을 최소화한다.

---

🛠️ 6. 확인하기

1) JWT 필터 점검: 검증 성공 시 Authentication(principal=userId, role)이 정확히 채워지는지 확인한다.
2) 리졸버 도입: @CurrentUserId, 리졸버, WebMvcConfig를 추가한다.
3) 컨트롤러 시그니처 교체: @CurrentUserId Long userId로 바꾸고 내부 인증 접근 코드를 삭제한다.
4) 문서화 정리: Swagger에서 Authorization 헤더는 명시하고, userId는 숨긴다.

---

❓ 7. FAQ

• 익명 허용 API는? -> @CurrentUserId를 쓰지 않고, 필요 시 nullable 주입용 별도 리졸버를 둔다.
• Long 외 타입은?
  -> supportsParameter를 확장하거나 사용자 객체 자체를 주입하는 애노테이션을 추가한다.
  -> 여기선 supportsParameter에 Long 조건을 걸어두었기에 Long 타입만 받는다.
• 비동기에서 컨텍스트 전파는? -> 스프링 Security의 컨텍스트 전파 설정을 사용하거나, 비동기 경계에서 명시적으로 복제·전달해야함.

---

🧪 8. 테스트 팁

SecurityContextProvider.setupSecurityContextForTest(1L, RoleType.USER);
// 테스트 ...
SecurityContextProvider.clearSecurityContext();

• 권한별 시나리오(USER/ADMIN)와 실패 케이스(미인증/만료)를 분리해 검증한다면 위와 같이 사용할 수 있음.
• 컨트롤러 테스트는 주입 동작에 집중하고, JWT 검증 자체는 따로 테스트로 커버한다.

---

🎯 9. 결론

컨트롤러에는 비즈니스 파라미터만 남긴다. 유저 ID는 리졸버가 일관되게 주입한다.
이렇게 하면 코드는 짧아지고, 보안/예외는 통일되며, 테스트와 문서화가 쉬워진다. 🚀