Retrofit — co to jest, biblioteka HTTP i zastosowanie w aplikacjach

Co to jest Retrofit?

Retrofit to biblioteka do wykonywania zapytań HTTP w aplikacjach Android, opracowana przez firmę Square. Zapewnia deklaratywne podejście do definiowania REST API poprzez interfejsy Java z adnotacjami, co sprawia, że kod komunikacji sieciowej jest czysty i przewidywalny.

Główna idea Retrofit polega na tym, że programista opisuje API jako interfejs z metodami i adnotacjami, a biblioteka samodzielnie generuje implementację. Takie podejście gwarantuje, że wszystkie endpointy są typowane, a błędy w URL lub parametrach są wykrywane na etapie kompilacji, a nie w czasie wykonania.

Retrofit obsługuje wszystkie popularne metody HTTP i formaty danych. Biblioteka jest aktywnie utrzymywana przez Square i społeczność: nowe wersje są wydawane regularnie, a obecna wersja 2.11 obejmuje obsługę Java 17 i Kotlin 2.0. Retrofit pozostaje najpopularniejszym klientem HTTP dla Androida.

Retrofit działa na OkHttp — wydajnym kliencie HTTP również od Square. Taki zestaw zapewnia buforowanie, przechwytywanie zapytań i zarządzanie połączeniami na poziomie protokołu transportowego. Biblioteka obsługuje zarówno synchroniczne, jak i asynchroniczne wywołania.

Od pierwszego wydania w 2013 roku Retrofit przeszedł kilka dużych aktualizacji. Obecna wersja Retrofit 2 została całkowicie przepisana z uwzględnieniem doświadczeń z pierwszej wersji i oferuje bardziej elastyczny system konwerterów i adapterów dla asynchroniczności.

Architektura Retrofit kieruje się zasadą podziału odpowiedzialności: interfejs definiuje tylko kontrakt API, konwertery odpowiadają za serializację, a adaptery zarządzają asynchronicznością. Pozwala to na wymianę dowolnego komponentu bez zmiany reszty kodu. Na przykład można przejść z Gson na Moshi bez zmiany definicji endpointów.

Główne możliwości Retrofit

Retrofit zapewnia zestaw funkcji, które pokrywają praktycznie wszystkie scenariusze komunikacji sieciowej w aplikacjach mobilnych. Kluczową zaletą jest deklaratywny styl definiowania API.

Deklaratywne adnotacje endpointów

Adnotacje @GET, @POST, @PUT, @PATCH, @DELETE i @HTTP pozwalają określić metodę HTTP i szablon URL bezpośrednio w interfejsie. Parametry ścieżki są ustawiane przez @Path, parametry zapytania przez @Query, a treść zapytania przez @Body. Takie podejście sprawia, że warstwa API aplikacji jest w pełni typowana.

Konwertery do serializacji

Konwertery przekształcają odpowiedzi HTTP w obiekty Java i odwrotnie. Retrofit obsługuje Gson, Moshi, Jackson, Protobuf i Wire. Programista podłącza odpowiedni konwerter przez Converter.Factory, a biblioteka automatycznie stosuje go do wszystkich zapytań i odpowiedzi.

Adaptery do asynchroniczności

Adaptery CallAdapter umożliwiają zmianę typu zwracanej wartości metod API. Zamiast standardowego Call można użyć Observable dla RxJava, Deferred dla korutyn Kotlin lub LiveData. To integruje zapytania sieciowe z wybraną architekturą aplikacji.

Dynamiczne URL i nagłówki

Dynamiczne URL są ustawiane przez adnotacje @Url, co pozwala przekazywać endpoint w czasie wykonania. Nagłówki można określać statycznie przez @Headers lub dynamicznie przez parametr @Header. Do globalnych nagłówków wszystkich zapytań używa się przechwytywacza OkHttp, który dodaje nagłówki do każdego wychodzącego zapytania.

Jak działa Retrofit?

Retrofit działa w trzech etapach: definiowanie interfejsu API, utworzenie instancji Retrofit i wykonanie zapytania. Biblioteka generuje implementację interfejsu w czasie wykonania na podstawie adnotacji i konwerterów.

Cykl życia zapytania

Gdy wywoływana jest metoda API, Retrofit tworzy obiekt Request na podstawie adnotacji i argumentów. Zapytanie jest przekazywane do OkHttp w celu wykonania. Po otrzymaniu odpowiedzi biblioteka przekazuje ją do Converter.Factory w celu przekształcenia na odpowiedni typ. CallAdapter opakowuje wynik w asynchroniczne opakowanie. Każdy etap można dostosować.

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)

Instalacja i konfiguracja Retrofit

Instalacja Retrofit odbywa się przez Gradle — standardowy system budowania Androida. Biblioteka jest rozpowszechniana przez Maven Central i wymaga dodania kilku zależności w build.gradle projektu.

