Retrofit: τι είναι, χαρακτηριστικά του HTTP πελάτη Android

Τι είναι το Retrofit;

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

Η βιβλιοθήκη εμφανίστηκε το 2013 ως εναλλακτική λύση σε ογκώδεις λύσεις όπως το AsyncTask και το HttpURLConnection. Μέχρι το 2025, το Retrofit παραμένει το de facto πρότυπο για δικτυακή επικοινωνία σε εφαρμογές Android χάρη στην απλότητα και ασφάλεια τύπων. Σύμφωνα με έρευνα του JetBrains Developer Ecosystem 2024, το Retrofit χρησιμοποιείται από περισσότερο από το 65% των προγραμματιστών Android σε εμπορικά έργα.

Η βασική διαφορά του Retrofit από τα ανάλογα — η δηλωτική προσέγγιση: ο προγραμματιστής περιγράφει τι να κάνει (ποιο endpoint να καλέσει, ποιες παραμέτρους να μεταδώσει), όχι πώς να το κάνει (πώς να ανοίξει τη σύνδεση, πώς να διαβάσει το InputStream, πώς να αναλύσει το JSON). Αυτό μειώνει την ποσότητα του boilerplate κώδικα κατά 60–70% σε σύγκριση με τη χειροκίνητη χρήση του HttpURLConnection.

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

Αρχή λειτουργίας του Retrofit βασίζεται σε δυναμικά proxy Java. Όταν ο προγραμματιστής καλεί μια μέθοδο διεπαφής με σχολιασμούς, το Retrofit μέσω του μηχανισμού Proxy.newProxyInstance υποκλέπτει την κλήση και τη μετατρέπει σε HTTP αίτημα. Ολόκληρη η διαδικασία συμβαίνει κατά τον χρόνο εκτέλεσης χωρίς δημιουργία κώδικα στο στάδιο μεταγλώττισης.

Κατά τη δημιουργία μιας παρουσίας Retrofit.Builder, καθορίζεται το βασικό URL και το εργοστάσιο μετατροπέων. Ο Builder ρυθμίζει το OkHttpClient — ορίζει χρονικά όρια, παρεμβολείς, ομάδα συνδέσεων και προσωρινή μνήμη. Η μέθοδος create(Class) δημιουργεί την υλοποίηση της διεπαφής, επιστρέφοντας ένα αντικείμενο proxy που μπορεί να κληθεί όπως μια κανονική κλάση.

Η αλυσίδα εκτέλεσης ενός αιτήματος έχει ως εξής: οι σχολιασμοί εξάγουν τη μέθοδο HTTP, οι παράμετροι εισάγονται στο URL ή στο σώμα του αιτήματος, ο μετατροπέας σειριοποιεί το σώμα, το OkHttp εκτελεί το αίτημα, ο μετατροπέας αποσειριοποιεί την απάντηση, το αποτέλεσμα επιστρέφεται στον καθορισμένο τύπο. Κάθε στάδιο είναι απομονωμένο και μπορεί να αντικατασταθεί με προσαρμοσμένη υλοποίηση, για παράδειγμα αντικατάσταση του OkHttpClient με MockWebServer για δοκιμές ή αλλαγή μετατροπέα κατά την αλλαγή API.

Σημαντικό χαρακτηριστικό — το Retrofit δεν υποστηρίζει άμεσα ροή δεδομένων. Για ροή, χρησιμοποιείται το OkHttp ResponseBody ως τύπος επιστροφής της μεθόδου διεπαφής. Το Retrofit επίσης δεν διαχειρίζεται αυτόματα την ακύρωση αιτημάτων — για ακύρωση πρέπει να αποθηκευτεί μια αναφορά στο Call και να κληθεί η cancel(). Στο Kotlin με συναρτήσεις suspend, η ακύρωση του αιτήματος γίνεται αυτόματα κατά την ακύρωση του γονικού coroutine.

Κύκλος ζωής του αντικειμένου Call

Call<T> — είναι ένα αντικείμενο που αντιπροσωπεύει ένα HTTP αίτημα. Μετά την εκτέλεση (execute ή enqueue), το Call δεν μπορεί να επαναχρησιμοποιηθεί — για επαναλαμβανόμενο αίτημα πρέπει να δημιουργηθεί νέο Call μέσω κλήσης της μεθόδου διεπαφής. Αυτό προστατεύει από τυχαία αποστολή του ίδιου αιτήματος δύο φορές, που θα μπορούσε να οδηγήσει σε διπλασιασμό λειτουργιών στον διακομιστή.

