[Spring] SpringBoot3에 추가된 Content-Disposition 헤더의 일반 filename 파라미터(Regular Parameters)

 

 

 

 

1. SpringBoot3에 추가된 Content-Disposition 헤더의
일반 filename 파라미터(Regular Parameters)

---

[ Content-Disposition 헤더와 ContentDisposition 클래스 ]

RFC-6266에 정의된 Content-Disposition 헤더는 서버가 클라이언트에게 전송되는 리소스(파일 등)의 처리 방법을 지정하는 데 사용되는 헤더이다. 주로 다운로드되는 파일의 이름 등을 지정하는 데 사용된다.

만약 서버가 다음과 같이 Content-Disposition 헤더를 전달하였다면, 브라우저는 example.txt라는 이름으로 파일을 다운로드하도록 요청을 처리한다.

Content-Disposition: attachment; filename="example.txt"

 

 

스프링 역시 HTTP 스펙에 맞게 Content-Disposition HTTP 헤더를 표현하기 위한

ContentDisposition 클래스를 제공하고 있다. 이를 통해 유연하게 Content-Disposition 헤더를 구성할 수 있다.

 

 

 

[ SpringBoot3에서 ContentDisposition 클래스 변경 사항 ]

SpringBoot2가 오픈 소스 지원(OSS, Open Source Support)이 종료되면서 SpringBoot3로 마이그레이션을 빠르게 해야 할 필요가 있다.

 

 

ContentDisposition 클래스 역시 버전업에 따른 변화가 생겼다. 그것은 바로 Content-Disposition 헤더로 기존에 반환되던 확장된 filename* 파라미터와 함께 일반 filename 파라미터가 함께 반환되는 것이다.

참고로 여기서 확장된 파라미터(Extended Parameter)란 좌측 변수가 * 문자로 끝나는 매개변수로, 필수(REQUIRED) 속성인 Charset과 선택(OPTIONAL) 속성인 언어 정보 그리고 실제 값으로 이루어진 파라미터이다. 여기서 *로 끝나지 않는 매개변수는 일반 파라미터(Regular Parameter)라고 한다. 해당 스펙은 RFC-5987에 정의되어 있다.

예를 들어 파일 이름이 中文.txt 이라고 하자. 스프링 부트2에서는 ContentDisposition 클래스를 사용하여 Content-Disposition 헤더를 생성하는 경우에 확장된 filename 파라미터로 파일 이름을 URL-Encoding하여 전달하였다. 따라서 Content-Disposition 헤더가 다음과 같이 반환되었다.

Content-Disposition: form-data; name="name"; filename*=UTF-8''%E4%B8%AD%E6%96%87.txt

 

 

하지만 스프링 부트3에서는 확장 filename 파라미터 뿐만 아니라 일반 filename 파라미터도 함께 반환하도록 변경되었다. 이제 부트 3에서 ContentDisposition 클래스를 사용하는 경우, Content-Disposition 헤더는 다음과 같이 반환된다.

Content-Disposition: form-data; name="name"; filename="=?UTF-8?Q?=E4=B8=AD=E6=96=87.txt?="; filename*=UTF-8''%E4%B8%AD%E6%96%87.txt

 

 

스프링 부트3는 filename 파라미터를 표현하기 위해 RFC-2047에 정의된 Quoted-Printable 방식으로 인코딩하였다. Quoted-Printable 인코딩은 특수 문자나 이진 데이터를 안전하게 전송하기 위한 인코딩 방식 중 하나로, ASCII 문자들은 그대로 사용하고 ASCII가 아닌 문자들(non-ASCII characters)은 특정한 규칙에 따라 인코딩하는 방식이다. 이는 주로 이베일 본문이나 헤더에서 특수 문자를 안전하게 처리하기 위해 사용되며, MIME (Multipurpose Internet Mail Extensions)에서 정의된 표준 인코딩 방식 중 하나다. 자세한 규칙은 당장 알 필요가 없으니, 나중에 필요할 때 자세히 살펴보도록 하자.

 

 

 

[ Content-Disposition 헤더에 일반 filename 파라미터가 추가된 이유 ]

스프링 부트3에서 이러한 변경이 생긴 이유는 이전 브라우저의 하위 호환성을 위해서이다. 이전에 일부 브라우저에서는 RFC-6266에서도 이를 권장하고 있어서, 어떤 개발자가 이에 대한 이슈를 등록하였고, 수정되었다.

 

 

RFC 6266, section 4.3:

Many user agent implementations predating this specification do not understand the "filename" parameter. Therefore, when both "filename" and "filename*" are present in a single header field value, recipients SHOULD pick "filename*" and ignore "filename". This way, senders can avoid special-casing specific user agents by sending both the more expressive "filename*" parameter, and the "filename" parameter as fallback for legacy recipients (see [Section 5] for an example).*

 

 

RFC 6266, section 5 (Examples):

This example is the same as the one above, but adding the "filename" parameter for compatibility with user agents not implementing [RFC 5987]:

 

 

 

만약 스프링부트의 버전을 올렸는데, 클라이언트 쪽에서 Content-Disposition 헤더의 filename 파라미터 파싱에 실패하고 있다면, 이러한 부분을 확인해보면 좋을 것이다.

 

 

 

 

 

참고 자료

• https://github.com/spring-projects/spring-framework/commit/58fbf60d2d5d28d96c351eb539a52bceffac270a
• https://github.com/spring-projects/spring-framework/issues/29861
• https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ContentDisposition.html
• https://datatracker.ietf.org/doc/html/rfc6266
• https://datatracker.ietf.org/doc/html/rfc5987
• https://datatracker.ietf.org/doc/html/rfc2047