Retrofit — τι είναι, HTTP-βιβλιοθήκη και χρήση σε εφαρμογές

Τι είναι το Retrofit;

Retrofit είναι μια βιβλιοθήκη για την εκτέλεση HTTP αιτημάτων σε εφαρμογές Android, που αναπτύχθηκε από την εταιρεία Square. Παρέχει μια δηλωτική προσέγγιση για τον ορισμό REST API μέσω Java διεπαφών με σχολιασμούς, καθιστώντας τον κώδικα επικοινωνίας δικτύου καθαρό και προβλέψιμο.

Η κύρια ιδέα του Retrofit είναι ότι ο προγραμματιστής περιγράφει το API ως διεπαφή με μεθόδους και σχολιασμούς, και η βιβλιοθήκη δημιουργεί μόνη της την υλοποίηση. Αυτή η προσέγγιση εγγυάται ότι όλα τα endpoints είναι τυποποιημένα και τα σφάλματα σε URL ή παραμέτρους εντοπίζονται κατά τη μεταγλώττιση, όχι κατά την εκτέλεση.

Το Retrofit υποστηρίζει όλες τις δημοφιλείς HTTP μεθόδους και μορφές δεδομένων. Η βιβλιοθήκη συντηρείται ενεργά από την Square και την κοινότητα: νέες εκδόσεις κυκλοφορούν τακτικά και η τρέχουσα έκδοση 2.11 περιλαμβάνει υποστήριξη για Java 17 και Kotlin 2.0. Το Retrofit παραμένει ο πιο δημοφιλής HTTP-client για Android.

Το Retrofit λειτουργεί πάνω από το OkHttp — έναν αποδοτικό HTTP-client επίσης από την Square. Αυτός ο συνδυασμός παρέχει προσωρινή αποθήκευση, παρεμβολή αιτημάτων και διαχείριση συνδέσεων στο επίπεδο του πρωτοκόλλου μεταφοράς. Η βιβλιοθήκη υποστηρίζει τόσο σύγχρονες όσο και ασύγχρονες κλήσεις.

Από την πρώτη κυκλοφορία το 2013, το Retrofit έχει υποστεί αρκετές μεγάλες ενημερώσεις. Η τρέχουσα έκδοση Retrofit 2 έχει ξαναγραφτεί πλήρως λαμβάνοντας υπόψη την εμπειρία από την πρώτη έκδοση και προσφέρει ένα πιο ευέλικτο σύστημα μετατροπέων και προσαρμογέων για ασυγχρονισμό.

Η αρχιτεκτονική του Retrofit ακολουθεί την αρχή του διαχωρισμού ευθυνών: η διεπαφή ορίζει μόνο τη σύμβαση API, οι μετατροπείς είναι υπεύθυνοι για τη σειριοποίηση και οι προσαρμογείς διαχειρίζονται τον ασυγχρονισμό. Αυτό επιτρέπει την αντικατάσταση οποιουδήποτε στοιχείου χωρίς αλλαγή του υπόλοιπου κώδικα. Για παράδειγμα, μπορεί κανείς να μεταβεί από Gson σε Moshi χωρίς να αλλάξει τους ορισμούς των endpoints.

Βασικές δυνατότητες του Retrofit

Retrofit παρέχει ένα σύνολο λειτουργιών που καλύπτουν ουσιαστικά όλα τα σενάρια επικοινωνίας δικτύου σε κινητές εφαρμογές. Το βασικό πλεονέκτημα είναι το δηλωτικό στυλ ορισμού του API.

Δηλωτικοί σχολιασμοί endpoints

Σχολιασμοί @GET, @POST, @PUT, @PATCH, @DELETE και @HTTP επιτρέπουν τον ορισμό της HTTP μεθόδου και του προτύπου URL απευθείας στη διεπαφή. Οι παράμετροι διαδρομής ορίζονται μέσω @Path, οι παράμετροι ερωτήματος μέσω @Query και το σώμα αιτήματος μέσω @Body. Αυτή η προσέγγιση καθιστά το επίπεδο API της εφαρμογής πλήρως τυποποιημένο.

Μετατροπείς για σειριοποίηση

Μετατροπείς μετατρέπουν τις HTTP απαντήσεις σε Java αντικείμενα και αντίστροφα. Το Retrofit υποστηρίζει Gson, Moshi, Jackson, Protobuf και Wire. Ο προγραμματιστής συνδέει τον επιθυμητό μετατροπέα μέσω Converter.Factory και η βιβλιοθήκη τον εφαρμόζει αυτόματα σε όλα τα αιτήματα και τις απαντήσεις.

