Dio: τι είναι, χαρακτηριστικά του HTTP client για Flutter

Τι είναι το Dio;

Dio — είναι μια ισχυρή βιβλιοθήκη HTTP client για τη γλώσσα Dart, που χρησιμοποιείται ευρύτερα σε εφαρμογές Flutter. Το Dio παρέχει πλούσιο API με υποστήριξη για interceptors, καθολική διαμόρφωση, transformers, FormData, μεταφόρτωση αρχείων και ευέλικτη διαχείριση χρονικών ορίων, καθιστώντας το την κύρια επιλογή για δικτυακή επικοινωνία στην κοινότητα Flutter.

Η βιβλιοθήκη δημιουργήθηκε από τον Wenda Wang το 2018 ως εναλλακτική λύση στον ενσωματωμένο dart:io HttpClient, ο οποίος δεν είχε πολλές σύγχρονες δυνατότητες: ενοποιημένη διαμόρφωση για όλα τα αιτήματα, interceptors και αυτόματη σειριοποίηση. Μέχρι το 2025, το Dio ξεπέρασε σε δημοτικότητα το πακέτο http της ομάδας Dart, καταλαμβάνοντας την πρώτη θέση μεταξύ των HTTP clients στο οικοσύστημα Flutter σύμφωνα με τα δεδομένα του pub.dev.

Το Dio υποστηρίζει τρεις προσαρμογείς: DartNativeAdapter (προεπιλογή σε Android, iOS, Desktop), BrowserAdapter (στο Web) και IOAdapter. Ο προσαρμογέας επιλέγεται αυτόματα ανάλογα με την πλατφόρμα. Το Dio παρέχει επίσης ενοποιημένη διεπαφή για όλες τις πλατφόρμες Flutter — Android, iOS, Web, macOS, Windows και Linux.

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

Η αρχιτεκτονική του Dio βασίζεται σε μια αλυσίδα χειριστών (handler chain). Κάθε αίτημα περνά από μια ακολουθία interceptors που μπορούν να τροποποιήσουν το αίτημα (InterceptorsWrapper.onRequest), την απάντηση (onResponse) ή να χειριστούν το σφάλμα (onError). Μετά τους interceptors, το αίτημα φτάνει στους transformers (Transformer) που μετασχηματίζουν τα δεδομένα πριν από την αποστολή.

Το στιγμιότυπο του Dio διαμορφώνεται μέσω του αντικειμένου BaseOptions που περιέχει το βασικό URL, προεπιλεγμένες κεφαλίδες, χρονικά όρια, τύπο απάντησης (JSON, stream, plain), παραμέτρους ερωτήματος και μορφή δεδομένων. Αυτές οι ρυθμίσεις εφαρμόζονται σε όλα τα αιτήματα, αλλά μπορούν να παρακαμφθούν σε ένα συγκεκριμένο αίτημα. Το BaseOptions παρέχει ένα ενοποιημένο σημείο διαμόρφωσης για ολόκληρη την εφαρμογή, απλοποιώντας την αλλαγή τελικού σημείου API ή την προσθήκη καθολικών κεφαλίδων.

Κάθε αίτημα στο Dio επιστρέφει Response<T>, όπου T — είναι ο τύπος δεδομένων μετά την επεξεργασία από τους transformers. Από προεπιλογή, το Dio μετατρέπει αυτόματα την απάντηση JSON σε Map<String, dynamic>. Για τυποποιημένες απαντήσεις, το Dio χρησιμοποιείται μαζί με πακέτα σειριοποίησης: json_serializable, freezed ή built_value. Το Response περιέχει data, headers, statusCode, requestOptions και πρόσθετα δεδομένα.

Καθολική διαμόρφωση του Dio

Βασική διαμόρφωση δημιουργείται μέσω του Dio(BaseOptions). Μπορείτε να ορίσετε baseUrl για όλα τα αιτήματα, connectTimeout και receiveTimeout, κεφαλίδες content-type και accept, καθώς και queryParameters. Όλες αυτές οι παράμετροι εφαρμόζονται σε κάθε αίτημα, εξαλείφοντας την επανάληψη κώδικα και συγκεντρώνοντας τη διαχείριση των ρυθμίσεων δικτύου.

