Dio: шта је то, карактеристике ХТТП клијента за Флуттер

Шта је Dio?

Dio — је моћна библиотека ХТТП клијента за језик Дарт, најшире коришћена у апликацијама на Флуттер-у. Dio пружа богати АПИ са подршком за пресретаче, глобалну конфигурацију, трансформере, ФормДата, отпремање датотека и флексибилно управљање временским ограничењима, што га чини главним избором за мрежну комуникацију у Флуттер заједници.

Библиотеку је створио Венда Ванг 2018. године као алтернативу уграђеном dart:io ХттпКлијент-у, који није имао многе модерне могућности: јединствену конфигурацију за све захтеве, пресретаче и аутоматску серијализацију. До 2025. године Dio је по популарности престигао хттп пакет од Дарт тима, заузевши прво место међу ХТТП клијентима у Флуттер екосистему према подацима pub.dev.

Dio подржава три адаптера: ДартНативеАдаптер (подразумевано на Андроид, иОС, Десктоп), БровсерАдаптер (на Веб-у) и ИОАдаптер. Адаптер се аутоматски бира у зависности од платформе. Dio такође пружа јединствени интерфејс за све Флуттер платформе — Андроид, иОС, Веб, мацОС, Виндовс и Линукс.

Како ради Dio

Архитектура Dio је изграђена на ланцу обрађивача (handler chain). Сваки захтев пролази кроз низ пресретача који могу да модификују захтев (ИнтерцепторсВраппер.онРекуест), одговор (онРеспонсе) или обраде грешку (онЕррор). После пресретача, захтев доспева до трансформера (Трансформер) који преобразују податке пре слања.

Инстанца Dio се конфигурише кроз објекат БасеОптионс који садржи основни УРЛ, подразумевана заглавља, временска ограничења, тип одговора (ЈСОН, стреам, плаин), упитне параметре и формат података. Ова подешавања се примењују на све захтеве, али могу бити замењена у одређеном захтеву. БасеОптионс обезбеђује јединствену тачку конфигурације за целу апликацију, што поједностављује промену АПИ ендпоинта или додавање глобалних заглавља.

Сваки захтев у Dio враћа Респонсе<Т>, где је Т — тип података после обраде од стране трансформера. Подразумевано Dio аутоматски претвара ЈСОН одговор у Мап<Стринг, dynamic>. За типизиране одговоре користи се Dio заједно са пакетима за серијализацију: јсон_сериализабле, фреезед или буилт_валуе. Респонсе садржи дата, хеадерс, статусЦоде, рекуестОптионс и додатне податке.

Глобална конфигурација Dio

Основна конфигурација се креира кроз Dio(БасеОптионс). Може се поставити басеУрл за све захтеве, цоннецтТимеоут и рецеивеТимеоут, заглавља цонтент-типе и аццепт, као и qуериПараметерс. Сви ови параметри се примењују на сваки захтев, чиме се елиминише дуплирање кода и централизује управљање мрежним подешавањима.

Dio подржава два режима серијализације: подразумевани ЈСОН (респонсеТипе: РеспонсеТипе.јсон) и стрим (РеспонсеТипе.стреам). У стрим режиму Респонсе.дата враћа РеспонсеБоди који се може читати у деловима. Ово је згодно за велике пејлоад датотеке, када потпуно учитавање у меморију није пожељно. Плаин режим враћа сирови низ без аутоматског парсирања ЈСОН-а.

Dio пресретачи

Пресретачи — кључни механизам Dio за пресретање и модификацију захтева, одговора и грешака. Они у потпуности замењују Интерцептор из ОкХттп-а и додатке из Ктор-а, али са Дарт-специфичним АПИ-јем и подршком за асинхроност кроз Футуре. Пресретачи се могу додавати како у глобалној конфигурацији Dio, тако и за појединачне захтеве.

ЛогИнтерцептор

Уграђени ЛогИнтерцептор бележи сваки захтев: методу, УРЛ, заглавља, тело и време извршења. Има два режима: цомпацт (један ред по захтеву) и фулл (потпуне информације са телом). ЛогИнтерцептор је посебно користан током развоја, али се препоручује да се искључи у релеасе верзијама кроз условни импорт или глобални флаг.

