Retrofit: mi ez, az Android HTTP-kliens jellemzői

Mi az a Retrofit?

Retrofit — egy könyvtár a típusos REST API interakcióhoz az Android platformon, amelyet a Square cég fejlesztett ki. Deklaratív módot biztosít a HTTP-kérések leírására Java vagy Kotlin interfészekkel és annotációkkal, teljesen felszabadítva a fejlesztőt a manuális JSON parsing és a HTTP kapcsolatok kezelése alól.

A könyvtár 2013-ban jelent meg alternatívaként a nehézkes megoldásokhoz, mint az AsyncTask és a HttpURLConnection. 2025-re a Retrofit továbbra is de facto szabvány a hálózati kommunikációban Android-alkalmazásokban a egyszerűségének és típusbiztonságának köszönhetően. A JetBrains Developer Ecosystem 2024 felmérése szerint a Retrofitot az Android-fejlesztők több mint 65%-a használja kereskedelmi projektekben.

A Retrofit fő különbsége az alternatívákkal szemben — a deklaratív megközelítés: a fejlesztő leírja, hogy mit kell csinálni (melyik endpointot hívja meg, milyen paramétereket adjon át), nem pedig hogy hogyan kell csinálni (hogyan nyissa meg a kapcsolatot, hogyan olvassa az InputStream-et, hogyan parse-olja a JSON-t). Ez 60–70%-kal csökkenti a boilerplate kód mennyiségét a HttpURLConnection manuális használatához képest.

Hogyan működik a Retrofit

Működési elv — a Retrofit Java dinamikus proxykon alapul. Amikor a fejlesztő meghív egy annotációkkal jelölt interfész metódust, a Retrofit a Proxy.newProxyInstance mechanizmuson keresztül elfogja a hívást és HTTP-kéréssé alakítja. Az egész folyamat futásidőben történik, kódgenerálás nélkül a fordítási fázisban.

A Retrofit.Builder példány létrehozásakor meg kell adni az alap URL-t és a konverter gyárat. A Builder konfigurálja az OkHttpClient-et — beállítja az időtúllépéseket, elfogókat, kapcsolatpool-t és gyorsítótárat. A create(Class) metódus létrehozza az interfész implementációját, visszaadva egy proxy objektumot, amely úgy hívható, mint egy szokásos osztály.

A kérések végrehajtási lánca a következő: az annotációk kinyerik a HTTP metódust, a paraméterek behelyettesítődnek az URL-be vagy a kérés törzsébe, a konverter szerializálja a törzset, az OkHttp végrehajtja a kérést, a konverter deszerializálja a választ, az eredmény a megadott típusban kerül visszaadásra. Minden szakasz izolált és lecserélhető egyéni implementációra, például az OkHttpClient cseréje MockWebServer-re teszteléshez vagy a konverter cseréje API váltáskor.

Fontos jellemző — a Retrofit nem támogatja közvetlenül az adatfolyamot. A streameléshez az OkHttp ResponseBody-t használják az interfész metódus visszatérési típusaként. A Retrofit szintén nem kezeli automatikusan a kérések megszakítását — a megszakításhoz el kell tárolni a Call referenciáját és meg kell hívni a cancel()-t. Kotlinban a suspend függvényekkel a kérés megszakítása automatikusan megtörténik a szülő korutin megszakításakor.

A Call objektum életciklusa

Call<T> — egy objektum, amely egy HTTP-kérést képvisel. Végrehajtás után (execute vagy enqueue) a Call nem használható újra — ismételt kéréshez új Call-t kell létrehozni az interfész metódus meghívásával. Ez véd az ugyanazon kérés véletlen kétszeri elküldése ellen, ami a műveletek megkettőződéséhez vezethet a szerveren.

Kotlinban a Call helyett suspend függvényeket használnak, amelyek automatikusan kezelik a kérés életciklusát. A Retrofit maga váltja át a végrehajtást a Dispatchers.IO-ra és visszaadja az eredményt a korutinnak. Ez 30–40%-kal lerövidíti a kódot a Call és Callback verzióhoz képest.

Retrofit annotációk HTTP metódusokhoz

Az annotációk — a fő mechanizmus a HTTP-kérések konfigurálásához a Retrofitban. Minden annotáció egy szabványos HTTP metódusnak felel meg, és elfogad egy relatív útvonalat az endpoint-hoz. A Retrofit támogatja a GET, POST, PUT, DELETE, PATCH, HEAD és OPTIONS metódusokat.

A kérés paramétereinek annotációi

@Path behelyettesíti az értéket az URL szegmensbe: @Path(id) Int id helyettesíti a {id}-t az útvonalban. @Query hozzáad egy query paramétert: @Query(page) Int page ?page=5-té alakul. @Body átad egy objektumot a kérés törzsében automatikus szerializációval a kiválasztott konverteren keresztül. @Header és @Headers kezelik a HTTP fejléceket — statikus vagy dinamikus módon.