Το Dio υποστηρίζει δύο λειτουργίες σειριοποίησης: προεπιλεγμένη JSON (responseType: ResponseType.json) και ροής (ResponseType.stream). Στη λειτουργία ροής, το Response.data επιστρέφει ένα ResponseBody που μπορεί να διαβαστεί τμηματικά. Αυτό είναι βολικό για μεγάλα αρχεία φορτίου, όταν η πλήρης φόρτωση στη μνήμη δεν είναι επιθυμητή. Η λειτουργία plain επιστρέφει ανεπεξέργαστη συμβολοσειρά χωρίς αυτόματη ανάλυση JSON.

Interceptors του Dio

Οι interceptors — βασικός μηχανισμός του Dio για υποκλοπή και τροποποίηση αιτημάτων, απαντήσεων και σφαλμάτων. Αντικαθιστούν πλήρως τον Interceptor από το OkHttp και τα πρόσθετα από το Ktor, αλλά με API ειδικό για Dart και υποστήριξη ασύγχρονης λειτουργίας μέσω Future. Οι interceptors μπορούν να προστεθούν τόσο στην καθολική διαμόρφωση του Dio όσο και για μεμονωμένα αιτήματα.

LogInterceptor

Ο ενσωματωμένος LogInterceptor καταγράφει κάθε αίτημα: μέθοδο, URL, κεφαλίδες, σώμα και χρόνο εκτέλεσης. Έχει δύο λειτουργίες: compact (μία γραμμή ανά αίτημα) και full (πλήρεις πληροφορίες με σώμα). Ο LogInterceptor είναι ιδιαίτερα χρήσιμος κατά την ανάπτυξη, αλλά συνιστάται η απενεργοποίησή του σε εκδόσεις release μέσω υπό όρους εισαγωγής ή καθολικής σημαίας.

Προσαρμοσμένοι interceptors δημιουργούνται μέσω της κλάσης InterceptorsWrapper. Μπορείτε να παρακάμψετε μία, δύο ή και τις τρεις μεθόδους (onRequest, onResponse, onError). Το Dio εκτελεί τους interceptors αυστηρά με τη σειρά προσθήκης τους στη λίστα interceptors. Εάν ένας interceptor δεν καλέσει το handler.next(), η αλυσίδα διακόπτεται και η απάντηση/σφάλμα δεν φτάνει στην εφαρμογή.

Για έλεγχο ταυτότητας στο Dio, χρησιμοποιείται ένας interceptor που προσθέτει token Bearer στην κεφαλίδα Authorization. Εάν ο διακομιστής επιστρέψει 401, ο interceptor στο onError προσπαθεί να ανανεώσει το token μέσω ενός αιτήματος refresh και επαναλαμβάνει το αρχικό αίτημα με το νέο token. Αυτό το μοτίβο ονομάζεται token refresh interceptor και υλοποιείται μέσω DioException με έλεγχο response?.statusCode == 401.

Το Dio παρέχει ενσωματωμένη υποστήριξη για λογική επανάληψης μέσω του πακέτου dio_smart_retry ή προσαρμοσμένου RetryInterceptor. Η επανάληψη είναι σημαντική για εφαρμογές κινητών: σε απώλεια σύνδεσης για 2–3 δευτερόλεπτα, το Dio ρίχνει DioException με τύπο connectionTimeout ή connectionError. Ο RetryInterceptor πιάνει αυτήν την εξαίρεση και επαναλαμβάνει το αίτημα έως 3 φορές με εκθετική καθυστέρηση (1s, 2s, 4s), αυξάνοντας την αξιοπιστία της εφαρμογής σε συνθήκες ασταθούς δικτύου.

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

Ας εξετάσουμε ένα βασικό αίτημα GET μέσω Dio. Δημιουργείται ένα στιγμιότυπο με BaseOptions, ορίζεται το βασικό URL και τα χρονικά όρια. Το αίτημα εκτελείται μέσω της μεθόδου get(), επιστρέφοντας Response με δεδομένα σε μορφή Map.

final dio = Dio(BaseOptions(
    baseUrl: 'https://api.github.com',
    connectTimeout: Duration(seconds: 15),
    receiveTimeout: Duration(seconds: 15),
    headers: {
        'Accept': 'application/vnd.github.v3+json',
    },
))

final response = await dio.get('/users/octocat')
print(response.data['σύνδεση'])

Για αίτημα POST με σώμα JSON, μεταδίδεται ένα αντικείμενο Map ή προσαρμοσμένο DTO. Το Dio σειριοποιεί αυτόματα το Map σε JSON μέσω jsonEncode. Για τυποποιημένο DTO, χρησιμοποιείται η επιλογή queryParameters, το πεδίο data ή προσαρμοσμένος Transformer.

