[Android]Ktor - Multipart 사용하기(feat. 클린 아키텍쳐)

Retrofit을 사용할 때는 자료가 많아서 신경안썼던 부분인데, Ktor를 이번에 사용하게 되면서 겪은 이슈들을 적어보겠다.

먼저 클린 아키텍쳐에 대해 간단하게 짚고 넘어가보자.

# Clean Architecture

워낙 개인간의 의견 차이가 심해서 논란이 되는 주제기도 하지만, CleanArchitecture를 사용함으로써 얻는 강점은 SOLID를 지킨다는 것이다. 이걸 도입해야될 정도의 규모가 아닌데도 도입하는 건 오버엔지니어링이라고들 하지만, 일단 나는 학습용으로 도입했다.

Domain에는 UseCase 인터페이스와, 전역에서 사용할 Model(Entities)이 존재한다. 

아키텍쳐를 설명할 때 보통 domain, data, presenter 레이어로 나눠서 보는데, CleanArchitecture와 구글이 권장하는 앱 아키텍쳐의 차이는 domain에 있다.

아래가 권장 앱 아키텍쳐,

flowchart LR
    B[Domain] --> C[Data]
    C --> D[Presentation]

그리고 이게 클린 아키텍쳐다

flowchart LR
    B[Data] --> C[Domain]
    D[Presentation]--> C

이전에는 도메인이 data를 알고 있는데 반해, 클린아키텍쳐의 경우 도메인은 아무도 모른다. 그래서 모듈을 만들때도 안드로이드 의존성도 제거한 Kotlin, Java Library 모듈로 만드는 것이다.

 

클린아키텍쳐를 적용했을 때 MultiPart가 어려워지는 점은 하나다.

File을 parameter로 넘기는 게 아니라, uri를 넘기는 것이라면 인터페이스에 Uri로 파라미터를 선언해야되는데 도메인 모듈은 android 의존성이 없기 때문에 Uri 타입을 가질 수 없다. 이걸 기반으로 이제 Ktor로 Multipart 적용하기를 시작해보겠다.

---

# Ktor에서 파일을 업로드 하는 방법

Ktor에서 파일을 업로드하는 방법은 2가지다. 공통점은 formData로 당연히 묶어야한다는 것인데 `submitFormWithBinaryData`와 post 요청을 `MultiPartFormDataContent`로 설정하는 방식의 차이점을  한 번 살펴보자. 예제 코드는 공식문서에서 가져온 것이다.

`submitFormWithBinaryData`

val client = HttpClient(CIO)

val response: HttpResponse = client.submitFormWithBinaryData(
    url = "http://localhost:8080/upload",
    formData = formData {
        append("description", "Ktor logo")
        append("image", File("ktor_logo.png").readBytes(), Headers.build {
            append(HttpHeaders.ContentType, "image/png")
            append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
        })
    }
)

이미지는 기본적으로 바이너리데이터다. 그래서 Ktor에서는 이걸 그냥 쉽게 보낼 수 있도록 해주는데, ByteArray로 변환된 File을 폼데이터에 넣어주고, Mime Type과 ContentDisposition 헤더를 설정하여 파일로 인식될 수 있도록 한다.

내부구조를 살펴보면 suspend 함수로 되어있다.

inline suspend fun HttpClient.submitFormWithBinaryData(
    url: String, 
    formData: List<PartData>, 
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

기본적으로 post로 동작한다. 폼 데이터의 경계를 Ktor가 알아서 관리 해주고, 따로 진행상황 모니터링은 지원하지않는다. 바이너리 데이터를 전송하는 역할을 하기때문에, 이미지가 아니더라도 일단 바이너리로 관리할 수 있는 모든 파일을 전송할 수 있다.

 

## Boundary? 경계?

방금 설명에서 폼데이터의 경계라는 게 있었다. 이게 뭔지 한 번 살펴보자.

멀티파트 폼 데이터에서 바운더리는 각 파트를 구분하는 역할을 하는 고유한 문자열이다. 멀티파트 형식은 하나의 HTTP 요청 본문 안에 여러 개의 파일이나 폼 필드를 포함할 수 있도록 설계되어 있으며, 각 파트를 서로 구분하기 위해 경계가 필요한데, 아래와 같다.

Content-Type: multipart/form-data; boundary=----WebAppBoundary

HTTP 요청 본문에 여러 개의 파일이나 텍스트 파트가 포함될 때, 바운더리 문자열을 사용하여 각 파트를 구분할 수 있다. 예를 들어, 텍스트 설명과 이미지 파일을 동시에 보낼 때 각각의 파트를 분리하기 위해 경계를 사용한다. 레트로핏에서 `@Part`로 구분하는게 이런 역할을 한다고 보면 된다. 

여러개로 쪼개게 되면 아래와 같이 요청이 간다.

------WebAppBoundary
Content-Disposition: form-data; name="description"

Ktor logo
------WebAppBoundary
Content-Disposition: form-data; name="image"; filename="ktor_logo.png"
Content-Type: image/png

기본적으로 바운더리는 자동생성이긴 하지만, `submitFormWithBinaryData`는 자동설정만 지원한다. 이제 한번 MultiPartFormDataContent를 봐보자

`MultiPartFormDataContent`

val client = HttpClient(CIO)

val response: HttpResponse = client.post("http://localhost:8080/upload") {
    setBody(MultiPartFormDataContent(
        formData {
            append("description", "Ktor logo")
            append("image", File("ktor_logo.png").readBytes(), Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
            })
        },
        boundary = "WebAppBoundary"
    ))
    onUpload { bytesSentTotal, contentLength ->
        println("Sent $bytesSentTotal bytes from $contentLength")
    }
}

