S3Client는 AWS SDK에서 제공하는 클래스 중 하나로, Amazon S3(Simple Storage Service)와 상호작용하는 기능을 제공합니다. 주로 파일 업로드, 다운로드, 삭제, 리스트 조회 등의 기능을 수행할 때 사용됩니다.
1. S3Client 개요
S3Client는 AWS SDK에서 제공하는 S3 서비스의 클라이언트 객체이며, 기본적으로 싱크 방식(Blocking I/O)으로 동작합니다. 만약 비동기 방식이 필요하다면 S3AsyncClient를 사용할 수 있습니다.
- AWS SDK for Java에서 제공하는 V1과 V2가 존재하지만, 현재 V2를 권장합니다.
- V2에서는
S3Client.builder()를 이용해 클라이언트를 생성할 수 있습니다.
2. S3Client 기본 사용법
(1) Maven 또는 Gradle 의존성 추가
Maven
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>s3</artifactId>
<version>2.20.100</version>
</dependency>Gradle
dependencies {
implementation("software.amazon.awssdk:s3:2.20.100")
}(2) S3Client 생성
1) 기본 클라이언트 생성
기본적으로 환경변수 또는 AWS 설정 파일(~/.aws/credentials)에서 자격증명을 가져옵니다.
import software.amazon.awssdk.services.s3.S3Client;
S3Client s3Client = S3Client.builder().build();2) 특정 리전과 자격증명을 명시적으로 설정
import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
S3Client s3Client = S3Client.builder()
.region(Region.AP_NORTHEAST_2) // 서울 리전
.credentialsProvider(ProfileCredentialsProvider.create("default"))
.build();Region.AP_NORTHEAST_2: 서울 리전ProfileCredentialsProvider.create("default"):~/.aws/credentials파일에서default프로필을 사용
3. 주요 기능
(1) S3 버킷 목록 조회
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
ListBucketsResponse listBucketsResponse = s3Client.listBuckets();
listBucketsResponse.buckets().forEach(bucket -> {
System.out.println("Bucket: " + bucket.name());
});listBuckets(): 사용자의 모든 S3 버킷을 조회
(2) 파일 업로드
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import java.nio.file.Paths;
String bucketName = "my-bucket";
String key = "uploads/sample.txt"; // S3 내에서 저장될 경로
String filePath = "/local/path/to/sample.txt"; // 로컬 파일 경로
s3Client.putObject(
PutObjectRequest.builder()
.bucket(bucketName)
.key(key)
.build(),
RequestBody.fromFile(Paths.get(filePath))
);PutObjectRequest.builder().bucket(bucketName).key(key).build(): 버킷과 키를 설정RequestBody.fromFile(Paths.get(filePath)): 로컬 파일을 읽어 업로드
(3) 파일 다운로드
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import java.nio.file.Paths;
String bucketName = "my-bucket";
String key = "uploads/sample.txt";
String downloadPath = "/local/path/to/downloaded.txt";
s3Client.getObject(
GetObjectRequest.builder().bucket(bucketName).key(key).build(),
Paths.get(downloadPath)
);GetObjectRequest.builder().bucket(bucketName).key(key).build(): 다운로드할 S3 객체 지정Paths.get(downloadPath): 파일을 저장할 로컬 경로
(4) 파일 삭제
import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
s3Client.deleteObject(
DeleteObjectRequest.builder()
.bucket("my-bucket")
.key("uploads/sample.txt")
.build()
);deleteObject(): 지정한 S3 객체 삭제
(5) 버킷 내 파일 목록 조회
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
String bucketName = "my-bucket";
ListObjectsV2Response listObjectsResponse = s3Client.listObjectsV2(
ListObjectsV2Request.builder().bucket(bucketName).build()
);
listObjectsResponse.contents().forEach(object -> {
System.out.println("File: " + object.key());
});listObjectsV2(): 특정 버킷의 파일 목록을 조회
4. S3Client vs S3AsyncClient
| 비교 항목 | S3Client (동기) | S3AsyncClient (비동기) |
|---|---|---|
| 요청 처리 방식 | 블로킹(Blocking) | 논블로킹(Non-Blocking) |
| API 응답 방식 | Response 객체 반환 | CompletableFuture<Response> 반환 |
| 추천 사용 케이스 | 작은 규모의 애플리케이션 | 대규모 트래픽 또는 비동기 병렬 처리 필요할 때 |
| 예제 | s3Client.putObject(...) | s3AsyncClient.putObject(...).thenAccept(response -> {...}) |
S3AsyncClient는 Netty 기반으로 동작하며, 대량의 파일 업로드/다운로드 처리 시 성능을 최적화할 수 있음.- 하지만 일반적인 Spring Boot 애플리케이션에서는
S3Client를 사용하는 것이 보편적.
5. S3 Presigned URL 사용 (서버에서 직접 업로드 X, 클라이언트에서 업로드)
S3에 파일을 업로드할 때 Presigned URL을 사용하면, 클라이언트가 직접 S3에 업로드할 수 있습니다.
Presigned URL 생성
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.presigner.S3Presigner;
import software.amazon.awssdk.services.s3.presigner.model.GetObjectPresignRequest;
import java.time.Duration;
S3Presigner presigner = S3Presigner.create();
GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder()
.signatureDuration(Duration.ofMinutes(10)) // 10분 동안 유효
.getObjectRequest(GetObjectRequest.builder()
.bucket("my-bucket")
.key("uploads/sample.txt")
.build())
.build();
String presignedUrl = presigner.presignGetObject(presignRequest).url().toString();
System.out.println("Presigned URL: " + presignedUrl);- 생성된 Presigned URL을 클라이언트에서 사용하면, 서버를 거치지 않고 직접 S3에 접근 가능.
6. 정리
S3Client는 AWS S3와 상호작용하는 기본적인 동기식 클라이언트.- 주요 기능:
- 버킷 및 객체 관리 (업로드, 다운로드, 삭제, 목록 조회 등)
- Presigned URL을 활용한 보안 업로드 및 다운로드
- 대규모 트래픽 처리 시
S3AsyncClient또는Presigned URL을 고려할 수 있음.
배포 환경에서는 IAM Role을 활용하여 자격 증명을 관리하는 것이 일반적이며, 필요에 따라 S3 Transfer Acceleration 등을 활용하면 속도를 더욱 최적화할 수 있습니다.
🌱