특수 문자 오류 해결하기: Invalid character found in the request target

안녕하세요.

최근 개발 중 java.lang.IllegalArgumentException: Invalid character found in the request target 오류에 직면했습니다.

해당오류는 클라이언트의 요청 URL에 특수 문자가 포함되어 있을 때 발생하는 문제로, RFC 7230 및 RFC 3986 규정에 어긋나는 문자들 때문이라고 합니다.

그래서 이번 글에서는 이 문제의 해결 과정을 공유하고자 합니다.

문제 발생 상황

Error 발생

Spring Boot에서 클라이언트로부터 특정 특수 문자를 포함한 요청을 받았을 때, java.lang.IllegalArgumentException 오류가 발생했습니다. 처음에는 application.yml 설정을 통해 요청 인코딩을 UTF-8로 강제하는 방식으로 해결하려 시도했습니다.

server:
  servlet:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

하지만, 이 방법은 문제를 해결하지 못했습니다. 오류 메시지를 보니 문제의 원인은 URL에 포함된 특수 문자가 웹 서버(Tomcat)의 기본 설정과 충돌하는 것으로 밝혀졌습니다.

해결 방안

문제를 해결하기 위해, Tomcat의 relaxedQueryChars 옵션을 커스터마이징하는 방법을 선택했습니다. 이 옵션을 사용하면 특정 특수 문자를 쿼리 파라미터로 허용할 수 있습니다. 아래는 TomcatServletWebServerFactory를 커스터마이징하여 relaxedQueryChars를 설정하는 Java 구성 클래스의 예시입니다.

@Configuration
public class TomcatWebCustomConfig implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> connector.setProperty("relaxedQueryChars", "<>[\\]^`{|}"));
    }
}

이 설정을 통해, \, <, >, [, ], ^, `, {, |, }와같은 문자들을 URL 쿼리 파라미터에서 안전하게 사용할 수 있게 되었습니다.

마치며

사실 처음엔 별거 아닌 줄 알았는데... 애들이 생각보다 까다롭더라고요.
괜히 에러가 나는 게 아니구나 싶었고, 결국 하나하나 뜯어보면서 URL 쿼리 파라미터랑 인코딩에 대해 꽤 많이 배우게 됐습니다.
“아 이런 것도 신경 써야 하는구나” 싶은 순간들이었고요.
개발하면서 예상 못한 데서 막히는 일이 종종 있는데, 이럴 때마다 좀 더 단단해지는 것 같습니다.