Ezen annotációk kombinálásával bármely REST endpoint leírható. Például a POST /api/users/{id}/posts?limit=10 endpoint-hoz @POST, @Path az id-hoz, @Query a limit-hez és @Body az átadott objektumhoz szükséges. A Retrofit automatikusan összeállítja a helyes HTTP-kérést. Ezen kívül támogatott a @Url (dinamikus URL), @Field (form-encoded törzs), @Part és @PartMap fájlokkal ellátott multipart kérésekhez.

Retrofit kódpéldák Kotlinban

Vizsgáljunk meg egy gyakorlati példát — egy interfészt a GitHub API-hoz. Létrejön egy Kotlin interfész egy metódussal a repozitóriumok listájának lekérésére. A Data class Repo leírja a JSON válasz szerkezetét.

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>
}

Az interfész leírása után létrejön egy Retrofit példány a Builder-en keresztül. Az alap URL, a konverter és az OkHttpClient egyszer kerül konfigurálásra, és dependency injection-en keresztül használódik újra.

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)

Válasz feldolgozása a Response burkolóval

A HTTP státuszok rugalmas kezeléséhez használja a Response<T> burkolót. Hozzáférést biztosít a válaszkódhoz, fejlécekhez és törzshöz anélkül, hogy kivételt dobna 4xx és 5xx hibák esetén. Ez lehetővé teszi a 404 és 500 kezelését try-catch nélkül.

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", "Hiba: ${response.code()}")
}

Konverterek és szerializáció a Retrofitban

Konverterek — a Retrofit olyan összetevői, amelyek felelősek az objektumok HTTP törzsé alakításáért és vissza. A Retrofit nem építi be a szerializációt a magba — ehelyett moduláris megközelítést használ a Converter.Factory-n keresztül, lehetővé téve bármely szerializációs könyvtár csatlakoztatását.

A legnépszerűbb konverter — a GsonConverterFactory a Google-től a Gson könyvtár alapján. A legtöbb projekt számára alkalmas, támogatja az egyéni TypeAdapter-t és JsonDeserializer-t. A Gson azonban reflexiót használ, és nem veszi figyelembe a Kotlin null safety-jét, ami NPE-hez vezethet váratlan null mezők esetén.

Alternatíva — a MoshiConverterFactory a Square-től: szigorúbb a típusokkal, jobb Kotlin támogatással (null safety, default values) és reflexió nélkül. Tiszta Kotlin projektekhez optimális — a Kotlinx Serialization Converter, amely @Serializable annotációkon működik a fordítási fázisban. Nem használ reflexiót, támogatja a sealed class-t, a default values-t és a többplatformos fejlesztést.

A konverter kiválasztása befolyásolja a teljesítményt és a típusbiztonságot. A Gson egyéni konfiguráció nélkül deszerializálhat null-t egy Kotlin non-null mezőbe, NPE-t okozva a hozzáféréskor. A Moshi ezt a problémát a @Json(name) annotációval és a failOnUnknown-nal oldja meg. A Kotlinx Serialization a legbiztonságosabb — kódot generál a fordítási fázisban, teljesen kiküszöbölve a futásidejű típushibákat.

Gyakori hibák a Retrofit használatakor

A HTTP hibák kezelésének hiánya a suspend függvényekben — a leggyakoribb probléma. Ha a szerver 4xx vagy 5xx kódot ad vissza, a Retrofit HttpException-t dob. Try-catch nélkül az alkalmazás összeomlik. A Response<T> visszatérési típusként való használata megoldja ezt a problémát, lehetővé téve az isSuccessful ellenőrzését a body elérése előtt.

A gyorsítótár helytelen konfigurációja túlzott forgalomhoz vezet. A Retrofit nem gyorsítótárazza a válaszokat magától — ezt a feladatot az OkHttpClient oldja meg a Cache-en keresztül. Gyorsítótár nélkül minden kérés teljes egészében végrehajtódik, még akkor is, ha az adatok nem változtak. Egy 10 MB méretű Cache hozzáadása az OkHttpClient-hez 40–60%-kal csökkenti a forgalmat ismételt kérések esetén.

Retrofit létrehozása minden kéréshez — kezdők gyakori hibája. A Retrofit.Builder erőforrás-igényes művelet, amely proxy osztályok generálását foglalja magában futásidőben. A helyes gyakorlat — egy Retrofit példány létrehozása és újrafelhasználása DI keretrendszereken keresztül. A Hilt, Koin vagy Dagger singleton Retrofit példányt biztosít az egész alkalmazás számára, ami memóriát takarít meg és gyorsítja a kéréseket.

Az Interceptor figyelmen kívül hagyása az autorizációhoz — a negyedik probléma. Ahelyett, hogy manuálisan adná hozzá az Authorization fejlécet minden híváshoz, konfiguráljon egy globális Interceptor-t az OkHttpClient-ben. Az Interceptor elfog minden kérést, hozzáadja a Bearer tokent, az Authenticator pedig feldolgozza a 401-es választ, frissíti a tokent és automatikusan megismétli a kérést. Ez centralizálja a hitelesítési logikát.