이건 post요청에 Body로 넣는, 이전에 알고있던 방식에 가깝다. post 요청에 MultiPartFormDataContent를 사용하여 멀티파트 폼 데이터를 직접 설정하고 setBody 함수로 서버에 전송한다.

내부 구조를 보면 다른 점이 딱 보인다.

class MultiPartFormDataContent(
    parts: List<PartData>, 
    val boundary: String = generateBoundary(), 
    val contentType: ContentType = ContentType.MultiPart.FormData.withParameter("boundary", boundary)
) : OutgoingContent.WriteChannelContent

boundary를 수동으로 설정할 수 있다. 물론 기본 생성자가 있어서 따로 만들게 아니면 놔둬도 된다.

이제 중요한 차이점이 등장한다. onUpload인데, MultiPartFormDataContent는 내부적으로 파일 데이터를 청크단위로 분할하여 전송하는 방식으로 작동하고, 이 과정에서 각 청크가 전송될 때마다 onUpload 콜백을 호출할 수 있다. submitFormWithBinaryData는 청크단위로 전송하는 게 아니기 때문에 post + MultiPartFormDataContent일때만 가능하다. 

 

좀 더 자세히 보면 MultiPartFormDataContent는 OutgoingContent.WriteChannelContent를 상속하는 걸 볼 수 있다. 이 상속을 통해 비동기 스트리밍 방식으로 데이터를 전송할 수 있습니다. 즉, 모든 데이터를 한꺼번에 메모리에 로드하지 않고, 청크 단위로 데이터를 스트리밍하여 서버로 전송한다.

 

onUpload만 똑 떼서 보자.

onUpload { bytesSentTotal, contentLength ->
    println("Sent $bytesSentTotal bytes from $contentLength")
}

bytesSentTotal(지금까지 전송된 크기), contentLength(전송할 파일 전체 크기)로 진행상황을 보고있을 수 있어서, UI에 진행상황을 띄울 수 도 있을 것으로 보인다.

suspend fun uploadImage(
    image: Image,
    file: ByteArray,
    onProgress: (bytesSentTotal: Long, contentLength: Long) -> Unit
): CommonResponse<FileResponse> {
    return client.post("your_url") {
        setBody(MultiPartFormDataContent(
            formData {
                append("image", file, Headers.build {
                    append(HttpHeaders.ContentType, ContentType.Image.PNG)
                })
            }
        ))

        onUpload { bytesSentTotal, contentLength ->
            onProgress(bytesSentTotal, contentLength)
        }
    }.body()
}

이렇게 쓰면 onProgress로 상태가 계속 위쪽으로 이동해서 감지할 수 있을 것 같다.

이제 두 방식을 모두 살펴봤으니, 실제로 한번 데이터를 보내보겠다.

---

Ktor로 이미지 업로드 해보자

presenteter에서 단순히 uri만 던지고 나머지를 다 data 레이어에서 처리하는 구조로 진행한다. uri가 인터페이스에서 선언될 수 없으니까 `setProfileImageUseCase(contentUri = contentUri.toString())` 이렇게 String으로 변환해서 넘긴다.

3단계로 동작한다.

1. 가져온 contentUri로 실기기 안에 있는 이미지를 가져온다음
2. 이걸 InputStream으로 바꿔 ByteArray로 변환하는 과정을 거쳐서
3. client에 formData로 넘긴다.