final data = {
    'name': 'my-project',
    'description': 'Created via Dio',
    'private': false,
}

final response = await dio.post(
    '/user/repos',
    data: data,
    options: Options(
        contentType: ContentType.json.value,
    ),
)

print(response.data['id'])

Προσθήκη interceptor εξουσιοδότησης

Ο προσαρμοσμένος interceptor προσθέτει token Bearer σε κάθε αίτημα. Η μέθοδος onRequest ενεργοποιείται πριν από την αποστολή, τροποποιώντας τις κεφαλίδες. Σε απάντηση 401, ο interceptor μπορεί να ανανεώσει το token και να επαναλάβει το αίτημα μέσω της μεθόδου dio.fetch(requestOptions).

class AuthInterceptor extends InterceptorsWrapper {
    final String token

    AuthInterceptor(this.token)

    @override
    void onRequest(
        RequestOptions options,
        RequestInterceptorHandler handler,
    ) {
        options.headers['Authorization'] = 'Bearer $token'
        handler.next(options)
    }
}

dio.interceptors.add(AuthInterceptor('ghp_abc123'))

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

Το Dio απλοποιεί τη μεταφόρτωση αρχείων μέσω FormData. Για αποστολή αρχείου, δημιουργείται MultipartFile από File, Bytes ή AssetBundle. Το FormData ορίζει αυτόματα την κεφαλίδα multipart/form-data με σωστό όριο και κωδικοποίηση. Το Dio υποστηρίζει πρόοδο μεταφόρτωσης μέσω onSendProgress.

Για λήψη αρχείων χρησιμοποιείται η μέθοδος download(), η οποία αποθηκεύει τη ροή δεδομένων απευθείας σε αρχείο. Το Dio υποστηρίζει συνέχιση (resume) διακοπτόμενων λήψεων μέσω της κεφαλίδας Range, που είναι ιδιαίτερα χρήσιμο για μεγάλα αρχεία. Η πρόοδος λήψης παρακολουθείται μέσω onReceiveProgress, επιτρέποντας την εμφάνιση γραμμής προόδου στο UI.

final formData = FormData.fromMap({
    'file': await MultipartFile.fromFile(
        '/path/to/photo.jpg',
        filename: 'photo.jpg',
    ),
    'description': 'Profile photo',
})

await dio.post(
    '/upload',
    data: formData,
    onSendProgress: (sent, total) {
        final progress = sent / total * 100
        print('Μεταφόρτωση: $progress%')
    },
)

// Λήψη αρχείου
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('Λήψη: ${received / total * 100}%')
    },
)

Συνηθισμένα λάθη κατά την εργασία με το Dio

Λανθασμένος χειρισμός σφαλμάτων — το πιο συνηθισμένο πρόβλημα. Το Dio ρίχνει DioException (πρώην DioError) σε οποιοδήποτε πρόβλημα: απουσία δικτύου, χρονικό όριο, σφάλματα HTTP 4xx/5xx. Πολλοί προγραμματιστές πιάνουν μόνο το γενικό Exception, χάνοντας πληροφορίες σχετικά με τον τύπο σφάλματος και τη δυνατότητα προσαρμοσμένου χειρισμού. Χρησιμοποιήστε το DioException.type για τον προσδιορισμό της αιτίας αποτυχίας.

Αγνόηση του CancelToken οδηγεί σε διαρροή αιτημάτων. Εάν ο χρήστης εγκαταλείψει την οθόνη ενώ το αίτημα εκτελείται ακόμα, το Dio καταναλώνει πόρους και μπορεί να προσπαθήσει να ενημερώσει μια κατεστραμμένη State. Πάντα να δημιουργείτε CancelToken για κάθε αίτημα και να το ακυρώνετε στο dispose(). Το CancelToken παράγει DioException με τύπο cancel, το οποίο πρέπει να χειρίζεστε σωστά.

Έλλειψη λογικής επανάληψης για προσωρινές βλάβες. Σε κινητές συσκευές, το δίκτυο είναι συχνά προσωρινά μη διαθέσιμο. Υλοποιήστε έναν interceptor με αυτόματη επανάληψη αιτήματος σε χρονικό όριο ή απόκριση 503/502. Χρησιμοποιήστε RetryInterceptor από το πακέτο dio_smart_retry ή γράψτε προσαρμοσμένο interceptor με εκθετική καθυστέρηση μεταξύ προσπαθειών.