Στο Kotlin, αντί για Call, χρησιμοποιούνται συναρτήσεις suspend που διαχειρίζονται αυτόματα τον κύκλο ζωής του αιτήματος. Το Retrofit το ίδιο μεταφέρει την εκτέλεση στο Dispatchers.IO και επιστρέφει το αποτέλεσμα στο coroutine. Αυτό συντομεύει τον κώδικα κατά 30–40% σε σύγκριση με την έκδοση σε Call και Callback.

Σχολιασμοί Retrofit για HTTP μεθόδους

Οι σχολιασμοί — είναι ο κύριος μηχανισμός ρύθμισης HTTP αιτημάτων στο Retrofit. Κάθε σχολιασμός αντιστοιχεί σε μια τυπική HTTP μέθοδο και δέχεται μια σχετική διαδρομή προς το endpoint. Το Retrofit υποστηρίζει GET, POST, PUT, DELETE, PATCH, HEAD και OPTIONS.

Σχολιασμοί παραμέτρων αιτήματος

@Path αντικαθιστά την τιμή στο τμήμα URL: @Path(id) Int id αντικαθιστά το {id} στη διαδρομή. @Query προσθέτει μια παράμετρο ερωτήματος: @Query(page) Int page μετατρέπεται σε ?page=5. @Body μεταδίδει ένα αντικείμενο στο σώμα του αιτήματος με αυτόματη σειριοποίηση μέσω του επιλεγμένου μετατροπέα. @Header και @Headers διαχειρίζονται τις HTTP κεφαλίδες — στατικές ή δυναμικές.

Συνδυάζοντας αυτούς τους σχολιασμούς, μπορεί να περιγραφεί οποιοδήποτε REST endpoint. Για παράδειγμα, για το endpoint POST /api/users/{id}/posts?limit=10 θα χρειαστούν @POST, @Path για το id, @Query για το limit και @Body για το αντικείμενο που μεταδίδεται. Το Retrofit θα συναρμολογήσει αυτόματα το σωστό HTTP αίτημα. Επιπλέον, υποστηρίζονται @Url (δυναμικό URL), @Field (σώμα form-encoded), @Part και @PartMap για multipart αιτήματα με αρχεία.

Παραδείγματα κώδικα Retrofit σε Kotlin

Ας εξετάσουμε ένα πρακτικό παράδειγμα — μια διεπαφή για το GitHub API. Δημιουργείται μια διεπαφή Kotlin με μια μέθοδο λήψης λίστας αποθετηρίων. Η Data class Repo περιγράφει τη δομή της απάντησης JSON.

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

Μετά την περιγραφή της διεπαφής, δημιουργείται μια παρουσία Retrofit μέσω Builder. Το βασικό URL, ο μετατροπέας και το OkHttpClient ρυθμίζονται μία φορά και επαναχρησιμοποιούνται μέσω έγχυσης εξαρτήσεων.

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)

Επεξεργασία απάντησης με το περιτύλιγμα Response

Για ευέλικτη επεξεργασία HTTP καταστάσεων χρησιμοποιήστε το περιτύλιγμα Response<T>. Παρέχει πρόσβαση στον κωδικό απάντησης, κεφαλίδες και σώμα, χωρίς να πετάει εξαίρεση σε σφάλματα 4xx και 5xx. Αυτό επιτρέπει την επεξεργασία 404 και 500 χωρίς 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", "Σφάλμα: ${response.code()}")
}

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

Μετατροπείς — είναι συστατικά του Retrofit υπεύθυνα για τη μετατροπή αντικειμένων σε HTTP σώμα και αντίστροφα. Το Retrofit δεν ενσωματώνει σειριοποίηση στον πυρήνα — αντίθετα, χρησιμοποιείται αρθρωτή προσέγγιση μέσω του Converter.Factory, επιτρέποντας τη σύνδεση οποιασδήποτε βιβλιοθήκης σειριοποίησης.