Προσαρμογείς για ασυγχρονισμό

Προσαρμογείς CallAdapter επιτρέπουν την αλλαγή του τύπου επιστροφής των μεθόδων API. Αντί για το τυπικό Call, μπορεί να χρησιμοποιηθεί Observable για RxJava, Deferred για coroutines Kotlin ή LiveData. Αυτό ενσωματώνει τα αιτήματα δικτύου με την επιλεγμένη αρχιτεκτονική εφαρμογής.

Δυναμικά URL και κεφαλίδες

Δυναμικά URL ορίζονται μέσω του σχολιασμού @Url, επιτρέποντας τη μετάδοση του endpoint κατά την εκτέλεση. Οι κεφαλίδες μπορούν να καθοριστούν στατικά μέσω @Headers ή δυναμικά μέσω της παραμέτρου @Header. Για καθολικές κεφαλίδες όλων των αιτημάτων χρησιμοποιείται ένας παρεμβολέας OkHttp που προσθέτει κεφαλίδες σε κάθε εξερχόμενο αίτημα.

Πώς λειτουργεί το Retrofit;

Retrofit λειτουργεί σε τρία στάδια: ορισμός της διεπαφής API, δημιουργία του στιγμιότυπου Retrofit και εκτέλεση του αιτήματος. Η βιβλιοθήκη δημιουργεί την υλοποίηση της διεπαφής κατά την εκτέλεση βάσει σχολιασμών και μετατροπέων.

Κύκλος ζωής αιτήματος

Όταν καλείται μια μέθοδος API, το Retrofit δημιουργεί ένα αντικείμενο Request βάσει σχολιασμών και ορισμάτων. Το αίτημα μεταβιβάζεται στο OkHttp για εκτέλεση. Μετά τη λήψη της απάντησης, η βιβλιοθήκη τη στέλνει στο Converter.Factory για μετατροπή στον απαιτούμενο τύπο. Ο CallAdapter τυλίγει το αποτέλεσμα σε ένα ασύγχρονο περιτύλιγμα. Κάθε στάδιο μπορεί να προσαρμοστεί.

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)

Εγκατάσταση και ρύθμιση του Retrofit

Εγκατάσταση του Retrofit γίνεται μέσω Gradle — του τυπικού συστήματος δόμησης Android. Η βιβλιοθήκη διανέμεται μέσω του Maven Central και απαιτεί την προσθήκη πολλών εξαρτήσεων στο build.gradle του έργου.

Προσθήκη εξαρτήσεων

Στο αρχείο build.gradle (επίπεδο ενότητας) προσθέστε εξαρτήσεις για Retrofit, τον μετατροπέα Gson και το OkHttp. Οι εκδόσεις βιβλιοθηκών συνιστάται να τοποθετούνται σε μεταβλητές στο root build.gradle για κεντρική διαχείριση. Το Retrofit 2 απαιτεί τουλάχιστον 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"
}

Δημιουργία στιγμιότυπου Retrofit

Το στιγμιότυπο Retrofit δημιουργείται μέσω Builder. Υποχρεωτικές παράμετροι: baseUrl και ConverterFactory. Συνιστάται η χρήση singleton για Retrofit και OkHttpClient για αποφυγή δημιουργίας περιττών συνδέσεων. Η προσθήκη logging-interceptor απλοποιεί τον εντοπισμό σφαλμάτων αιτημάτων δικτύου κατά την ανάπτυξη.

Για έργα Kotlin συνιστάται η χρήση συναρτήσεων suspend στη διεπαφή API αντί για τύπους Call. Αυτό απλοποιεί τον κώδικα και επιτρέπει τη χρήση δομημένης ταυτοχρονίας των coroutines. Κατά τη μετάβαση από Call σε suspend αρκεί να αλλάξετε τον τύπο επιστροφής στη διεπαφή — ο υπόλοιπος κώδικας προσαρμόζεται αυτόματα.

Παραδείγματα χρήσης του Retrofit

Παραδείγματα παρακάτω δείχνουν τυπικά σενάρια εργασίας με το Retrofit σε εφαρμογές Android: από ένα απλό αίτημα GET έως τη μεταφόρτωση αρχείου στον διακομιστή.

Αίτημα GET με παραμέτρους ερωτήματος

Ένα απλό αίτημα GET με παραμέτρους συμβολοσειράς ερωτήματος — η βασική λειτουργία. Ο σχολιασμός @Query προσθέτει αυτόματα παραμέτρους στο URL και η συνάρτηση suspend επιτρέπει την κλήση του αιτήματος από ένα coroutine χωρίς αποκλεισμό του κύριου νήματος.

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 με σώμα JSON