Прилагођени пресретачи се креирају кроз класу ИнтерцепторсВраппер. Може се прегазити једна, две или све три методе (онРекуест, онРеспонсе, онЕррор). Dio извршава пресретаче строго по редоследу њиховог додавања у листу интерцепторс. Ако пресретач не позове хандлер.неxт(), ланац се прекида и одговор/грешка не стижу до апликације.

За ауторизацију у Dio користи се пресретач који додаје Беарер токен у заглавље Аутхоризатион. Ако сервер врати 401, пресретач у онЕррор покушава да освежи токен кроз рефресх захтев и понавља оригинални захтев са новим токеном. Овај образац се назива токен рефресх интерцептор и имплементира се кроз ДиоЕxцептион са провером респонсе?.статусЦоде == 401.

Dio пружа уграђену подршку за логику поновног покушаја кроз пакет дио_смарт_ретрy или прилагођени РетрyИнтерцептор. Поновни покушај је важан за мобилне апликације: при губитку везе на 2–3 секунде Dio баца ДиоЕxцептион са типом цоннецтионТимеоут или цоннецтионЕррор. РетрyИнтерцептор пресреће овај изузетак и понавља захтев до 3 пута са експоненцијалним закашњењем (1с, 2с, 4с), што повећава поузданост апликације у условима нестабилне мреже.

Примери кода Dio у Дарт-у

Размотримо основни ГЕТ захтев кроз Dio. Креира се инстанца са БасеОптионс, поставља се основни УРЛ и временска ограничења. Захтев се извршава кроз метод гет(), који враћа Респонсе са подацима у формату Мап.

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['пријава'])

За ПОСТ захтев са ЈСОН телом прослеђује се Мап објекат или прилагођени ДТО. Dio аутоматски серијализује Мап у ЈСОН кроз јсонЕнцоде. За типизирани ДТО користи се опција qуериПараметерс, дата поље или прилагођени Трансформер.

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['ид'])

Додавање пресретача ауторизације

Прилагођени пресретач додаје Беарер токен сваком захтеву. Метода онРекуест се активира пре слања, мењајући заглавља. При одговору 401, пресретач може да освежи токен и понови захтев кроз метод дио.фетцх(рекуестОптионс).

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 поједностављује отпремање датотека кроз ФормДата. За слање датотеке креира се МултипартФиле из Филе, Бyтес или АссетБундле. ФормДата аутоматски поставља заглавље мултипарт/форм-дата са исправном границом и кодирањем. Dio подржава напредак отпремања кроз онСендПрогресс.

За преузимање датотека користи се метод доwnлоад(), који чува ток података директно у датотеку. Dio подржава наставак (ресуме) прекинутих преузимања кроз заглавље Ранге, што је посебно корисно за велике датотеке. Напредак преузимања се прати кроз онРецеивеПрогресс, омогућавајући приказ траке напретка у корисничком интерфејсу.

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 баца ДиоЕxцептион (раније ДиоЕррор) при било каквим проблемима: недостатак мреже, временско ограничење, ХТТП грешке 4xx/5xx. Многи програмери хватају само генерички Еxцептион, губећи информацију о типу грешке и могућности њене прилагођене обраде. Користите ДиоЕxцептион.типе за одређивање узрока квара.

Игнорисање ЦанцелТокен-а доводи до цурења захтева. Ако корисник напусти екран, а захтев се наставља извршавати, Dio троши ресурсе и може покушати да ажурира уништени Стате. Увек креирајте ЦанцелТокен за сваки захтев и откажите га у диспосе(). ЦанцелТокен генерише ДиоЕxцептион са типом цанцел, који треба правилно обрадити.

Недостатак логике поновног покушаја за привремене кварове. На мобилним уређајима мрежа је често краткотрајно недоступна. Имплементирајте пресретач са аутоматским понављањем захтева при временском ограничењу или одговору 503/502. Користите РетрyИнтерцептор из пакета дио_смарт_ретрy или напишите прилагођени пресретач са експоненцијалним закашњењем између покушаја.