Redesigning Snowball's Android Network Framework with OkHttp and Retrofit: Architecture, Issues, and Migration

Snowball's original Android network framework had become outdated, leading to problems such as complex integration, poor performance, unreasonable architecture, limited functionality, an inactive community, and fragmented usage across multiple sub‑projects. To address these issues, a new framework based on OkHttp and Retrofit was designed.

The new framework follows a three‑question approach: what the libraries are, why they are chosen, and how to use them. OkHttp provides efficient HTTP connections, HTTP/2 support, connection pooling, GZIP compression, and caching. Retrofit offers a clean, declarative API layer that works with OkHttp, enabling easy request definition and response handling.

Reasons for selecting OkHttp and Retrofit include reasonable architecture (separating low‑level HTTP handling from higher‑level abstraction), high availability (connection reuse, compression, fast speed), and active maintenance with a vibrant community, unlike alternatives such as Volley, xUtils, and Android‑async‑http.

During the migration, several concrete problems were solved:

Domain switching: using an IPManager and an OkHttp interceptor to replace hostnames with optimal IPs, improving latency, enabling local access, avoiding DNS hijacking, and providing basic resilience.

Custom annotations: a DisableCommonError annotation was created to mark APIs that should bypass generic error handling. A double‑proxy mechanism intercepts Retrofit calls, records URLs with this annotation, and the response interceptor skips common error processing for those URLs.

Data validation: custom TypeAdapter implementations for Gson were added to handle null strings and other type mismatches, ensuring robust JSON parsing.

These solutions are illustrated with Kotlin code snippets wrapped in ... blocks.

The overall framework is organized into four layers:

Base layer: OkHttp and Retrofit libraries.

Infrastructure layer: wrappers, builders, and common interceptors providing configurable entry points.

Middle layer: project‑specific initialization and API definitions, handling public parameters, cookies, headers, dynamic domain replacement, login checks, and unified error handling.

Application layer: business‑level API calls integrated with the existing MVVM onion architecture (View, ViewModel, Model, Repository).

Migration to the new framework is performed by abstracting network calls behind interfaces, using Retrofit's standard @GET and @POST definitions, and gradually replacing old calls while keeping the onion architecture unchanged.

In summary, the redesign clarified the purpose of the network layer, justified the choice of OkHttp and Retrofit, demonstrated practical solutions for common pitfalls, described the layered architecture, and outlined a safe migration path, resulting in significantly better performance, maintainability, and scalability for Snowball's Android client.