Ο πιο δημοφιλής μετατροπέας — GsonConverterFactory από την Google βασισμένος στη βιβλιοθήκη Gson. Είναι κατάλληλος για τα περισσότερα έργα, υποστηρίζει προσαρμοσμένους TypeAdapter και JsonDeserializer. Ωστόσο, το Gson χρησιμοποιει αντανάκλαση και δεν λαμβάνει υπόψη το null safety του Kotlin, που μπορεί να οδηγήσει σε NPE σε απροσδόκητα null πεδία.

Εναλλακτική — MoshiConverterFactory από την Square: πιο αυστηρό με τους τύπους, με καλύτερη υποστήριξη Kotlin (null safety, default values) και χωρίς αντανάκλαση. Για έργα σε καθαρό Kotlin, βέλτιστος είναι Kotlinx Serialization Converter, που λειτουργεί με σχολιασμούς @Serializable στο στάδιο μεταγλώττισης. Δεν χρησιμοποιεί αντανάκλαση, υποστηρίζει sealed class, default values και πολλαπλές πλατφόρμες.

Η επιλογή μετατροπέα επηρεάζει την απόδοση και την ασφάλεια τύπων. Το Gson χωρίς προσαρμοσμένη ρύθμιση μπορεί να αποσειριοποιήσει null σε πεδίο non-null Kotlin, προκαλώντας NPE κατά την πρόσβαση. Το Moshi λύνει αυτό το πρόβλημα μέσω του σχολιασμού @Json(name) και failOnUnknown. Το Kotlinx Serialization είναι το ασφαλέστερο — δημιουργεί κώδικα στο στάδιο μεταγλώττισης, εξαλείφοντας πλήρως τα σφάλματα τύπων κατά τον χρόνο εκτέλεσης.

Συνήθη λάθη κατά την εργασία με το Retrofit

Έλλειψη χειρισμού σφαλμάτων HTTP σε συναρτήσεις suspend — το πιο συνηθισμένο πρόβλημα. Αν ο διακομιστής επιστρέψει 4xx ή 5xx, το Retrofit πετάει HttpException. Χωρίς try-catch, η εφαρμογή θα καταρρεύσει. Η χρήση του Response<T> ως τύπου επιστροφής λύνει αυτό το πρόβλημα, επιτρέποντας τον έλεγχο isSuccessful πριν από την πρόσβαση στο body.

Λανθασμένη ρύθμιση προσωρινής μνήμης οδηγεί σε υπερβολική κίνηση. Το Retrofit δεν αποθηκεύει προσωρινά απαντήσεις μόνο του — αυτό το έργο το λύνει το OkHttpClient μέσω Cache. Χωρίς προσωρινή μνήμη, κάθε αίτημα εκτελείται πλήρως, ακόμα κι όταν τα δεδομένα δεν έχουν αλλάξει. Η προσθήκη Cache μεγέθους 10 MB στο OkHttpClient μειώνει την κίνηση κατά 40–60% σε επαναλαμβανόμενα αιτήματα των ίδιων πληροφοριών.

Δημιουργία Retrofit για κάθε αίτημα — συχνό λάθος αρχαρίων. Το Retrofit.Builder είναι μια λειτουργία έντασης πόρων που περιλαμβάνει δημιουργία proxy κλάσεων κατά τον χρόνο εκτέλεσης. Η σωστή πρακτική — δημιουργία μιας παρουσίας Retrofit και επαναχρησιμοποίησή της μέσω DI πλαισίων. Hilt, Koin ή Dagger παρέχουν μια singleton παρουσία Retrofit για ολόκληρη την εφαρμογή, εξοικονομώντας μνήμη και επιταχύνοντας τα αιτήματα.

Παράβλεψη του Interceptor για εξουσιοδότηση — το τέταρτο πρόβλημα. Αντί να προσθέτετε χειροκίνητα την κεφαλίδα Authorization σε κάθε κλήση, ρυθμίστε έναν καθολικό Interceptor στο OkHttpClient. Ο Interceptor υποκλέπτει κάθε αίτημα, προσθέτει το διακριτικό Bearer, και ο Authenticator επεξεργάζεται την απάντηση 401, ανανεώνοντας το διακριτικό και επαναλαμβάνοντας το αίτημα αυτόματα. Αυτό συγκεντρώνει τη λογική ταυτοποίησης.