Dodawanie zależności

W pliku build.gradle (poziomu modułu) dodaj zależności dla Retrofit, konwertera Gson i OkHttp. Wersje bibliotek zaleca się wyodrębnić do zmiennych w głównym build.gradle w celu scentralizowanego zarządzania. Retrofit 2 wymaga minimum 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"
}

Tworzenie instancji Retrofit

Instancję Retrofit tworzy się przez Builder. Obowiązkowe parametry: baseUrl i ConverterFactory. Zaleca się używanie singletonu dla Retrofit i OkHttpClient, aby uniknąć tworzenia nadmiarowych połączeń. Dodanie logging-interceptor upraszcza debugowanie zapytań sieciowych podczas rozwoju.

W projektach Kotlin zaleca się używanie suspend-funkcji w interfejsie API zamiast typów Call. Upraszcza to kod i pozwala na użycie strukturalnej współbieżności korutyn. Przy przejściu z Call na suspend wystarczy zmienić typ zwracany w interfejsie — reszta kodu dostosowuje się automatycznie.

Przykłady użycia Retrofit

Przykłady poniżej demonstrują typowe scenariusze pracy z Retrofit w aplikacjach Android: od prostego zapytania GET po przesyłanie pliku na serwer.

Zapytanie GET z parametrami zapytania

Proste zapytanie GET z parametrami łańcucha zapytania — podstawowa operacja. Adnotacja @Query dodaje parametry do URL automatycznie, a suspend-funkcja pozwala wywołać zapytanie z korutyny bez blokowania głównego wątku.

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

val users = api.getUsers(page = 1)

Zapytanie POST z treścią JSON

Zapytanie POST z treścią JSON używa adnotacji @Body do przesłania obiektu. GsonConverterFactory automatycznie serializuje obiekt User do JSON. Korutyny Kotlin zapewniają wykonanie zapytania w tle bez interfejsów Callback.

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

val user = User(name = "Anna Iwanowa", email = "anna@example.com")
val created = api.createUser(user)

Przesyłanie pliku przez Multipart

Adnotacja @Multipart z @Part umożliwia przesyłanie plików na serwer. Retrofit automatycznie tworzy multipart-zapytanie z odpowiednimi nagłówkami. OkHttp zarządza postępem przesyłania przez RequestBody, co pozwala wyświetlić wskaźnik użytkownikowi.

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)

Obsługa błędów i przechwytywacze w Retrofit

Obsługa błędów w Retrofit opiera się na kombinacji mechanizmów OkHttp i korutyn Kotlin. Przechwytywacze OkHttp pozwalają logować zapytania, dodawać nagłówki uwierzytelniania i obsługiwać błędy, zanim dotrą one do kodu aplikacji.

Do scentralizowanej obsługi błędów często tworzy się opakowanie wokół wywołań API w postaci sealed class Result. Taka klasa zawiera dwa dziedziczniki: Success z danymi i Error z wyjątkiem. ViewModel otrzymuje ujednolicony wynik i może wyświetlić odpowiedni stan interfejsu użytkownika bez powielania kodu obsługi błędów w każdej funkcji.

Przechwytywacze Interceptor są dwóch typów: przechwytywacze aplikacyjne modyfikują zapytanie przed wysłaniem na serwer, a przechwytywacze sieciowe działają z odpowiedzią po jej otrzymaniu. Na przykład przechwytywacz może automatycznie odświeżać token dostępu po otrzymaniu 401 i powtarzać zapytanie z nowym tokenem bez udziału programisty.

Logowanie zapytań przez Interceptor

Przechwytywacz logowania HttpLoggingInterceptor — niezbędne narzędzie przy debugowaniu zapytań sieciowych. Wyświetla w Logcat metodę zapytania, URL, nagłówki, treść i kod odpowiedzi. Poziom logowania można skonfigurować: BASIC dla minimalnych informacji, HEADERS dla nagłówków lub BODY dla pełnej zawartości. W produkcji zaleca się używanie BASIC lub całkowite wyłączenie logowania.

Przechwytywacze Interceptor w OkHtml dzielą się na dwa typy: przechwytywacze aplikacyjne do modyfikacji zapytania i przechwytywacze sieciowe do pracy z surowymi danymi sieciowymi. Przechwytywacz logowania automatycznie wypisuje szczegóły zapytania i odpowiedzi w Logcat.

Obsługa błędów na poziomie korutyn odbywa się przez try-catch wokół wywołania suspend-funkcji. Retrofit zwraca błędy w postaci HttpException dla kodów 4xx i 5xx, UnknownHostException przy braku sieci i SocketTimeoutException przy przekroczeniu limitu czasu. Zaleca się używanie sealed class Result do ujednoliconej obsługi.