Alamofire — τι είναι, HTTP-client σε Swift και πώς λειτουργεί

Τι είναι το Alamofire;

Alamofire είναι ένας HTTP πελάτης για Swift, που δημιουργήθηκε από το Alamofire Software Foundation (αρχικά Mattt Thompson το 2014). Η βιβλιοθήκη αφαιρεί τις λεπτομέρειες χαμηλού επιπέδου του URLSession, παρέχοντας ένα καθαρό και εκφραστικό API για επικοινωνία δικτύου.

Η βασική φιλοσοφία του Alamofire είναι η αλυσιδωτή σύνταξη, όπου οι παράμετροι αιτήματος (URL, μέθοδος, κεφαλίδες, παράμετροι, κωδικοποιητής) μεταβιβάζονται μέσω διαδοχικών κλήσεων. Αυτό κάνει τον κώδικα πιο ευανάγνωστο και μειώνει την πιθανότητα σφαλμάτων που σχετίζονται με εσφαλμένη ρύθμιση του URLRequest. Δηλωτική προσέγγιση επιτρέπει την εστίαση στο τι πρέπει να γίνει, όχι στις λεπτομέρειες του πώς να ρυθμιστεί η σύνδεση. Ο προγραμματιστής περιγράφει το επιθυμητό αποτέλεσμα και η βιβλιοθήκη αναλαμβάνει την εργασία χαμηλού επιπέδου με το δίκτυο.

Η βιβλιοθήκη υποστηρίζεται ενεργά από το 2014 και έχει περάσει από επτά κύριες εκδόσεις. Το Alamofire 5, τρέχον για το 2025–2026, περιλαμβάνει υποστήριξη για Combine, async/await, μετατροπείς αποκρίσεων, EventMonitor για εντοπισμό σφαλμάτων και RequestInterceptor για παρεμβολή αιτημάτων. Κάθε κύρια έκδοση έφερε σημαντικές βελτιώσεις: Το Alamofire 4 πρόσθεσε υποστήριξη Codable, το Alamofire 5 — Combine Publishers και βελτιωμένο σύστημα παρεμβολής αιτημάτων.

Το οικοσύστημα Alamofire περιλαμβάνει πρόσθετες βιβλιοθήκες: AlamofireImage για φόρτωση και προσωρινή αποθήκευση εικόνων, AlamofireNetworkActivityIndicator για ένδειξη δικτύου στη γραμμή κατάστασης iOS και AlamofireObjectMapper για ενσωμάτωση με ObjectMapper. Αυτά τα στοιχεία καθιστούν το Alamofire μια πλήρη στοίβα δικτύου, όχι απλώς έναν HTTP πελάτη.

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

Το Alamofire εγκαθίσταται μέσω Swift Package Manager (συνιστάται), CocoaPods ή Carthage. Στο Xcode, απλά ανοίξτε το μενού File → Add Packages, επικολλήστε το URL του αποθετηρίου και καθορίστε την έκδοση.

// Swift Package Manager — πρόσθεσε στο Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Import στο αρχείο
import Alamofire

Μετά την εγκατάσταση, το Alamofire είναι διαθέσιμο παγκοσμίως μέσω του χώρου ονομάτων AF (συντομογραφία του Alamofire) χωρίς πρόσθετη ρύθμιση. Τα περισσότερα έργα ξεκινούν με τη ρύθμιση ενός Session με τη δική του διαμόρφωση — αυτό επιτρέπει τον ορισμό βασικού URL, τυπικών κεφαλίδων, χρονικών ορίων και χειριστών πιστοποιητικών TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

Η δημιουργία δικού σας Session μέσω Session(configuration:) είναι απαραίτητη όταν απαιτείται μοναδική διαμόρφωση για διαφορετικά μέρη της εφαρμογής — για παράδειγμα, ξεχωριστό Session για φόρτωση εικόνων με επιθετική προσωρινή αποθήκευση και ξεχωριστό για αιτήματα API με αυθεντικοποίηση. Το Session του Alamofire δέχεται όχι μόνο τη διαμόρφωση, αλλά και interceptor, serverTrustManager, cachedResponseHandler και redirectHandler, επιτρέποντας πλήρη έλεγχο της συμπεριφοράς δικτύου σε όλα τα στάδια του αιτήματος.

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

Το Alamofire παρέχει ένα ευρύ φάσμα λειτουργιών που καλύπτουν τα περισσότερα σενάρια επικοινωνίας δικτύου σε εφαρμογές iOS. Ας δούμε τα κυριότερα.

Αιτήματα HTTP

Η βασική σύνταξη ενός αιτήματος περιλαμβάνει τη μέθοδο, το URL, τις παραμέτρους και την κωδικοποίηση. Όλες οι τυπικές μέθοδοι HTTP υποστηρίζονται μέσω του enum HTTPMethod: get, post, put, patch, delete. Οι παράμετροι μπορούν να κωδικοποιηθούν ως παράμετροι URL (URLEncoding), σώμα JSON (JSONEncoding) ή μορφή multipart (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("Δημιουργήθηκε χρήστης: \(user)")
        case .failure(let error):
            print("Σφάλμα: \(error)")
        }
    }

Η μέθοδος validate() ελέγχει αυτόματα τον κωδικό κατάστασης (200–299) και τον τύπο περιεχομένου, επιστρέφοντας σφάλμα σε μη τυπική απόκριση, εξαλείφοντας τον μη αυτόματο έλεγχο του statusCode. Το responseDecodable χρησιμοποιεί το πρωτόκολλο Decodable για αυτόματη αποσειριοποίηση JSON σε δομή Swift — εξαλείφει τη μη αυτόματη JSONSerialization και μειώνει τον όγκο του boilerplate κώδικα κατά την εργασία με REST API.

