Retrofit — mi ez, HTTP-könyvtár és használata alkalmazásokban

Mi az a Retrofit?

Retrofit egy könyvtár HTTP-kérések végrehajtására Android-alkalmazásokban, amelyet a Square cég fejlesztett. Deklaratív megközelítést kínál a REST API-k Java-interfészeken és annotációkon keresztül történő definiálásához, ami a hálózati kommunikációs kódot tisztává és kiszámíthatóvá teszi.

A Retrofit fő gondolata az, hogy a fejlesztő az API-t interfészként írja le metódusokkal és annotációkkal, a könyvtár pedig magától generálja a megvalósítást. Ez a megközelítés garantálja, hogy minden végpont típusos, és az URL-ekben vagy paraméterekben lévő hibák fordítási időben derülnek ki, nem futási időben.

A Retrofit támogatja az összes népszerű HTTP-módszert és adatformátumot. A könyvtárat a Square és a közösség aktívan karbantartja: az új verziók rendszeresen megjelennek, a jelenlegi 2.11-es verzió pedig támogatja a Java 17-et és a Kotlin 2.0-t. A Retrofit továbbra is a legnépszerűbb HTTP-kliens Androidhoz.

A Retrofit az OkHttp tetején működik — egy szintén a Square-től származó hatékony HTTP-kliensen. Ez a kombináció gyorstárazást, kérés-interceptálást és kapcsolatkezelést biztosít a szállítási protokoll szintjén. A könyvtár támogatja a szinkron és aszinkron hívásokat is.

Az első kiadás óta 2013-ban a Retrofit több nagy frissítésen esett át. A jelenlegi Retrofit 2-es verziót teljesen átírták az első verzió tapasztalatait figyelembe véve, és rugalmasabb konverter- és adapterrendszert kínál az aszinkronitáshoz.

A Retrofit architektúrája a felelősségek szétválasztásának elvét követi: az interfész csak az API-szerződést definiálja, a konverterek felelnek a szerializációért, az adapterek pedig az aszinkronitást kezelik. Ez lehetővé teszi bármely összetevő cseréjét a többi kód módosítása nélkül. Például át lehet térni Gson-ról Moshi-ra a végpont-definíciók megváltoztatása nélkül.

A Retrofit fő funkciói

Retrofit olyan funkciókészletet kínál, amely lényegében az összes hálózati kommunikációs forgatókönyvet lefedi a mobilalkalmazásokban. A legfőbb előny az API deklaratív stílusú definiálása.

A végpontok deklaratív annotációi

Annotációk @GET, @POST, @PUT, @PATCH, @DELETE és @HTTP lehetővé teszik a HTTP-módszer és az URL-sablon közvetlenül az interfészben történő definiálását. Az útvonal paraméterei @Path, a lekérdezési paraméterek @Query, a kérés törzse pedig @Body segítségével állítható be. Ez a megközelítés az alkalmazás API-rétegét teljesen típusossá teszi.

Konverterek szerializációhoz

Konverterek alakítják át a HTTP-válaszokat Java-objektumokká és fordítva. A Retrofit támogatja a Gson, Moshi, Jackson, Protobuf és Wire könyvtárakat. A fejlesztő a Converter.Factory segítségével csatlakoztatja a kívánt konvertert, és a könyvtár automatikusan alkalmazza azt minden kérésre és válaszra.

Adapterek aszinkronitáshoz

Adapterek CallAdapter lehetővé teszik az API-metódusok visszatérési típusának megváltoztatását. A szabvány Call helyett használható Observable az RxJava-hoz, Deferred a Kotlin korutinokhoz vagy LiveData. Ez integrálja a hálózati kéréseket a választott alkalmazásarchitektúrával.

Dinamikus URL-ek és fejlécek

Dinamikus URL-ek @Url annotációval állíthatók be, ami lehetővé teszi a végpont futási időben történő átadását. A fejlécek statikusan @Headers vagy dinamikusan @Header paraméterrel adhatók meg. Az összes kérés globális fejléceihez OkHttp-interceptőr használatos, amely minden kimenő kéréshez hozzáadja a fejléceket.

Hogyan működik a Retrofit?

Retrofit három szakaszban működik: az API-interfész definiálása, a Retrofit-példány létrehozása és a kérés végrehajtása. A könyvtár futási időben generálja az interfész megvalósítását az annotációk és konverterek alapján.

A kérés életciklusa

Amikor egy API-metódust meghívnak, a Retrofit létrehoz egy Request objektumot az annotációk és argumentumok alapján. A kérés végrehajtásra az OkHttp felé kerül továbbításra. A válasz beérkezése után a könyvtár a Converter.Factory-ba továbbítja a megfelelő típusra történő átalakításhoz. A CallAdapter aszinkron burkolóba csomagolja az eredményt. Minden szakasz testreszabható.

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)

A Retrofit telepítése és konfigurálása

