Retrofit: co to je, vlastnosti HTTP klienta pro Android

Co je Retrofit?

Retrofit — je knihovna pro typovanou interakci s REST API na platformě Android, vyvinutá společností Square. Poskytuje deklarativní způsob popisu HTTP požadavků prostřednictvím rozhraní Java nebo Kotlin s anotacemi, zcela osvobozujíc vývojáře od ručního parsování JSON a správy HTTP připojení.

Knihovna se objevila v roce 2013 jako alternativa k těžkopádným řešením jako AsyncTask a HttpURLConnection. Do roku 2025 zůstává Retrofit de facto standardem pro síťovou komunikaci v aplikacích pro Android díky jednoduchosti a typové bezpečnosti. Podle průzkumu JetBrains Developer Ecosystem 2024 používá Retrofit více než 65 % vývojářů pro Android v komerčních projektech.

Klíčový rozdíl Retrofit od analogů — deklarativní přístup: vývojář popisuje co dělat (který endpoint volat, jaké parametry předat), ne jak to udělat (jak otevřít připojení, jak číst InputStream, jak parsovat JSON). To snižuje množství boilerplate kódu o 60–70 % ve srovnání s ručním použitím HttpURLConnection.

Jak Retrofit funguje

Princip fungování Retrofit je založen na dynamických proxy Java. Když vývojář zavolá metodu rozhraní označenou anotacemi, Retrofit prostřednictvím mechanismu Proxy.newProxyInstance zachytí volání a převede ho na HTTP požadavek. Celý proces probíhá za běhu bez generování kódu ve fázi kompilace.

Při vytváření instance Retrofit.Builder se specifikuje základní URL a továrna na konvertory. Builder konfiguruje OkHttpClient — nastavuje timeouty, interceptory, fond připojení a cache. Metoda create(Class) generuje implementaci rozhraní a vrací proxy objekt, který lze volat jako běžnou třídu.

Řetězec provádění požadavku vypadá takto: anotace extrahují HTTP metodu, parametry jsou vloženy do URL nebo těla požadavku, konvertor serializuje tělo, OkHttp provede požadavek, konvertor deserializuje odpověď, výsledek je vrácen v uvedeném typu. Každá fáze je izolovaná a může být nahrazena vlastní implementací, například nahrazení OkHttpClient za MockWebServer pro testování nebo změna konvertoru při změně API.

Důležitá vlastnost — Retrofit přímo nepodporuje streamování dat. Pro streamování se používá OkHttp ResponseBody jako návratový typ metody rozhraní. Retrofit také automaticky nespravuje rušení požadavků — pro zrušení je třeba uložit referenci na Call a zavolat cancel(). V Kotlinu se suspend funkcemi dojde ke zrušení požadavku automaticky při zrušení nadřazené korutiny.

Životní cyklus objektu Call

Call<T> — je objekt představující jeden HTTP požadavek. Po provedení (execute nebo enqueue) nelze Call znovu použít — pro opakovaný požadavek je třeba vytvořit nový Call voláním metody rozhraní. To chrání před náhodným odesláním stejného požadavku dvakrát, což by mohlo vést k duplikaci operací na serveru.

V Kotlinu se místo Call používají suspend funkce, které automaticky spravují životní cyklus požadavku. Retrofit sám přepíná provádění na Dispatchers.IO a vrací výsledek do korutiny. To zkracuje kód o 30–40 % ve srovnání s verzí na Call a Callback.

Anotace Retrofit pro HTTP metody

Anotace — jsou hlavním mechanismem konfigurace HTTP požadavků v Retrofit. Každá anotace odpovídá standardní HTTP metodě a přijímá relativní cestu k endpointu. Retrofit podporuje GET, POST, PUT, DELETE, PATCH, HEAD a OPTIONS.

Anotace parametrů požadavku

@Path nahrazuje hodnotu v segmentu URL: @Path(id) Int id nahrazuje {id} v cestě. @Query přidává parametr dotazu: @Query(page) Int page se mění na ?page=5. @Body předává objekt v těle požadavku s automatickou serializací pomocí vybraného konvertoru. @Header a @Headers spravují HTTP hlavičky — statické nebo dynamické.

