Ktor와 함께 GraphQL 마스터하기: Android를 위한 현대적인 네트워킹 가이드

Source: Dev.to

원본이 Medium에 게시되었습니다:

소개

현대 Android 앱은 유연하고 효율적이며 확장 가능한 네트워킹 솔루션을 요구합니다. 수년간 표준이었던 REST API에 비해, GraphQL은 특히 정확한 데이터 가져오기와 네트워크 오버헤드 감소가 필요한 앱에 강력한 대안으로 떠올랐습니다. 여러 엔드포인트를 호출해 각각의 데이터를 얻는 대신, GraphQL을 사용하면 하나의 요청으로 정확히 필요한 데이터만 요청할 수 있습니다.

이전 글에서는 JetBrains에서 개발한 최신 Kotlin‑first 네트워킹 프레임워크 Ktor를 설정하는 방법을 다뤘습니다. Ktor가 Retrofit에 비해 가벼운 대안이 되는 방식을 살펴보았습니다. 아직 읽어보지 않으셨다면, 기본 클라이언트를 설정하기 위해 꼭 확인해 보시길 권합니다. 해당 글은 여기에서 확인할 수 있습니다:

Exploring Ktor: A Modern Networking Framework for Kotlin

이제 한 단계 더 나아가 GraphQL을 Ktor와 통합하여 효율적인 API를 구축하는 방법을 살펴보겠습니다. 초보자이든 스택을 현대화하려는 개발자이든, 이 가이드는 설정부터 첫 번째 요청 만들기까지 모든 과정을 다룹니다.

GraphQL이란?

GraphQL은 API를 위한 쿼리 언어로, 클라이언트가 정확히 필요한 데이터만 요청할 수 있게 합니다—더 많지도, 더 적지도 않게.

주요 차이점은 REST가 고정된 응답 구조를 가진 여러 엔드포인트를 사용하는 반면, GraphQL은 단일 엔드포인트와 유연한 쿼리를 사용해 최적화된 응답을 제공한다는 점입니다. 이러한 대역폭 효율성은 매 킬로바이트가 중요한 모바일 앱에 완벽합니다.

왜 Ktor와 GraphQL을 사용할까?

• 최소 오버헤드 – 무거운 외부 라이브러리가 필요 없으며, APK 크기를 작게 유지합니다.
• 전체 제어 – 요청 및 응답이 어떻게 처리되는지 정확히 정의할 수 있습니다.
• 멀티플랫폼 지원 – 동일한 로직이 Kotlin Multiplatform (KMP)에서도 원활히 작동합니다.
• Kotlin‑First – 코루틴 기반이며 콜백이 없고, Clean Architecture와 MVVM과 매끄럽게 연동됩니다.

프로젝트 설정

GraphQL을 통합하기 전에 Android 프로젝트에 Ktor가 포함되어 있는지 확인하세요. 앱‑레벨 build.gradle.kts에 다음 의존성을 추가합니다:

dependencies {
    implementation(platform("io.ktor:ktor-bom:3.1.2"))
    implementation("io.ktor:ktor-client-android")
    implementation("io.ktor:ktor-client-content-negotiation")
    implementation("io.ktor:ktor-serialization-kotlinx-json")
    implementation("io.ktor:ktor-client-logging")
}

루트 build.gradle.kts에서 Kotlin Serialization 플러그인을 활성화합니다:

plugins {
    id("org.jetbrains.kotlin.plugin.serialization") version "2.1.20"
}

Ktor와 함께 GraphQL 작동 방식 이해하기

GraphQL에서는 모든 작업이 일반적으로 단일 엔드포인트에 대한 POST 요청으로 이루어집니다. 쿼리 또는 뮤테이션은 JSON 본문으로 전달됩니다.

요청 모델 정의

@Serializable
data class GraphQLRequest(
    val query: String,
    val variables: Map<String, Any>? = null
)

일반 응답 래퍼 정의

@Serializable
data class GraphQLResponse<T>(
    val data: T? = null,
    val errors: List<GraphQLError>? = null
)

@Serializable
data class GraphQLError(val message: String)

첫 번째 요청 만들기

공개 GraphQL API를 사용하여 국가 목록을 가져옵니다. 먼저 데이터 모델을 정의합니다:

@Serializable
data class CountriesData(val countries: List<Country>)

@Serializable
data class Country(
    val code: String,
    val name: String,
    val emoji: String,
    val capital: String? = null
)

구현

suspend fun fetchCountries(): GraphQLResponse<CountriesData> {
    val countryQuery = """
        query {
            countries {
                code
                name
                emoji
                capital
            }
        }
    """.trimIndent()

    return httpClient.post("https://countries.trevorblades.com/graphql") {
        setBody(GraphQLRequest(query = countryQuery))
    }.body()
}

