Retrofit — 개념, HTTP 라이브러리 및 애플리케이션에서의 사용

Retrofit이란?

Retrofit은 Square사가 개발한 Android 애플리케이션에서 HTTP 요청을 수행하기 위한 라이브러리입니다. Java 인터페이스와 어노테이션을 통해 REST API를 선언적으로 정의하는 접근 방식을 제공하여 네트워크 상호작용 코드를 깔끔하고 예측 가능하게 만듭니다.

Retrofit의 핵심 아이디어는 개발자가 API를 메서드와 어노테이션이 있는 인터페이스로 설명하면 라이브러리가 자동으로 구현을 생성한다는 것입니다. 이 접근 방식은 모든 엔드포인트가 타입화되고 URL이나 매개변수의 오류가 런타임이 아닌 컴파일 타임에 감지되도록 보장합니다.

Retrofit은 모든 인기 있는 HTTP 메서드와 데이터 형식을 지원합니다. 이 라이브러리는 Square와 커뮤니티에 의해 활발히 유지 관리됩니다. 새 버전이 정기적으로 출시되며, 현재 버전 2.11은 Java 17 및 Kotlin 2.0을 지원합니다. Retrofit은 Android에서 가장 인기 있는 HTTP 클라이언트로 남아 있습니다.

Retrofit은 또한 Square의 효율적인 HTTP 클라이언트인 OkHttp 위에서 작동합니다. 이 조합은 캐싱, 요청 인터셉션 및 전송 프로토콜 수준의 연결 관리를 제공합니다. 이 라이브러리는 동기 및 비동기 호출을 모두 지원합니다.

2013년 첫 출시 이후 Retrofit은 여러 주요 업데이트를 거쳤습니다. 현재 버전 Retrofit 2는 첫 번째 버전의 경험을 바탕으로 완전히 재작성되었으며 비동기 처리를 위한 더 유연한 컨버터 및 어댑터 시스템을 제공합니다.

Retrofit의 아키텍처는 관심사의 분리 원칙을 따릅니다. 인터페이스는 API 계약만 정의하고, 컨버터는 직렬화를 담당하며, 어댑터는 비동기 처리를 관리합니다. 이를 통해 나머지 코드를 변경하지 않고도 모든 구성 요소를 교체할 수 있습니다. 예를 들어, 엔드포인트 정의를 변경하지 않고 Gson에서 Moshi로 전환할 수 있습니다.

Retrofit의 주요 기능

Retrofit은 모바일 애플리케이션의 거의 모든 네트워크 상호작용 시나리오를 포괄하는 기능 세트를 제공합니다. 주요 장점은 API 정의의 선언적 스타일입니다.

선언적 엔드포인트 어노테이션

어노테이션 @GET, @POST, @PUT, @PATCH, @DELETE 및 @HTTP를 사용하면 인터페이스에서 직접 HTTP 메서드와 URL 템플릿을 지정할 수 있습니다. 경로 매개변수는 @Path를 통해, 쿼리 매개변수는 @Query를 통해, 요청 본문은 @Body를 통해 설정됩니다. 이 접근 방식은 애플리케이션의 API 계층을 완전히 타입화합니다.

직렬화를 위한 컨버터

컨버터는 HTTP 응답을 Java 객체로 또는 그 반대로 변환합니다. Retrofit은 Gson, Moshi, Jackson, Protobuf 및 Wire를 지원합니다. 개발자는 Converter.Factory를 통해 필요한 컨버터를 연결하면 라이브러리가 모든 요청과 응답에 자동으로 적용합니다.

비동기 처리를 위한 어댑터

어댑터 CallAdapter를 사용하면 API 메서드의 반환 유형을 변경할 수 있습니다. 표준 Call 대신 RxJava용 Observable, Kotlin 코루틴용 Deferred 또는 LiveData를 사용할 수 있습니다. 이를 통해 네트워크 요청을 선택한 애플리케이션 아키텍처에 통합할 수 있습니다.

동적 URL 및 헤더

동적 URL은 @Url 어노테이션을 통해 설정되어 런타임에 엔드포인트를 전달할 수 있습니다. 헤더는 @Headers를 통해 정적으로 또는 @Header 매개변수를 통해 동적으로 지정할 수 있습니다. 모든 요청에 대한 전역 헤더의 경우 각 발신 요청에 헤더를 추가하는 OkHttp 인터셉터가 사용됩니다.

Retrofit의 작동 방식

Retrofit은 API 인터페이스 정의, Retrofit 인스턴스 생성, 요청 실행의 세 단계로 작동합니다. 라이브러리는 어노테이션과 컨버터를 기반으로 런타임에 인터페이스 구현을 생성합니다.

요청 라이프사이클

API 메서드가 호출되면 Retrofit은 어노테이션과 인수를 기반으로 Request 객체를 생성합니다. 요청은 실행을 위해 OkHttp로 전달됩니다. 응답을 받은 후 라이브러리는 필요한 유형으로 변환하기 위해 Converter.Factory에 전달합니다. CallAdapter는 결과를 비동기 래퍼로 감쌉니다. 각 단계를 사용자 지정할 수 있습니다.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(ApiService::class.java)

Retrofit 설치 및 설정