먼저 이미지를 가져오려면 contentResolver를 사용해야된다. 

val uri = Uri.parse(contentUri)
val projection = arrayOf(
    MediaStore.Images.Media._ID,
    MediaStore.Images.Media.DISPLAY_NAME,
    MediaStore.Images.Media.SIZE,
    MediaStore.Images.Media.MIME_TYPE
)
val cursor = context.contentResolver.query(
    uri,
    projection,
    null,
    null,
    null
)

return cursor?.use { c->
    c.moveToNext() // 커서를 한칸 내려서 정보 가져오기
    val idIdx = c.getColumnIndexOrThrow(projection[0])
    val nameIdx = c.getColumnIndexOrThrow(projection[1])
    val sizeIdx = c.getColumnIndexOrThrow(projection[2])
    val typeIdx =  c.getColumnIndexOrThrow(projection[3])
    // idx를 알아야 커서가 컬럼에 대한 값을 가져올 수 있다
    val id = c.getLong(idIdx)
    val name = c.getString(nameIdx)
    val size = c.getLong(sizeIdx)
    val type = c.getString(typeIdx)
    Image(contentUri, name, size, type)
}

이 과정을 거치면 cursor를 통해 파일에 대한 정보를 모두 가져올 수 있다. 파일 길이, 파일 이름, mimetype까지 모두 가져올 수 있기 때문에 따로 매번 mimeType을 수동을 지정해줘야하는 불편함을 덜 수 있다.

이렇게 가져온 이미지 정보들은 multipart 요청 때 사용할 것이고, contentUri로 가져온 Uri를 InputStream으로 ByteArray 변환하는 과정은 또 따로 해준다.

val uri = Uri.parse(contentUri)
context.contentResolver.openInputStream(uri) ?: throw IllegalStateException("비어있음")

콘텐트 리졸버로 inputStream을 열어서 반환한다. 근데 이건 리소스를 열기 때문에 사용하게 되면 꼭 use를 써서 memory leak안나게 auto close 해줘야한다.

val byteArray = getInputStreamUseCase(image.uri).getOrElse {
    Log.e("UploadImageUseCase", "Failed to get InputStream: ${it.message}")
    throw it
}.use { inputStream ->
    inputStream.readBytes()
}

// readBytes 내부
public fun InputStream.readBytes(): ByteArray {
    val buffer = ByteArrayOutputStream(maxOf(DEFAULT_BUFFER_SIZE, this.available()))
    copyTo(buffer)
    return buffer.toByteArray()
}

이렇게 하면가져온 inputStream을 ByteArray로 바꿀 수 있다.

 

이제 ktor 클라이언트 호출부를 보자.

@Serializable // Data 모듈에서 사용하기 위해 직렬화를 해줬음
data class Image(
    val uri: String,
    val name: String,
    val size: Long,
    val mimeType: String
)

suspend fun uploadImage(imageFile: Image, file: ByteArray): CommonResponse<FileResponse> {
    return client.post("files") {
        setBody(
            MultiPartFormDataContent(
                formData {
                    append("fileName", imageFile.name)
                    append("file", file, Headers.build {
                        append(HttpHeaders.ContentType, imageFile.mimeType)
                        append(HttpHeaders.ContentDisposition, "filename=\"${imageFile.name}\"")
                    })
                },
            )
        )
        onUpload { bytesSentTotal, contentLength ->
            println("Sent $bytesSentTotal bytes from $contentLength")
        }
    }.body()
}

이 코드자체는 예시코드와 정말 다를 게 없다. mimeType과 contentDisposition을 contentResolver로 가져온걸 제외하면 똑같다.

onUpload를 사용해보기 위해서 나는 MultiPartFormDataContent를 사용했는데 로그에 아래와 같이 찍힌다.

Sent 4096 bytes from 233983
Sent 8192 bytes from 233983
Sent 12288 bytes from 233983
Sent 16384 bytes from 233983
Sent 20480 bytes from 233983
Sent 24576 bytes from 233983
Sent 28672 bytes from 233983
Sent 32768 bytes from 233983
Sent 36864 bytes from 233983
Sent 40960 bytes from 233983
Sent 45056 bytes from 233983
Sent 49152 bytes from 233983
Sent 53248 bytes from 233983
... 생략하겠다

4096Bytes 단위 청크로 전송되고있는 모습을 볼 수 있다!

 

도움이 됐다면 댓글이나 공감 버튼 한 번씩 누르고 가주세요!