문제 개요
프로젝트에서 Global Exception Handler를 도입해서 예외 처리를 구성해서 공통적인 에러처리를 @RestControllerAdvice를 통해 구성했다. 또한 api 문서를 자동화할 수 있게끔 Swagger를 도입했었다.
글로벌 익셉션 핸들러를 도입한 이후 테스트를 해보니 잘 돌아가던 Swagger가 먹통이 되버렸다.
해결
엥? 잘 돌아가고 있었는데..
문제를 해결한 결론부터 말하자면, 이 이슈는 Swagger와 Spring Boot 버전 간의 충돌문제였다.
build.gradle에서 swagger 사용을 위한 springdoc-openapi-starter-common 2.5에서 2.7 버전으로 올려주니 무사히 잘 되었다.
그럼 이전에는 됐는데, 글로벌 익셉션을 구현하니까 왜 안됨?
우리 프로젝트는 Spring Framework 6.2.6 을 사용하고 있는데, springdoc-openapi-starter-common 2.5.0 버전 사용 중이라 문제가 발생했다. Spring 프레임워크 6.2 버전 이상부터 내부 API가 변경되어서 ControllerAdviceBean 생성자 시그니처가 바뀌었는데 2.5.0 버전에서는 예전 버전 API를 참조해서 NoSuchMethodError 가 발생했었다.
🤔아니 근데 왜 됐다가 안 되냐고!!!
@RestControllerAdvice 때문 !
핵심 이유 : springdoc-openapi 가 @RestControllerAdvice로 인해 ControllerAdviceBean 을 직접 탐색했기 때문
- springdoc-openapi는 @RestControllerAdvice가 있는 bean 들만 탐색해서 문서화에 포함할지 말지 판단함.
- 이전에 코드에서는 @RestControllerAdvice를 추가하지 않았기에 이 부분 코드를 타지 않기 때문에 getBeanType()도 호출되지 않음.
- 글로벌 예외 처리하면서 @RestControllerAdvice 추가하면서 springdoc-openapi가 이 클래스를 문서화 대상으로 판단해 탐색하게 된 것임.
- 내부적으로 getBeanType() 호출 ➡️ 응 없어~ NoSuchMethodError
정리
@RestControllerAdvice가 없음 → springdoc-openapi는 탐색 안 함 → 정상 작동
@RestControllerAdvice 등록 → springdoc-openapi가 이 클래스의 타입을 확인하려 함 → 메서드 없음 → 에러 발생
NoSuchMethodError
핵심 에러 로그 메시지
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'
NoSuchMethodError는 컴파일은 성공했지만, 런타임에 해당 클래스에서 메서드를 찾지 못할 때 발생하는 링커 에러(linkage error)라고 한다. (이런 에러는 라이브러리 간 버전 호환성 문제에서 자주 나타나고 메서드가 이름, 리턴 타입, 파라미터 시그니처 중 하나라도 바뀌면 발생)
ControllerAdviceBean은 스프링 내부에 클래스인데 springdoc-openapi는 ControllerAdviceBean에 존재하던 getBeanType() 같은 메서드를 리플렉션 혹은 직접 참조하여 사용했는데, Spring Framework 6.2.x에서 해당 메서드가 변경되거나 제거되면, NoSuchMethodError가 발생한다.
회고
문제가 발생했을 때 GPT에 에러코드 바로 던져서 확인했는데 버전 충돌로 인해 안되는 거라고 이야기했었다. GPT가 그냥 던져준 에러만 보고 잘못된 정보를 알려주는 줄 알았다. 왜냐면 일단 GPT가 던져준 버전으로 했는데도 안됐고, 이전에 SWAGGER를 잘 쓰고 있었으니, 버전 충돌이 났었을 거면 일찍이 났었을 거라 판단했다. 그래서 "글로벌 익셉션 코드의 문제다"라 판단했고, 계속해서 다른 문제가 아닌지 찾아보는 삽질을 했던 것 같다.
"전에는 잘 되었으니 버전 문제일 리가 없다" 라는 고정관념을 깨는 유익한 시간이었다.