Retrofit의 설치는 Android 표준 빌드 시스템인 Gradle을 통해 수행됩니다. 라이브러리는 Maven Central을 통해 배포되며 프로젝트의 build.gradle에 여러 종속성을 추가해야 합니다.

종속성 추가

build.gradle 파일(모듈 수준)에 Retrofit, Gson 컨버터 및 OkHttp에 대한 종속성을 추가합니다. 중앙 집중식 관리를 위해 루트 build.gradle에서 라이브러리 버전을 변수로 추출하는 것이 좋습니다. Retrofit 2에는 최소 Android API 21이 필요합니다.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Retrofit 인스턴스 생성

Retrofit 인스턴스는 Builder를 통해 생성됩니다. 필수 매개변수: baseUrl 및 ConverterFactory입니다. 중복 연결을 피하기 위해 Retrofit 및 OkHttpClient에 싱글톤을 사용하는 것이 좋습니다. logging-interceptor를 추가하면 개발 중 네트워크 요청 디버깅이 간소화됩니다.

Kotlin 프로젝트의 경우 Call 유형 대신 API 인터페이스에서 suspend 함수를 사용하는 것이 좋습니다. 이렇게 하면 코드가 간소화되고 코루틴의 구조적 동시성을 사용할 수 있습니다. Call에서 suspend로 전환할 때는 인터페이스의 반환 유형만 변경하면 나머지 코드는 자동으로 적용됩니다.

Retrofit 사용 예제

아래 예제는 Android 애플리케이션에서 Retrofit을 사용하는 일반적인 시나리오를 보여줍니다. 간단한 GET 요청부터 서버에 파일 업로드까지 다룹니다.

쿼리 매개변수가 있는 GET 요청

쿼리 문자열 매개변수가 있는 간단한 GET 요청은 기본 작업입니다. @Query 어노테이션이 자동으로 URL에 매개변수를 추가하고, suspend 함수를 사용하면 메인 스레드를 차단하지 않고 코루틴에서 요청을 호출할 수 있습니다.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

JSON 본문이 있는 POST 요청

JSON 본문이 있는 POST 요청은 @Body 어노테이션을 사용하여 객체를 전달합니다. GsonConverterFactory는 User 객체를 자동으로 JSON으로 직렬화합니다. Kotlin 코루틴은 Callback 인터페이스 없이 백그라운드 스레드에서 요청 실행을 보장합니다.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "안나 이바노바", email = "anna@example.com")
val created = api.createUser(user)

Multipart를 통한 파일 업로드

@Multipart 어노테이션과 @Part를 사용하면 서버에 파일을 업로드할 수 있습니다. Retrofit은 필요한 헤더로 multipart 요청을 자동으로 구성합니다. OkHttp는 RequestBody를 통해 업로드 진행 상황을 관리하여 사용자에게 표시기를 표시할 수 있습니다.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Retrofit의 오류 처리 및 인터셉터

Retrofit의 오류 처리는 OkHttp 메커니즘과 Kotlin 코루틴의 조합을 기반으로 구축됩니다. OkHttp 인터셉터를 사용하면 요청 로깅, 인증 헤더 추가 및 애플리케이션 코드에 도달하기 전에 오류를 처리할 수 있습니다.

중앙 집중식 오류 처리를 위해 API 호출 주변에 sealed class Result로 래퍼를 만드는 경우가 많습니다. 이러한 클래스에는 데이터가 있는 Success와 예외가 있는 Error의 두 하위 클래스가 있습니다. ViewModel은 통합된 결과를 수신하고 각 함수에서 오류 처리 코드를 중복하지 않고 해당 사용자 인터페이스 상태를 표시할 수 있습니다.

인터셉터에는 두 가지 유형이 있습니다. 애플리케이션 인터셉터는 서버로 보내기 전에 요청을 수정하고, 네트워크 인터셉터는 수신 후 응답으로 작업합니다. 예를 들어, 인터셉터는 401을 수신할 때 자동으로 액세스 토큰을 갱신하고 개발자 개입 없이 새 토큰으로 요청을 재시도할 수 있습니다.

Interceptor를 통한 요청 로깅

로깅 인터셉터 HttpLoggingInterceptor는 네트워크 요청 디버깅에 필수적인 도구입니다. Logcat에 요청 메서드, URL, 헤더, 본문 및 응답 코드를 출력합니다. 로깅 수준은 최소 정보의 경우 BASIC, 헤더의 경우 HEADERS, 전체 내용의 경우 BODY로 구성할 수 있습니다. 프로덕션에서는 BASIC을 사용하거나 로깅을 완전히 비활성화하는 것이 좋습니다.

OkHttp의 인터셉터는 요청을 수정하는 애플리케이션 인터셉터와 원시 네트워크 데이터로 작업하는 네트워크 인터셉터의 두 가지 유형으로 나뉩니다. 로깅 인터셉터는 자동으로 요청 및 응답 세부 정보를 Logcat에 출력합니다.

코루틴 수준의 오류 처리는 suspend 함수 호출 주변의 try-catch를 통해 수행됩니다. Retrofit은 4xx 및 5xx 코드의 경우 HttpException, 네트워크가 없는 경우 UnknownHostException, 시간 초과가 발생한 경우 SocketTimeoutException으로 오류를 반환합니다. 통합 처리를 위해 sealed class Result를 사용하는 것이 좋습니다.