Επεξεργασία αποκρίσεων

Το Alamofire υποστηρίζει διάφορους τύπους χειριστών απόκρισης: response (ακατέργαστα δεδομένα), responseJSON (λεξικό/πίνακας), responseString (κείμενο), responseData (Data) και responseDecodable (μοντέλο Decodable). Μετατροπείς αποκρίσεων μπορούν να δημιουργηθούν προσαρμοσμένοι — για protobuf, γραφικές μορφές ή δικά σας πρωτόκολλα.

Μεταφόρτωση και λήψη αρχείων

Για μεταφόρτωση δεδομένων στον διακομιστή χρησιμοποιείται το upload, που υποστηρίζει Data, File και MultipartFormData. Η λήψη μεγάλων αρχείων γίνεται μέσω download με δυνατότητα συνέχισης μέσω resumeData μετά από διακοπή ή αποσύνδεση. Και οι δύο λειτουργίες υποστηρίζουν παρακολούθηση προόδου μέσω uploadProgress και downloadProgress με κλασματικές τιμές από 0 έως 1 για εμφάνιση στη διεπαφή χρήστη.

Η μεταφόρτωση multipart με Alamofire είναι ιδιαίτερα βολική: η μέθοδος upload(multipartFormData:) δέχεται ένα closure στο οποίο τα μέρη της φόρμας προστίθενται μέσω append. Κάθε μέρος μπορεί να περιέχει δεδομένα, αρχείο ή ροή, καθώς και το δικό του όνομα και τύπο mime. Το Alamofire υπολογίζει αυτόματα τα όρια multipart και ορίζει τη σωστή κεφαλίδα Content-Type, απαλλάσσοντας τον προγραμματιστή από τη μη αυτόματη δημιουργία του σώματος αιτήματος. Για μεγάλα αρχεία, συνιστάται η χρήση μετάδοσης ροής (stream provider) αντί της φόρτωσης ολόκληρου του αρχείου στη μνήμη — αυτό αποτρέπει την υπέρβαση του ορίου μνήμης σε κινητές συσκευές με περιορισμένους πόρους. Ένα τυπικό σενάριο — αποστολή του avatar του χρήστη μαζί με δεδομένα προφίλ σε ένα αίτημα multipart, που μειώνει τον αριθμό κλήσεων HTTP και απλοποιεί την επεξεργασία στον διακομιστή.

Alamofire vs URLSession

Η σύγκριση του Alamofire και του εγγενούς URLSession βοηθά στη λήψη αρχιτεκτονικών αποφάσεων. Το Alamofire δεν αντικαθιστά το URLSession — είναι χτισμένο πάνω του και χρησιμοποιεί τους ίδιους μηχανισμούς διαμόρφωσης, προσωρινής αποθήκευσης και εργασιών παρασκηνίου. Όλες οι λειτουργίες του URLSession είναι διαθέσιμες μέσω Alamofire, αλλά με πιο βολική δηλωτική σύνταξη.

Σε μεγάλα έργα, το Alamofire μειώνει τον όγκο κώδικα για αιτήματα δικτύου κατά 30–50% και απλοποιεί τον χειρισμό σφαλμάτων. Σε μικρά έργα ή με αυστηρές απαιτήσεις για το μέγεθος του δυαδικού αρχείου, το εγγενές URLSession είναι προτιμότερο λόγω απουσίας εξωτερικών εξαρτήσεων.

Το σύγχρονο Alamofire 5 ενσωματώνεται με το Combine μέσω της ιδιότητας publishDecodable, η οποία επιστρέφει ένα Publisher, επιτρέποντας τη δημιουργία αντιδραστικών αλυσίδων αιτημάτων με χειρισμό σφαλμάτων και μετασχηματισμό δεδομένων. Για async/await είναι διαθέσιμες μέθοδοι με κατάληξη value — για παράδειγμα, AF.request(url).serializingDecodable(User.self).value, που κάνει τη σύνταξη εξαιρετικά συνοπτική και θυμίζει εργασία με εγγενές URLSession. Κατά τη χρήση async/await, εξαλείφεται η ανάγκη για closures και ο χειρισμός σφαλμάτων γίνεται μέσω τυπικών μπλοκ do-catch της Swift, απλοποιώντας τη συντήρηση κώδικα και την αναγνωσιμότητά του μακροπρόθεσμα.

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

Ας δούμε ένα πιο σύνθετο παράδειγμα — ένα αίτημα με ενδιάμεσο λογισμικό που προσθέτει αυτόματα διακριτικό εξουσιοδότησης και επαναλαμβάνει την προσπάθεια σε σφάλμα 401. Αυτό είναι ένα τυπικό σενάριο για εφαρμογές με αυθεντικοποίηση JWT.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

Ο ενδιάμεσος λογισμικού AuthInterceptor υλοποιεί δύο πρωτόκολλα: adapt (προσθέτει διακριτικό σε κάθε αίτημα) και retry (προσπαθεί να ανανεώσει το διακριτικό σε σφάλμα 401). Η μέθοδος retry ελέγχει τον κωδικό κατάστασης της απόκρισης και, εάν ληφθεί 401, ζητά νέο διακριτικό μέσω TokenManager. Μετά την επιτυχή ανανέωση, το αίτημα επαναλαμβάνεται αυτόματα.

Χρήση του ενδιάμεσου λογισμικού με Session:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

Όλα τα αιτήματα μέσω αυτού του Session περνούν αυτόματα από το AuthInterceptor — το διακριτικό προστίθεται στις κεφαλίδες και σε 401 γίνεται ανανέωση και επανάληψη. Αυτό εξαλείφει την αντιγραφή κώδικα αυθεντικοποίησης σε κάθε αίτημα και συγκεντρώνει τη λογική εργασίας με διακριτικά.