Telepítés A Retrofit telepítése a Gradle — az Android szabványos építőrendszere — segítségével történik. A könyvtár a Maven Centralen keresztül terjeszthető, és több függőség hozzáadását igényli a projekt build.gradle fájljában.

Függőségek hozzáadása

A build.gradle fájlban (modulszinten) adja hozzá a függőségeket a Retrofit, a Gson konverter és az OkHttp számára. A könyvtárverziókat ajánlott változókba kiemelni a gyökér build.gradle-ben a központosított kezelés érdekében. A Retrofit 2 minimálisan Android API 21-et igényel.

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-példány létrehozása

A Retrofit példánya a Builder segítségével hozható létre. Kötelező paraméterek: baseUrl és ConverterFactory. Ajánlott a singleton mintázat használata a Retrofit és OkHttpClient számára a többletkapcsolatok létrehozásának elkerülése érdekében. A logging-interceptor hozzáadása leegyszerűsíti a hálózati kérések hibakeresését a fejlesztés során.

Kotlin-projektek esetén ajánlott a suspend-függvények használata az API-interfészben a Call típusok helyett. Ez leegyszerűsíti a kódot, és lehetővé teszi a korutinok strukturált konkurenciájának használatát. Call-ról suspend-re váltáskor elég az interfészben megváltoztatni a visszatérési típust — a többi kód automatikusan alkalmazkodik.

Retrofit használati példák

Példák az alábbiakban tipikus forgatókönyveket mutatnak be a Retrofit használatára Android-alkalmazásokban: az egyszerű GET-kéréstől a fájl szerverre történő feltöltéséig.

GET-kérés lekérdezési paraméterekkel

Egy egyszerű GET-kérés lekérdezési paraméterekkel — az alapművelet. A @Query annotáció automatikusan hozzáadja a paramétereket az URL-hez, a suspend-függvény pedig lehetővé teszi a kérés korutinból történő meghívását a főszál blokkolása nélkül.

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-kérés JSON-törzssel

POST-kérés JSON-törzssel a @Body annotációt használja az objektum továbbítására. A GsonConverterFactory automatikusan szerializálja a User objektumot JSON-ba. A Kotlin korutinok biztosítják a kérés háttérszálon történő végrehajtását Callback interfészek nélkül.

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

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

Fájl feltöltése Multipart segítségével

A @Multipart annotáció a @Part segítségével lehetővé teszi fájlok szerverre történő feltöltését. A Retrofit automatikusan létrehozza a multipart kérést a szükséges fejlécekkel. Az OkHttp a RequestBody-n keresztül kezeli a feltöltés előrehaladását, ami lehetővé teszi egy mutató megjelenítését a felhasználó számára.

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)

Hibakezelés és interceptőrök a Retrofitban

Hibakezelés a Retrofitban az OkHttp mechanizmusainak és a Kotlin korutinoknak a kombinációján alapul. Az OkHttp interceptőrök lehetővé teszik a kérések naplózását, hitelesítési fejlécek hozzáadását és a hibák kezelését, mielőtt azok elérnek az alkalmazáskódot.

Központosított hibakezeléshez gyakran hoznak lére burkolót az API-hívások köré sealed class Result formájában. Egy ilyen osztály két alosztályt tartalmaz: Success adatokkal és Error kivétellel. A ViewModel egységesített eredményt kap, és meg tudja jeleníteni a felhasználói felület megfelelő állapotát anélkül, hogy megkettőzné a hibakezelési kódot minden függvényben.

Interceptőrök két típusúak: az alkalmazás-interceptőrök a kérést a szerverre küldés előtt módosítják, a hálózati interceptőrök pedig a válasz beérkezése után dolgoznak. Például egy interceptőr automatikusan frissítheti a hozzáférési tokent 401-es válasz esetén, és megismételheti a kérést az új tokennal a fejlesztő részvétele nélkül.

Kérések naplózása Interceptor segítségével

Naplózó interceptőr HttpLoggingInterceptor — nélkülözhetetlen eszköz a hálózati kérések hibakeresésénél. Megjeleníti a Logcat-ben a kérés módszerét, URL-jét, fejléceit, törzsét és a válasz kódját. A naplózási szint konfigurálható: BASIC minimális információhoz, HEADERS fejlécekhez vagy BODY teljes tartalomhoz. Éles környezetben a BASIC használata vagy a naplózás teljes kikapcsolása ajánlott.

Interceptőrök az OkHttp-ben két típusra oszlanak: alkalmazás-interceptőrök a kérés módosítására és hálózati interceptőrök a nyers hálózati adatokkal való munkához. A naplózó interceptőr automatikusan megjeleníti a kérés és válasz részleteit a Logcat-ben.

Hibakezelés a korutin szintjén try-catch segítségével történik a suspend-függvény hívása körül. A Retrofit hibákat ad vissza HttpException formájában 4xx és 5xx kódokra, UnknownHostException hálózat hiányában és SocketTimeoutException időtúllépés esetén. Egységesített kezeléshez ajánlott a sealed class Result használata.