클라이언트 → (파일 전송) → 서버 → (파일 저장) → 스토리지

클라이언트 → (업로드 URL 요청) → 서버
서버 → (Presigned URL 발급) → 클라이언트
클라이언트 → (파일 직접 업로드) → 스토리지

public interface FileStorage {
    void uploadFile(String fileKey, byte[] bytes);
    FileResponse downloadFileStream(String fileKey);
    String generateUploadUrl(String fileKey, long expirationSeconds);
    String generateDownloadUrl(String fileKey, long expirationSeconds);
}

@RequiredArgsConstructor
public class CephFileStorage implements FileStorage {
    private final S3Client s3Client;
    private final S3Presigner s3Presigner;
    private final String bucketName;
 
    @Override
    public String generateUploadUrl(String fileKey, long expirationSeconds) {
        final PutObjectPresignRequest presignRequest = PutObjectPresignRequest.builder()
                .signatureDuration(Duration.ofSeconds(expirationSeconds))
                .putObjectRequest(b -> b
                        .bucket(bucketName)
                        .key(fileKey)
                        .contentType(FileUtils.getMediaType(fileKey)))
                .build();
        return s3Presigner.presignPutObject(presignRequest).url().toString();
    }
 
    @Override
    public String generateDownloadUrl(String fileKey, long expirationSeconds) {
        final GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder()
                .signatureDuration(Duration.ofSeconds(expirationSeconds))
                .getObjectRequest(b -> b
                        .bucket(bucketName)
                        .key(fileKey))
                .build();
        return s3Presigner.presignGetObject(presignRequest).url().toString();
    }
 
    @Override
    public FileResponse downloadFileStream(final String fileKey) {
        try {
            GetObjectRequest getObjectRequest = GetObjectRequest.builder()
                    .bucket(bucketName)
                    .key(fileKey)
                    .build();
            final ResponseInputStream<GetObjectResponse> responseInputStream =
                    s3Client.getObject(getObjectRequest);
            final GetObjectResponse response = responseInputStream.response();
            final String contentType = response.contentType();
            final long contentLength = response.contentLength();
            return new FileResponse(responseInputStream, contentType, fileKey, contentLength);
        } catch (NoSuchKeyException e) {
            throw new CoreException(CommonErrorType.NOT_FOUND,
                "File not found: " + fileKey);
        }
    }
 
    @Override
    public void uploadFile(String fileKey, byte[] bytes) {
        PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                .bucket(bucketName)
                .key(fileKey)
                .contentType(FileUtils.getMediaType(fileKey))
                .build();
        s3Client.putObject(putObjectRequest, RequestBody.fromBytes(bytes));
    }
}

domain 모듈
  ↑ (의존)
storage/port 모듈       ← FileStorage 인터페이스 정의
  ↑ (의존)
storage/adapter-ceph 모듈  ← CephFileStorage 구현, AWS SDK 의존
  ↑ (의존)
application/visual 모듈    ← Bean 등록 및 주입

@Configuration
public class StorageConfig {
 
    @Bean
    public FileStorage fileStorage(S3Client s3Client,
                                   S3Presigner s3Presigner,
                                   @Value("${storage.bucket-name}") String bucketName) {
        return new CephFileStorage(s3Client, s3Presigner, bucketName);
    }
}

@RequiredArgsConstructor
@Service
public class DocumentUploadService {
    private final FileStorage fileStorage;
    private final DocumentRepository documentRepository;
 
    public UploadUrlResponse generateUploadUrl(GenerateUploadUrlCommand command) {
        String fileKey = FileKeyGenerator.generate(command.domain(), command.fileName());
        String uploadUrl = fileStorage.generateUploadUrl(fileKey, 300L); // 5분 유효
        return new UploadUrlResponse(fileKey, uploadUrl);
    }
}

@ExtendWith(MockitoExtension.class)
class DocumentUploadServiceTest {
 
    @Mock
    private FileStorage fileStorage;
 
    @Mock
    private DocumentRepository documentRepository;
 
    @InjectMocks
    private DocumentUploadService documentUploadService;
 
    @Test
    void 업로드_URL_생성_시_올바른_fileKey가_반환된다() {
        // given
        given(fileStorage.generateUploadUrl(anyString(), anyLong()))
            .willReturn("https://storage.example.com/signed-url");
 
        var command = new GenerateUploadUrlCommand("domain", "test.pdf");
 
        // when
        var result = documentUploadService.generateUploadUrl(command);
 
        // then
        assertThat(result.uploadUrl()).isEqualTo("https://storage.example.com/signed-url");
        verify(fileStorage).generateUploadUrl(anyString(), eq(300L));
    }
}

// 개발 환경용 MinIO 어댑터
public class MinioFileStorage implements FileStorage {
    // MinIO 클라이언트로 동일한 인터페이스 구현
}
 
// Spring 프로파일로 환경별 Bean 선택
@Profile("local")
@Bean
public FileStorage fileStorage(MinioClient minioClient, ...) {
    return new MinioFileStorage(minioClient, bucketName);
}
 
@Profile("!local")
@Bean
public FileStorage fileStorage(S3Client s3Client, ...) {
    return new CephFileStorage(s3Client, s3Presigner, bucketName);
}