이 라이브러리를 사용하면 모든 Java 웹 애플리케이션에서 재개 가능한(필요한 경우 비동기 방식의) 파일 업로드 기능을 제공할 수 있습니다. 이를 통해 사용자는 느리거나 불안정한 인터넷 연결에서도 대용량 파일을 업로드할 수 있습니다. 연결이 끊기거나 재설정된 뒤 파일 업로드를 일시 중지하거나 재개하는 기능은 공개 파일 업로드 프로토콜인 tus(https://tus.io/)를 구현하여 제공합니다. 이 라이브러리는 모든 선택적 확장 기능을 포함한 tus v1.0.0 프로토콜의 서버 측 기능을 구현합니다.
이 라이브러리의 Javadoc은 https://tus.desair.me/ 에서 확인할 수 있습니다. 버전 1.0.0-3.0부터 Java 17 이상이 필요합니다. 이전 Java 버전에서는 1.0.0-2.x 릴리스 중 하나를 사용하십시오.
tus-java-server 라이브러리는 Jakarta Servlet API 6.0과 일부 Apache Commons 유틸리티 라이브러리에만 의존합니다. 따라서 이론적으로 Tomcat, JBoss, Jetty 등 최신 Java 웹 애플리케이션 서버에서 사용할 수 있습니다. 기본적으로 업로드된 모든 데이터와 정보는 애플리케이션 서버의 파일 시스템에 저장됩니다. 현재는 이 방식만 지원합니다(설정 절 참조).
다음 의존성을 추가하면 Maven을 통해 이 라이브러리의 최신 안정 버전을 애플리케이션에 포함할 수 있습니다.
<dependency>
<groupId>me.desair.tus</groupId>
<artifactId>tus-java-server</artifactId>
<version>1.0.0-3.0-SNAPSHOT</version>
</dependency>
라이브러리의 주요 진입점은 me.desair.tus.server.TusFileUploadService.process(jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse) 메서드입니다. 이 메서드는 jakarta.servlet.http.HttpServlet, jakarta.servlet.Filter 또는 HttpServletRequest와 HttpServletResponse 객체에 접근할 수 있는 프레임워크의 REST API 컨트롤러 안에서 호출할 수 있습니다. 다음은 몇 가지 구현 예제입니다.
- Ralph가 작성한 상세 블로그 글: Spring Boot와 Tus JavaScript 클라이언트를 함께 사용하여 이 라이브러리를 사용하는 방법을 설명합니다.
- Dropwizard(Jetty)에서 폼 제출과 함께 Uppy를 사용한 재개 가능 비동기 파일 업로드
- Spring Boot REST API에서 Uppy JavaScript 클라이언트를 사용한 재개 가능 비동기 파일 업로드
- (추후 더 많은 예제가 추가될 예정입니다!)
핵심 프로토콜 외에도 이 라이브러리는 모든 선택적 tus 프로토콜 확장 기능을 기본적으로 활성화합니다. 따라서 Tus-Extension 헤더의 값은 creation,creation-defer-length,checksum,checksum-trailer,termination,expiration,concatenation,concatenation-unfinished입니다. 비공식 download 확장 기능도 선택적으로 활성화할 수 있습니다(설정 절 참조).
- creation: 새 업로드를 생성하고 해당 업로드 URL을 가져올 수 있는 생성 확장 기능입니다.
- creation-defer-length: 생성 시점에 최종 크기를 알지 못하더라도 새 업로드를 생성할 수 있습니다.
- checksum: 각 업로드(PATCH) 요청의 데이터 무결성을 검증할 수 있는 확장 기능입니다.
- checksum-trailer: 업로드 시작 시 체크섬 해시를 계산할 수 없다면 청크 분할 HTTP 요청의 끝에 트레일러 HTTP 헤더로 포함할 수 있습니다.
- termination: 클라이언트가 완료되었거나 진행 중인 업로드를 종료하여 tus-java-server 라이브러리가 서버 리소스를 해제하도록 합니다.
- expiration: 설정한 기간보다 오래된 업로드를 tus-java-server 라이브러리가 정리하도록 지정할 수 있습니다.
- concatenation: 여러 업로드를 하나의 최종 업로드로 결합할 수 있습니다. 이를 통해 클라이언트는 병렬 업로드와 비연속 청크 업로드를 수행할 수 있습니다.
- concatenation-unfinished: 부분 업로드가 아직 진행 중이어도 클라이언트가 해당 부분 업로드를 결합하는 요청을 보낼 수 있습니다.
download: 비공식 다운로드 확장 기능으로, 클라이언트가 HTTPGET요청을 사용하여 업로드된 파일을 내려받을 수 있습니다.withDownloadFeature()메서드를 호출하여 활성화할 수 있습니다.
첫 단계는 생성자를 사용하여 TusFileUploadService 객체를 만드는 것입니다. 이 객체를 (Spring 빈) 싱글턴으로 제공하거나 요청마다 새 인스턴스를 만들 수 있습니다. 객체를 생성한 뒤 다음 메서드로 설정할 수 있습니다.
withUploadUri(String): 기본 tus 업로드 엔드포인트가 제공될 상대 URL을 설정합니다(예:/files/upload). URL 매개변수가 포함된 엔드포인트를 지원하도록 이 URI에 정규식 매개변수를 선택적으로 포함할 수 있습니다(예:/users/[0-9]+/files/upload).withMaxUploadSize(Long): 업로드 한 건당 허용되는 최대 바이트 수를 지정합니다. 이 메서드를 호출하지 않으면 최대 바이트 수는Long.MAX_VALUE입니다.withStoragePath(String): 기본 파일 시스템 기반 저장 서비스를 사용하는 경우 업로드된 바이트와 업로드 정보를 저장할 경로를 지정합니다.withChunkedTransferDecoding: 이 라이브러리가 청크 분할 HTTP 요청을 디코딩할지 활성화하거나 비활성화합니다. 서비스가 실행되는 웹 컨테이너가 청크 분할 전송을 직접 디코딩하지 않는 경우 활성화하십시오. 최신 프레임워크는 일반적으로 이를 처리하므로 이 라이브러리의 청크 디코딩은 기본적으로 비활성화되어 있습니다.withThreadLocalCache(Boolean): 업로드 요청 데이터의 메모리 내 스레드 로컬 캐시를 선택적으로 활성화하거나 비활성화합니다. 이를 통해 저장소 백엔드의 부하를 줄이고 업로드 요청 처리 성능을 높일 수 있습니다.withUploadExpirationPeriod(Long): 업로드를 만료된 것으로 간주하여 정리할 수 있게 되는 시간을 밀리초 단위로 설정합니다.withDownloadFeature(): 업로드된 바이트를 내려받을 수 있게 하는 비공식download확장 기능을 활성화합니다.addTusExtension(TusExtension):me.desair.tus.server.TusExtension인터페이스를 구현하는 사용자 정의(애플리케이션 전용) 확장 기능을 추가합니다. 예를 들어 업로드를 수행하는 사용자에 대해 애플리케이션의 인증 및 권한 부여 정책을 검사하는 확장 기능을 추가할 수 있습니다.disableTusExtension(String):getName()메서드가 전달한 문자열과 일치하는TusExtension을 비활성화합니다. 기본 확장 기능의 이름은 "creation", "checksum", "expiration", "concatenation", "termination", "download"입니다. "core" 기능은 비활성화할 수 없습니다.withUploadIdFactory(UploadIdFactory): 각 업로드의 식별자를 생성하는 데 사용할 사용자 정의UploadIdFactory구현을 제공합니다. 기본 구현인UuidUploadIdFactory는 UUID를 사용하여 식별자를 생성합니다. 사용자 정의 ID 팩터리 구현의 또 다른 예로 시스템 시간 기반의TimeBasedUploadIdFactory클래스가 있습니다.
현재 이 라이브러리는 파일 시스템 기반 저장 및 잠금 옵션만 제공합니다. 하지만 다른 유형의 업로드 저장소를 지원하려면 withUploadStorageService(UploadStorageService) 및 withUploadLockingService(UploadLockingService) 메서드를 사용하여 자체 UploadStorageService와 UploadLockingService 구현을 제공할 수 있습니다.
업로드 요청을 처리하려면 현재 jakarta.servlet.http.HttpServletRequest와 jakarta.servlet.http.HttpServletResponse 객체를 me.desair.tus.server.TusFileUploadService.process() 메서드에 전달해야 합니다. 일반적으로 Servlet, Filter 또는 REST API Controller에서 처리할 수 있습니다(예제 참조).
선택적으로 String ownerKey 매개변수도 전달할 수 있습니다. 다중 테넌트 환경에서 ownerKey를 사용하면 서로 다른 사용자, 그룹 또는 테넌트의 업로드를 엄격하게 분리할 수 있습니다. ownerKey 값의 예로 사용자 ID, 그룹 이름, 클라이언트 ID 등이 있습니다.
사용자가 업로드를 완료하면 애플리케이션의 비즈니스 로직 계층에서 업로드된 바이트를 가져와 처리해야 합니다. 예를 들어 파일 내용을 읽거나 업로드된 바이트를 최종 영구 저장 위치로 이동할 수 있습니다. 백엔드에서 업로드된 바이트를 가져오려면 me.desair.tus.server.TusFileUploadService.getUploadedBytes(String uploadUrl) 메서드를 사용합니다. 전달하는 uploadUrl 값은 클라이언트가 파일을 업로드할 때 사용한 업로드 URL이어야 합니다. 따라서 애플리케이션은 완료된 업로드의 업로드 URL을 백엔드에 전달해야 합니다. 애플리케이션이 소유자 키를 사용하여 업로드를 처리하도록 구성했다면 이 메서드에 ownerKey 값을 선택적으로 전달할 수도 있습니다. ownerKey로 사용할 수 있는 값에는 내부 사용자 식별자, 세션 ID, 애플리케이션 하위 영역의 이름 등이 있습니다.
me.desair.tus.server.TusFileUploadService.getUploadInfo(String uploadUrl) 메서드를 사용하면 특정 업로드 과정의 메타데이터를 가져올 수 있습니다. 여기에는 클라이언트가 제공한 메타데이터뿐 아니라 생성 타임스탬프, 생성자 IP 주소 목록, 업로드 크기 등 라이브러리가 관리하는 메타데이터도 포함됩니다. UploadInfo.getId() 메서드는 UploadId 인스턴스에 캡슐화된 업로드의 고유 식별자를 반환합니다. 업로드의 원래 사용자 정의 생성 식별자 객체는 UploadId.getOriginalObject()로 가져올 수 있습니다. UploadId.toString()은 식별자의 URL 안전 문자열 표현을 반환합니다. 두 클래스의 JavaDoc을 확인할 것을 강력히 권장합니다.
서버 백엔드에서 업로드된 바이트를 처리한 뒤(예: 최종 영구 위치로 복사)에는 임시 업로드 바이트를 정리해야 합니다. me.desair.tus.server.TusFileUploadService.deleteUpload(String uploadUri) 메서드를 호출하면 됩니다. 이 메서드는 저장소 백엔드에서 업로드된 바이트와 관련 업로드 정보를 모두 제거합니다. 또는 클라이언트가 termination 확장 기능을 사용하여 진행 중인 업로드를 제거할 수도 있습니다.
완료되어 백엔드에서 처리된 업로드를 제거하는 것뿐 아니라 만료된 업로드 또는 잠금을 정리하는 정기 유지보수 작업을 예약하는 것도 권장합니다. 만료된 업로드와 잠금은 me.desair.tus.server.TusFileUploadService.cleanup() 메서드로 정리할 수 있습니다.
이 tus 프로토콜 구현은 Uppy 파일 업로드 클라이언트와 함께 테스트되었습니다. 또한 이 저장소에는 일반 HTTP 요청으로 tus 프로토콜 서버 구현을 검증하는 다수의 자동화 통합 테스트가 포함되어 있습니다. 따라서 이론적으로 tus 1.0.0을 준수하는 모든 클라이언트와 호환됩니다.
이 아티팩트의 버전 형식은 A.B.C-X.Y입니다. 여기서 A.B.C는 구현된 tus 프로토콜의 버전(현재 1.0.0)이고 X.Y는 이 라이브러리의 버전입니다.
이 라이브러리는 어떠한 보증도 없이 제공되며 MIT 라이선스에 따라 배포됩니다. 버그를 발견하거나 유용한 개선 아이디어가 있다면 새 이슈를 등록하거나 제안 구현을 담은 풀 리퀘스트를 생성해 주십시오. 기여하는 모든 코드에는 자동화된 단위 테스트 및/또는 통합 테스트가 함께 포함되어야 하며 정의된 코드 스타일을 준수해야 합니다.
모든 풀 리퀘스트는 Google Java Style 코드 형식에 따라 올바르게 포맷되어야 합니다. 코드 스타일이 올바른지 확인하려면 다음 명령을 실행합니다.
mvn -P codestyle com.spotify.fmt:fmt-maven-plugin:check
코드 형식을 다시 맞추려면 다음 명령을 실행합니다.
mvn -P codestyle com.spotify.fmt:fmt-maven-plugin:format
IDE 설정 권장 사항은 Google Java Style GitHub 페이지를 참조하십시오. Python 3가 설치되어 있다면 pre-commit을 사용하여 작업을 더 편리하게 할 수도 있습니다.
pip install pre-commit
pre-commit install