132 lines
12 KiB
Markdown
132 lines
12 KiB
Markdown
---
|
|
title: Spring Boot — Multipart File Uploads (spring.servlet.multipart, MultipartProperties defaults)
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-boot/how-to/spring-mvc.html
|
|
archive_url:
|
|
related_projects: []
|
|
related_branches: [feature-file-resource-handling-contract]
|
|
tags: [spring-boot, multipart, file-upload, spring-mvc, multipart-properties, servlet, jakarta-servlet, official-doc]
|
|
status: raw
|
|
confidence: high
|
|
created: 2026-05-27
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Spring Boot — Multipart File Uploads (spring.servlet.multipart, MultipartProperties defaults)
|
|
|
|
> Layer: `raw/official-docs/` — Spring Boot Reference / "How-To Guides / Spring MVC / Handling Multipart File Uploads" 페이지 + `MultipartProperties.java` source verbatim.
|
|
> File upload endpoint 의 `MultipartFile` baseline / max-file-size / max-request-size 의 1차 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-file-resource-handling-contract]] | D3 mechanism — Spring Boot 가 default 로 multipart upload 를 enable 하고 max-file-size=1MB / max-request-size=10MB 로 제한한다는 사실. D4 mechanism — `spring.servlet.multipart.*` property prefix 로 max-file-size override (예: `-1` 로 unlimited) + `MultipartFile` controller parameter 사용 패턴 |
|
|
|
|
## 컨텍스트
|
|
|
|
ca-tmpl 의 file/resource handling contract 는 (1) "기본은 작은 파일만 허용 → 1MB default 활용", (2) "큰 파일은 endpoint 별 `spring.servlet.multipart.max-file-size` override + 별도 storage 경로", (3) "controller 는 `@RequestParam MultipartFile`" 베이스라인을 따른다. 본 자료는 이 세 결정의 정확한 default 값 + property 명 + controller 형태를 verbatim 으로 보존. 추가로 `MultipartProperties.java` source 의 정확한 default literal (`DataSize.ofMegabytes(1)`, `DataSize.ofMegabytes(10)`, `DataSize.ofBytes(0)`, `enabled=true`) 를 함께 보존.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL (reference, how-to): https://docs.spring.io/spring-boot/how-to/spring-mvc.html (§Handling Multipart File Uploads)
|
|
- 보조 URL (source): https://raw.githubusercontent.com/spring-projects/spring-boot/main/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/servlet/MultipartProperties.java
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Boot (VMware / Broadcom)
|
|
- 발행일: rolling docs (current = Spring Boot 3.4+)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
### Reference 문서 (how-to / spring-mvc.html — §Handling Multipart File Uploads)
|
|
|
|
> [§Handling Multipart File Uploads] "Spring Boot embraces the servlet 5 `Part` API to support uploading files."
|
|
|
|
> [§Handling Multipart File Uploads] "By default, Spring Boot configures Spring MVC with a maximum size of 1MB per file and a maximum of 10MB of file data in a single request."
|
|
|
|
> [§Handling Multipart File Uploads] "You may override these values, the location to which intermediate data is stored (for example, to the `/tmp` directory), and the threshold past which data is flushed to disk by using the properties exposed in the `MultipartProperties` class."
|
|
|
|
> [§Handling Multipart File Uploads] "For example, if you want to specify that files be unlimited, set the `spring.servlet.multipart.max-file-size` property to `-1`."
|
|
|
|
> [§Handling Multipart File Uploads] "The multipart support is helpful when you want to receive multipart encoded file data as a `@RequestParam`-annotated parameter of type `MultipartFile` in a Spring MVC controller handler method."
|
|
|
|
> [§Handling Multipart File Uploads] "It is recommended to use the container's built-in support for multipart uploads rather than introduce an additional dependency such as Apache Commons File Upload."
|
|
|
|
### Source 코드 (MultipartProperties.java)
|
|
|
|
> [MultipartProperties.java — class annotation] `@ConfigurationProperties(prefix = "spring.servlet.multipart", ignoreUnknownFields = false)`
|
|
|
|
> [MultipartProperties.java — fields with defaults]
|
|
> ```
|
|
> /** Whether to enable support of multipart uploads. */
|
|
> private boolean enabled = true;
|
|
>
|
|
> /** Intermediate location of uploaded files. */
|
|
> private String location;
|
|
>
|
|
> /** Max file size. */
|
|
> private DataSize maxFileSize = DataSize.ofMegabytes(1);
|
|
>
|
|
> /** Max request size. */
|
|
> private DataSize maxRequestSize = DataSize.ofMegabytes(10);
|
|
>
|
|
> /** Threshold after which files are written to disk. */
|
|
> private DataSize fileSizeThreshold = DataSize.ofBytes(0);
|
|
>
|
|
> /** Whether to resolve the multipart request lazily at the time of file or parameter access. */
|
|
> private boolean resolveLazily;
|
|
> ```
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SB-MULTIPART-C1 | Spring Boot 의 multipart 지원은 servlet 5 (Jakarta Servlet 5+) 의 `Part` API 를 채택 | [§Handling Multipart File Uploads] "Spring Boot embraces the servlet 5 `Part` API to support uploading files." | `official-vendor-doc` | Spring Boot (Jakarta Servlet 5+ 환경) | Apache Commons FileUpload 또는 다른 multipart parser 가 fallback 으로 사용되는지는 본 인용 범위 밖 (별도 권고: "container built-in 사용" 명시) |
|
|
| SB-MULTIPART-C2 | Spring Boot 는 default 로 per-file max 1MB, per-request max 10MB 의 multipart 제한을 적용 | [§Handling Multipart File Uploads] "By default, Spring Boot configures Spring MVC with a maximum size of 1MB per file and a maximum of 10MB of file data in a single request." + [MultipartProperties.java] `private DataSize maxFileSize = DataSize.ofMegabytes(1);` + `private DataSize maxRequestSize = DataSize.ofMegabytes(10);` | `official-vendor-doc` | Spring Boot (current — 3.4+) auto-configuration 미override | reactive (WebFlux) 의 multipart default 가 동일한지는 본 인용 범위 밖 |
|
|
| SB-MULTIPART-C3 | multipart 관련 설정은 `MultipartProperties` 클래스를 통해 노출되며, prefix 는 `spring.servlet.multipart` 이고, max size / 저장 위치 / disk flush threshold 모두 override 가능 | [§Handling Multipart File Uploads] "You may override these values, the location to which intermediate data is stored (for example, to the `/tmp` directory), and the threshold past which data is flushed to disk by using the properties exposed in the `MultipartProperties` class." + [MultipartProperties.java] `@ConfigurationProperties(prefix = "spring.servlet.multipart", ignoreUnknownFields = false)` | `official-vendor-doc` | Spring Boot multipart auto-config | reactive (WebFlux) prefix 가 다른지 (실제로는 `spring.webflux.multipart`) 는 본 인용 범위 밖 |
|
|
| SB-MULTIPART-C4 | `spring.servlet.multipart.max-file-size=-1` 로 설정하면 파일 크기 제한 없음 (unlimited) | [§Handling Multipart File Uploads] "For example, if you want to specify that files be unlimited, set the `spring.servlet.multipart.max-file-size` property to `-1`." | `official-vendor-doc` | Spring Boot multipart property | unlimited 설정이 컨테이너 (Tomcat) 의 별도 제한을 우회한다는 뜻은 본 인용 범위 밖 |
|
|
| SB-MULTIPART-C5 | controller 에서 multipart 데이터는 `@RequestParam` annotation + `MultipartFile` 타입 parameter 로 받는 것이 권장 패턴 | [§Handling Multipart File Uploads] "The multipart support is helpful when you want to receive multipart encoded file data as a `@RequestParam`-annotated parameter of type `MultipartFile` in a Spring MVC controller handler method." | `official-vendor-doc` | Spring MVC controller handler method | `MultipartHttpServletRequest` 직접 사용 / `@RequestPart` 사용은 본 인용 범위 밖 (별도 Spring Framework MVC docs) |
|
|
| SB-MULTIPART-C6 | Apache Commons FileUpload 같은 별도 dependency 보다 컨테이너 내장 multipart 지원 사용이 권장됨 | [§Handling Multipart File Uploads] "It is recommended to use the container's built-in support for multipart uploads rather than introduce an additional dependency such as Apache Commons File Upload." | `official-vendor-doc` | Spring Boot 환경 (Tomcat/Jetty/Undertow embedded) | "container built-in" 이 servlet 컨테이너 (Tomcat) 의 multipart parser 임을 의미; 컨테이너별 동작 차이는 본 인용 범위 밖 |
|
|
| SB-MULTIPART-C7 | `MultipartProperties` 의 default field 값: `enabled = true`, `maxFileSize = 1MB`, `maxRequestSize = 10MB`, `fileSizeThreshold = 0 bytes` (즉 항상 disk 로 flush), `location = null` (servlet container default temp 사용), `resolveLazily = false` (default) | [MultipartProperties.java] `private boolean enabled = true;` + `private DataSize maxFileSize = DataSize.ofMegabytes(1);` + `private DataSize maxRequestSize = DataSize.ofMegabytes(10);` + `private DataSize fileSizeThreshold = DataSize.ofBytes(0);` + `private boolean resolveLazily;` (Java default = false) | `official-vendor-doc` | Spring Boot (main branch / current) MultipartProperties source | reactive (WebFlux) 의 동일 field 값은 본 인용 범위 밖. `fileSizeThreshold = 0` 의 정확한 의미 (모든 파일이 즉시 disk 로 가는지, threshold 가 비활성인지) 는 Servlet spec / 컨테이너 별 동작 확인 필요 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `SB-MULTIPART-C1`: Servlet 5 `Part` API 채택
|
|
- `SB-MULTIPART-C2`: default per-file 1MB / per-request 10MB
|
|
- `SB-MULTIPART-C3`: `MultipartProperties` + `spring.servlet.multipart` prefix
|
|
- `SB-MULTIPART-C4`: `max-file-size=-1` = unlimited
|
|
- `SB-MULTIPART-C5`: `@RequestParam MultipartFile` 권장 controller 패턴
|
|
- `SB-MULTIPART-C6`: 컨테이너 내장 multipart 권장
|
|
- `SB-MULTIPART-C7`: `MultipartProperties` source 의 정확한 default literal 6개
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- WebFlux (`spring.webflux.multipart`) 의 default 가 동일하다는 뜻 — 다름
|
|
- default 1MB/10MB 가 OWASP / 보안 best practice 라는 뜻 — Spring Boot 의 design 선택일 뿐, 별도 보안 가이드 필요
|
|
- Tomcat 의 `connectionTimeout` / `maxSwallowSize` 등 컨테이너 level limit 이 application property 와 어떻게 상호작용하는지
|
|
- 파일 업로드 streaming (chunked transfer) 의 자동 활성화 — `resolveLazily` 와 streaming 의 관계는 별도 검증 필요
|
|
- cleanup (`MultipartFile.transferTo` 후 임시 파일 삭제 시점) 의 정확한 동작
|
|
- virus scan / MIME type 검증 자동 활성화 — Spring Boot 가 제공하지 않음
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 `application.yml` 에서 `spring.servlet.multipart.max-file-size` override 여부 확인 (default 1MB 가 충분한지)
|
|
- file upload endpoint 가 `@RequestParam("file") MultipartFile file` 시그니처를 사용하는지 (vs `@RequestPart`)
|
|
- 임시 파일 location 설정 (`spring.servlet.multipart.location`) 이 컨테이너의 `/tmp` 와 충돌하지 않는지
|
|
- `fileSizeThreshold = 0` 의 실제 동작 (모든 multipart 가 disk 로 가는지 — Tomcat 의 경우 `0` 은 "all goes to disk" 의미일 수 있음)
|
|
|
|
## 메모 / Notes
|
|
|
|
- 인용 1 해석 후보 (미검증):
|
|
- `fileSizeThreshold = 0` literal 의 의미 → Servlet spec 의 `MultipartConfigElement.fileSizeThreshold` JavaDoc 에 따르면 "If not specified, the default of 0 will cause all uploaded files to be written to disk." 일 가능성. 본 raw 의 직접 인용에는 없으므로 별도 확인.
|
|
- 추가로 봐야 할 동일 출처 페이지:
|
|
- Servlet 5 `jakarta.servlet.http.Part` JavaDoc
|
|
- `https://docs.spring.io/spring-boot/api/java/org/springframework/boot/autoconfigure/web/servlet/MultipartAutoConfiguration.html` (auto-config 조건)
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/spring-restclient-builder-reference]] (outbound multipart 송신 측은 별도)
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-file-resource-handling-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 인용하는 wiki: (미작성)
|