Αίτημα POST με σώμα JSON χρησιμοποιεί τον σχολιασμό @Body για τη μετάδοση του αντικειμένου. Το GsonConverterFactory σειριοποιεί αυτόματα το αντικείμενο User σε JSON. Τα coroutines Kotlin εξασφαλίζουν την εκτέλεση του αιτήματος στο παρασκήνιο χωρίς διεπαφές Callback.

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

val user = User(name = "Άννα Ιβάνοβα", email = "anna@example.com")
val created = api.createUser(user)

Μεταφόρτωση αρχείου μέσω Multipart

Ο σχολιασμός @Multipart με @Part επιτρέπει τη μεταφόρτωση αρχείων στον διακομιστή. Το Retrofit δημιουργεί αυτόματα ένα αίτημα multipart με τις απαραίτητες κεφαλίδες. Το OkHttp διαχειρίζεται την πρόοδο μεταφόρτωσης μέσω RequestBody, επιτρέποντας την εμφάνιση δείκτη προόδου στον χρήστη.

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)

Διαχείριση σφαλμάτων και παρεμβολείς στο Retrofit

Διαχείριση σφαλμάτων στο Retrofit βασίζεται σε συνδυασμό μηχανισμών OkHttp και coroutines Kotlin. Οι παρεμβολείς OkHttp επιτρέπουν την καταγραφή αιτημάτων, την προσθήκη κεφαλίδων ταυτοποίησης και τη διαχείριση σφαλμάτων πριν φτάσουν στον κώδικα εφαρμογής.

Για κεντρική διαχείριση σφαλμάτων συχνά δημιουργείται ένα περιτύλιγμα γύρω από κλήσεις API με τη μορφή sealed class Result. Μια τέτοια κλάση περιέχει δύο υποκλάσεις: Success με δεδομένα και Error με εξαίρεση. Το ViewModel λαμβάνει ένα ενοποιημένο αποτέλεσμα και μπορεί να εμφανίσει την αντίστοιχη κατάσταση διεπαφής χρήστη χωρίς διπλασιασμό κώδικα διαχείρισης σφαλμάτων σε κάθε συνάρτηση.

Παρεμβολείς Interceptor είναι δύο τύπων: παρεμβολείς εφαρμογής τροποποιούν το αίτημα πριν από την αποστολή στον διακομιστή και παρεμβολείς δικτύου λειτουργούν με την απάντηση μετά τη λήψη. Για παράδειγμα, ένας παρεμβολέας μπορεί να ανανεώνει αυτόματα το διακριτικό πρόσβασης όταν λαμβάνει 401 και να επαναλαμβάνει το αίτημα με το νέο διακριτικό χωρίς τη συμμετοχή του προγραμματιστή.

Καταγραφή αιτημάτων μέσω Interceptor

Παρεμβολέας καταγραφής HttpLoggingInterceptor — απαραίτητο εργαλείο για τον εντοπισμό σφαλμάτων αιτημάτων δικτύου. Εμφανίζει στο Logcat τη μέθοδο αιτήματος, URL, κεφαλίδες, σώμα και κωδικό απάντησης. Το επίπεδο καταγραφής μπορεί να ρυθμιστεί: BASIC για ελάχιστες πληροφορίες, HEADERS για κεφαλίδες ή BODY για πλήρες περιεχόμενο. Στην παραγωγή συνιστάται η χρήση BASIC ή η πλήρης απενεργοποίηση της καταγραφής.

Παρεμβολείς Interceptor στο OkHttp χωρίζονται σε δύο τύπους: παρεμβολείς εφαρμογής για τροποποίηση αιτήματος και παρεμβολείς δικτύου για εργασία με ακατέργαστα δεδομένα δικτύου. Ο παρεμβολέας καταγραφής εμφανίζει αυτόματα λεπτομέρειες αιτήματος και απάντησης στο Logcat.

Διαχείριση σφαλμάτων σε επίπεδο coroutine γίνεται μέσω try-catch γύρω από την κλήση της συνάρτησης suspend. Το Retrofit επιστρέφει σφάλματα ως HttpException για κωδικούς 4xx και 5xx, UnknownHostException όταν δεν υπάρχει δίκτυο και SocketTimeoutException όταν γίνεται υπέρβαση χρονικού ορίου. Συνιστάται η χρήση sealed class Result για ενοποιημένη διαχείριση.