오류 처리 및 로깅

GraphQL은 쿼리 로직에 오류가 있더라도 HTTP 200 상태 코드를 반환할 수 있습니다. 항상 오류 목록을 확인하세요:

val response = fetchCountries()
if (!response.errors.isNullOrEmpty()) {
    response.errors.forEach { error ->
        Log.e("GraphQL Error", error.message)
    }
}

전문적인 로깅을 위해서는 Timber 사용을 권장합니다. 나중에 게시한 글에서 Timber를 Ktor와 통합하는 자세한 가이드를 작성했습니다.

자세한 가이드

A detailed guide on setting it up here: Effortless Android Logging with Timber and Kotlin

Medium에서 기사 읽기

최종 생각

GraphQL을 Ktor와 통합하는 것은 간단하며 Android 개발자에게 현대적이고 유연하며 Kotlin‑네이티브 네트워킹 스택을 제공합니다. MVVM 및 Clean Architecture와 아름답게 어울립니다. 단일 통합된 HttpClient를 활용하면 REST와 GraphQL을 모두 원활하게 처리할 수 있습니다.

실습 레퍼런스를 위한 GitHub 저장소

이 글을 보다 실용적으로 만들기 위해, 실제 GraphQL API를 사용해 위에서 논의한 모든 내용을 시연하는 공개 GitHub 저장소를 공개했습니다.

이 프로젝트의 목표는 단순히 **“데이터를 가져오는 것”**이 아니라, Ktor를 이용해 Android 애플리케이션에 GraphQL을 관용적으로 통합하는 방법을 보여주는 것입니다—REST‑기반 추상화를 강제로 끼워 넣지 않습니다.

📂 GitHub 저장소:

https://github.com/your-username/ktor-graphql-android-example (실제 URL로 교체)

GraphQL Example – Android (Jetpack Compose + Ktor)

Overview

간단하고 깔끔한 Android 샘플로, Jetpack Compose 애플리케이션 내에서 Ktor를 사용해 GraphQL API를 소비하는 방법을 보여줍니다.
프로젝트는 Clean Architecture와 MVVM 원칙을 따르며, REST‑스타일 추상화(예: 가짜 HTTP 상태 코드나 일반 응답 래퍼) 없이 관용적인 GraphQL 처리를 구현합니다.

✨ Features

• ✅ Ktor를 이용한 GraphQL API 통합
• ✅ Jetpack Compose UI
• ✅ Clean Architecture (Data → Domain → UI)
• ✅ 단방향 데이터 흐름을 갖는 MVVM
• ✅ Kotlin Coroutines
• ✅ Koin을 이용한 의존성 주입
• ✅ 올바른 GraphQL 오류 처리 (data vs errors)
• ✅ Retrofit 없이, REST‑스타일 CommonResponse도 없음

🔗 API Used (Free & Public)

Countries GraphQL API

https://countries.trevorblades.com/graphql

Sample query

query {
  countries {
    code
    name
    capital
  }
}

This API is:

• 완전 무료
• 인증 필요 없음
• 데모 및 학습에 이상적

🏗️ Architecture Overview

아래는 앱 레이어와 상호 작용 방식을 보여주는 고수준 다이어그램입니다. 각 구성 요소는 독립적으로 유지되어 테스트 가능성, 유지 보수성 및 확장성을 높입니다.

graph TD
    UI[UI (Jetpack Compose)] --> ViewModel[ViewModel (Android Architecture Components)]
    ViewModel --> Repository[Repository]
    Repository -->|Local| RoomDB[(Room Database)]
    Repository -->|Remote| Retrofit[(Retrofit API)]
    Repository -->|Cache| DataStore[(DataStore / SharedPreferences)]

Layer Breakdown

Interaction Flow

1. User Action – UI가 이벤트(예: 버튼 클릭)를 발생시킵니다.
2. ViewModel – 이벤트를 받아 StateFlow/LiveData를 업데이트하고 적절한 Repository 메서드를 호출합니다.
3. Repository – 로컬 캐시(Room/DataStore)에서 가져올지, 네트워크 요청(Retrofit)을 할지 결정합니다.
4. Data Sources – 데이터를 반환하거나 오류를 반환하여 체인을 거슬러 올라갑니다.
5. ViewModel – 새로운 UI 상태를 방출하고, Compose UI가 이를 관찰해 재구성합니다.

Tip: UI 레이어는 가능한 한 단순하게 유지하세요 – 상태를 렌더링하고 사용자 의도를 전달하는 역할만 담당합니다. 모든 로직은 ViewModel이나 Repository에 두어 Android 의존성 없이도 단위 테스트가 쉽게 이루어지도록 합니다.