Kombinací těchto anotací lze popsat libovolný REST endpoint. Například pro endpoint POST /api/users/{id}/posts?limit=10 budou potřeba @POST, @Path pro id, @Query pro limit a @Body pro předávaný objekt. Retrofit automaticky sestaví správný HTTP požadavek. Dále jsou podporovány @Url (dynamické URL), @Field (form-encoded tělo), @Part a @PartMap pro multipart požadavky se soubory.

Příklady kódu Retrofit v Kotlinu

Podívejme se na praktický příklad — rozhraní pro GitHub API. Vytvoří se Kotlin rozhraní s metodou pro získání seznamu repozitářů. Data class Repo popisuje strukturu JSON odpovědi.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Po popisu rozhraní se vytvoří instance Retrofit přes Builder. Základní URL, konvertor a OkHttpClient se nakonfigurují jednou a znovu používají pomocí dependency injection.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

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

Zpracování odpovědi s obalem Response

Pro flexibilní zpracování HTTP stavů použijte obal Response<T>. Poskytuje přístup ke kódu odpovědi, hlavičkám a tělu, aniž by vyhazoval výjimku při chybách 4xx a 5xx. To umožňuje zpracovávat 404 a 500 bez try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Chyba: ${response.code()}")
}

Konvertory a serializace v Retrofit

Konvertory — jsou komponenty Retrofit zodpovědné za převod objektů na HTTP tělo a naopak. Retrofit nevestaví serializaci do jádra — místo toho používá modulární přístup přes Converter.Factory, umožňující připojení libovolné serializační knihovny.

Nejoblíbenější konvertor — GsonConverterFactory od Google založený na knihovně Gson. Je vhodný pro většinu projektů, podporuje vlastní TypeAdapter a JsonDeserializer. Nicméně Gson používá reflexi a nebere v úvahu null safety Kotlin, což může vést k NPE při neočekávaných null polích.

Alternativa — MoshiConverterFactory od Square: přísnější k typům, s lepší podporou Kotlin (null safety, default values) a bez reflexe. Pro projekty v čistém Kotlin je optimální Kotlinx Serialization Converter, pracující na @Serializable anotacích ve fázi kompilace. Nepoužívá reflexi, podporuje sealed class, default values a multiplatformnost.

Výběr konvertoru ovlivňuje výkon a bezpečnost typů. Gson bez vlastní konfigurace může deserializovat null do non-null pole Kotlin, což způsobí NPE při přístupu. Moshi řeší tento problém pomocí anotace @Json(name) a failOnUnknown. Kotlinx Serialization je nejbezpečnější — generuje kód ve fázi kompilace, zcela eliminuje runtime chyby typů.

Typické chyby při práci s Retrofit

Chybějící zpracování HTTP chyb v suspend funkcích — nejčastější problém. Pokud server vrátí 4xx nebo 5xx, Retrofit vyhodí HttpException. Bez try-catch aplikace havaruje. Použití Response<T> jako návratového typu řeší tento problém a umožňuje kontrolovat isSuccessful před přístupem k body.

Nesprávné nastavení cache vede k nadměrnému provozu. Retrofit neukládá odpovědi do cache sám — tento úkol řeší OkHttpClient přes Cache. Bez cache se každý požadavek provádí celý, i když se data nezměnila. Přidání Cache o velikosti 10 MB do OkHttpClient snižuje provoz o 40–60 % při opakovaných požadavcích stejných informací.

Vytváření Retrofit pro každý požadavek — častá chyba začátečníků. Retrofit.Builder je operace náročná na zdroje, zahrnující generování proxy tříd za běhu. Správná praxe — vytvořit jednu instanci Retrofit a znovu ji používat přes DI frameworky. Hilt, Koin nebo Dagger poskytují singleton instanci Retrofit pro celou aplikaci, což šetří paměť a zrychluje požadavky.

Ignorování Interceptor pro autorizaci — čtvrtý problém. Místo ručního přidávání hlavičky Authorization do každého volání nakonfigurujte globální Interceptor v OkHttpClient. Interceptor zachytí každý požadavek, přidá Bearer token a Authenticator zpracuje odpověď 401, obnoví token a automaticky zopakuje požadavek. To centralizuje logiku autentizace.