Retrofit — co to je, HTTP knihovna a použití v aplikacích

Co je Retrofit?

Retrofit je knihovna pro provádění HTTP požadavků v aplikacích Android, vyvinutá společností Square. Poskytuje deklarativní přístup k definování REST API prostřednictvím Java rozhraní s anotacemi, což činí kód síťové komunikace čistým a předvídatelným.

Hlavní myšlenkou Retrofit je, že vývojář popíše API jako rozhraní s metodami a anotacemi, a knihovna sama vygeneruje implementaci. Tento přístup zaručuje, že všechny endpointy jsou typované a chyby v URL nebo parametrech jsou odhaleny při kompilaci, nikoli za běhu.

Retrofit podporuje všechny populární HTTP metody a formáty dat. Knihovna je aktivně udržována Square a komunitou: nové verze vycházejí pravidelně a současná verze 2.11 zahrnuje podporu Java 17 a Kotlin 2.0. Retrofit zůstává nejpopulárnějším HTTP klientem pro Android.

Retrofit pracuje na OkHttp — efektivním HTTP klientovi také od Square. Tato kombinace zajišťuje cache, zachytávání požadavků a správu připojení na úrovni transportního protokolu. Knihovna podporuje jak synchronní, tak asynchronní volání.

Od prvního vydání v roce 2013 prošel Retrofit několika velkými aktualizacemi. Současná verze Retrofit 2 byla kompletně přepsána s ohledem na zkušenosti z první verze a nabízí flexibilnější systém konvertorů a adaptérů pro asynchronitu.

Architektura Retrofit následuje princip oddělení odpovědností: rozhraní definuje pouze smlouvu API, konvertory jsou zodpovědné za serializaci a adaptéry spravují asynchronitu. To umožňuje vyměnu libovolné komponenty bez změny zbytku kódu. Například lze přejít z Gson na Moshi bez změny definic endpointů.

Hlavní funkce Retrofit

Retrofit poskytuje sadu funkcí, které pokrývají prakticky všechny scénáře síťové komunikace v mobilních aplikacích. Klíčovou výhodou je deklarativní styl definování API.

Deklarativní anotace endpointů

Anotace @GET, @POST, @PUT, @PATCH, @DELETE a @HTTP umožňují definovat HTTP metodu a šablonu URL přímo v rozhraní. Parametry cesty se nastavují pomocí @Path, parametry dotazu pomocí @Query a tělo požadavku pomocí @Body. Tento přístup činí API vrstvu aplikace kompletně typovanou.

Konvertory pro serializaci

Konvertory převádějí HTTP odpovědi na Java objekty a naopak. Retrofit podporuje Gson, Moshi, Jackson, Protobuf a Wire. Vývojář připojí požadovaný konvertor pomocí Converter.Factory a knihovna jej automaticky aplikuje na všechny požadavky a odpovědi.

Adaptéry pro asynchronitu

Adaptéry CallAdapter umožňují změnu návratového typu metod API. Místo standardního Call lze použít Observable pro RxJava, Deferred pro korutiny Kotlin nebo LiveData. To integruje síťové požadavky se zvolenou architekturou aplikace.

Dynamické URL a hlavičky

Dynamické URL se nastavují pomocí anotace @Url, což umožňuje předávání endpointu za běhu. Hlavičky lze specifikovat staticky pomocí @Headers nebo dynamicky pomocí parametru @Header. Pro globální hlavičky všech požadavků se používá interceptor OkHttp, který přidává hlavičky ke každému odchozímu požadavku.

Jak Retrofit funguje?

Retrofit pracuje ve třech fázích: definování API rozhraní, vytvoření instance Retrofit a provedení požadavku. Knihovna generuje implementaci rozhraní za běhu na základě anotací a konvertorů.

Životní cyklus požadavku

Když je zavolána metoda API, Retrofit vytvoří objekt Request na základě anotací a argumentů. Požadavek je předán OkHttp k provedení. Po obdržení odpovědi ji knihovna předá Converter.Factory k převodu na požadovaný typ. CallAdapter zabalí výsledek do asynchronního obalu. Každou fázi lze přizpůsobit.

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)

Instalace a konfigurace Retrofit

