Розробка мережевого шару на Retrofit часто натикається на підводні камені: несподіваний 401, помилки парсингу, витік токенів. Один із наших проєктів — додаток для банківського сервісу — вимагав надійної авторизації з оновленням токена. Без налаштування Authenticator OkHttp кожен запит до захищеного ресурсу повертав помилку. Нам довелося переписати логіку, щоб уникнути ручної обробки в кожному UseCase. За 5 років роботи над 20+ проєктами ми виробили типову конфігурацію, яка скорочує час розробки мережевого шару на 30–50%. Розглянемо best practices налаштування мережевого шару на Retrofit. Ми гарантуємо якість коду, покриття тестами (не менше 80%) та підтримку протягом 2 тижнів після здачі.
Приклад коду Interceptor та Authenticator
class AuthInterceptor(private val tokenProvider: TokenProvider) : Interceptor { override fun intercept(chain: Interceptor.Chain): Response { val request = chain.request().newBuilder() .addHeader("Authorization", "Bearer ${tokenProvider.getToken()}") .build() return chain.proceed(request) } } class TokenAuthenticator( private val tokenProvider: TokenProvider, private val refreshApi: RefreshApi ) : Authenticator { override fun authenticate(route: Route?, response: Response): Request? { synchronized(this) { val newToken = tokenProvider.getToken() ?: return null if (response.request.header("Authorization") == "Bearer $newToken") { val refreshed = refreshApi.refresh(newToken) if (refreshed.isSuccessful) { tokenProvider.saveToken(refreshed.body()!!.accessToken) return response.request.newBuilder() .header("Authorization", "Bearer ${refreshed.body()!!.accessToken}") .build() } } } return null } } Як налаштувати авторизацію в Retrofit?
Авторизація будується на двох компонентах: Interceptor для додавання заголовка та Authenticator для оновлення токена. Interceptor читає токен із захищеного сховища (EncryptedSharedPreferences) та підставляє його в кожен запит. Якщо сервер повертає 401, Authenticator намагається оновити токен через refresh-ендпоінт і повторює запит. Це позбавляє копіювання логіки авторизації по всьому проєкту та працює з будь-якими OAuth2-провайдерами.
Чому KotlinX Serialization кращий за Gson?
У Kotlin-проєктах kotlinx.serialization дає переваги: null-safety на рівні парсингу, підтримка sealed класів та робота без рефлексії. Це особливо важливо при обфускації через R8, оскільки рефлексивні виклики Gson можуть зламатися. За нашими вимірами, KotlinX обробляє JSON у 2–3 рази швидше за Gson на об'ємах від 100 КБ. Крім того, розмір APK збільшується лише на ~50 КБ проти ~200 КБ у Gson.
Порівняльна таблиця Gson vs KotlinX
| Критерій | Gson | KotlinX Serialization |
|---|---|---|
| Швидкість (відносно) | 1x | 2–3x |
| Null-safety | Ні | Так |
| Sealed класи | Ні | Так |
| Рефлексія | Так | Ні |
| Розмір APK (приріст) | ~200 КБ | ~50 КБ |
Інтерсептори OkHttp
Тут зосереджена більша частина логіки мережевого шару. Окрім авторизації, типові інтерсептори:
- Логування:
HttpLoggingInterceptorз рівнемBODYтільки для debug-збірки. У production —NONE, щоб не логувати чутливі дані. - Retry: кастомний інтерсептор з експоненційною затримкою для
IOException. Коди 4xx та 5xx не повторюємо — тільки мережеві збої. - Timeout:
connectTimeout(30, TimeUnit.SECONDS),readTimeout(30, TimeUnit.SECONDS),writeTimeout(30, TimeUnit.SECONDS). Для завантаження файлів (до 5 МБ) використовуємо окремий клієнт із збільшенимwriteTimeout.
Таблиця інтерсепторів
| Інтерсептор | Призначення | Приклад конфігурації |
|---|---|---|
| AuthInterceptor | Додавання Bearer-токена | .addInterceptor(AuthInterceptor(tokenProvider)) |
| TokenAuthenticator | Автоматичне оновлення токена | .authenticator(TokenAuthenticator(tokenProvider, refreshApi)) |
| HttpLoggingInterceptor | Логування запитів/відповідей | .addInterceptor(HttpLoggingInterceptor().apply { level = if (BuildConfig.DEBUG) BODY else NONE }) |
| RetryInterceptor | Повтор при мережевих помилках | Кастомна реалізація з exponential backoff |
Типові помилки при налаштуванні:
- Неправильний baseUrl: обов'язково кінцевий слеш
/. - Відсутність
INTERNET-пермішену в маніфесті. - Зберігання токена в
SharedPreferencesбез шифрування — використовуйтеEncryptedSharedPreferences. - Забули додати логгер у debug-збірці — налагодження займе години.
Обробка помилок
Suspend-функції Retrofit викидають HttpException при статусах не 2xx та IOException при мережевих проблемах. Обгортаємо в sealed class:
sealed class ApiResult<out T> { data class Success<T>(val data: T) : ApiResult<T>() data class Error(val code: Int, val message: String) : ApiResult<Nothing>() data object NetworkError : ApiResult<Nothing>() } Це дозволяє ViewModel обробляти помилки типізовано без try/catch на кожному виклику. Логіка обгортки винесена в NetworkDataSource. Для unit-тестів використовуємо MockWebServer — симулюємо відповіді та перевіряємо коректність парсингу. Такий підхід скорочує час на налагодження інтеграції на 20–30%.
Як ми працюємо над мережевим шаром
Наш процес включає етапи:
- Аналітика — визначаємо ендпоїнти, формати запитів/відповідей, фіксуємо вимоги до безпеки.
- Проектування — вибираємо стек (Retrofit + OkHttp + серіалізатор), проектуємо інтерфейси та моделі даних.
- Реалізація — пишемо код мережевого шару, налаштовуємо інтерсептори, обробку помилок, unit-тести.
- Тестування — інтеграційні тести з MockWebServer, перевірка сценаріїв авторизації, retry, timeout.
- Деплой — інтеграція в CI/CD, налаштування productFlavors для різних оточень.
Що входить в роботу з налаштування мережевого шару
- Документація API (формат, ендпоїнти, приклади запитів/відповідей)
- Повний код мережевого шару (інтерфейси, інтерсептори, моделі)
- Unit-тести та інтеграційні тести (покриття не менше 80%)
- Конфігурація CI/CD для збірки різних оточень
- Code review та рекомендації щодо подальшого розширення
- Підтримка протягом 2 тижнів після здачі
Терміни налаштування мережевого шару — від 1 до 3 днів. Налаштування під ключ.
Як налаштувати Retrofit за 5 кроків
- Підключіть залежності в
build.gradle.kts:implementation("com.squareup.retrofit2:retrofit:2.9.0") implementation("com.squareup.okhttp3:okhttp:4.12.0") implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")Звертайтеся до нас для консультації — ми налаштуємо мережевий шар під ключ за 1-3 дні. Оцінимо ваш проект безкоштовно.
Додаткові матеріали: Retrofit та OkHttp — офіційні джерела за цими бібліотеками.