Instalace Retrofit se provádí prostřednictvím Gradle — standardního sestavovacího systému Androidu. Knihovna je distribuována přes Maven Central a vyžaduje přidání několika závislostí v build.gradle projektu.

Přidání závislostí

Do souboru build.gradle (na úrovni modulu) přidejte závislosti pro Retrofit, konvertor Gson a OkHttp. Verze knihoven se doporučuje vyčlenit do proměnných v kořenovém build.gradle pro centralizovanou správu. Retrofit 2 vyžaduje minimálně 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"
}

Vytvoření instance Retrofit

Instance Retrofit se vytváří pomocí Builder. Povinné parametry: baseUrl a ConverterFactory. Doporučuje se používat singleton pro Retrofit a OkHttpClient, aby se zabránilo vytváření nadbytečných připojení. Přidání logging-interceptoru zjednodušuje ladění síťových požadavků během vývoje.

Pro projekty v Kotlinu se doporučuje používání suspend funkcí v API rozhraní místo typů Call. To zjednodušuje kód a umožňuje použití strukturované konkurence korutin. Při přechodu z Call na suspend stačí změnit návratový typ v rozhraní — zbytek kódu se automaticky přizpůsobí.

Příklady použití Retrofit

Příklady níže demonstrují typické scénáře práce s Retrofit v aplikacích Android: od jednoduchého GET požadavku po nahrávání souboru na server.

GET požadavek s parametry dotazu

Jednoduchý GET požadavek s parametry dotazu — základní operace. Anotace @Query přidává parametry automaticky do URL a suspend funkce umožňuje zavolat požadavek z korutiny bez blokování hlavního vlákna.

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

val users = api.getUsers(page = 1)

POST požadavek s tělem JSON

POST požadavek s tělem JSON používá anotaci @Body pro předání objektu. GsonConverterFactory automaticky serializuje objekt User do JSON. Korutiny Kotlin zajišťují provedení požadavku na pozadí bez rozhraní Callback.

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

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

Nahrávání souboru pomocí Multipart

Anotace @Multipart s @Part umožňuje nahrávání souborů na server. Retrofit automaticky vytvoří multipart požadavek s potřebnými hlavičkami. OkHttp spravuje průběh nahrávání pomocí RequestBody, což umožňuje zobrazení indikátoru uživateli.

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)

Zpracování chyb a interceptory v Retrofit

Zpracování chyb v Retrofit je založeno na kombinaci mechanismů OkHttp a korutin Kotlin. Interceptory OkHttp umožňují logovat požadavky, přidávat autentizační hlavičky a zpracovávat chyby dříve, než dosáhnou kódu aplikace.

Pro centralizované zpracování chyb se často vytváří obal kolem API volání ve formě sealed class Result. Taková třída obsahuje dva potomky: Success s daty a Error s výjimkou. ViewModel obdrží unifikovaný výsledek a může zobrazit odpovídající stav uživatelského rozhraní bez duplikování kódu pro zpracování chyb v každé funkci.

Interceptory jsou dvou typů: aplikáční interceptory upravují požadavek před odesláním na server a síťové interceptory pracují s odpovědí po obdržení. Například interceptor může automaticky obnovit přístupový token při obdržení 401 a zopakovat požadavek s novým tokenem bez účasti vývojáře.

Logování požadavků pomocí Interceptor

Logovací interceptor HttpLoggingInterceptor — nezbytný nástroj při ladění síťových požadavků. Zobrazuje v Logcat metodu požadavku, URL, hlavičky, tělo a kód odpovědi. Úroveň logování lze nakonfigurovat: BASIC pro minimální informace, HEADERS pro hlavičky nebo BODY pro úplný obsah. V produkci se doporučuje BASIC nebo úplné vypnutí logování.

Interceptory v OkHttp se dělí na dva typy: aplikáční interceptory pro úpravu požadavku a síťové interceptory pro práci se syrovými síťovými daty. Logovací interceptor automaticky zobrazuje podrobnosti požadavku a odpovědi v Logcat.

Zpracování chyb na úrovni korutin se provádí pomocí try-catch kolem volání suspend funkce. Retrofit vrací chyby jako HttpException pro kódy 4xx a 5xx, UnknownHostException při nedostupnosti sítě a SocketTimeoutException při překročení časového limitu. Doporučuje se použít sealed class Result pro unifikované zpracování.