Retrofit: ano ito, mga tampok ng HTTP client ng Android

Ano ang Retrofit?

Retrofit — ay isang library para sa typed na interaksyon sa REST API sa Android platform, na binuo ng kumpanyang Square. Nagbibigay ito ng declarative na paraan ng paglalarawan ng mga HTTP request sa pamamagitan ng Java o Kotlin interface na may mga annotation, na ganap na nagpapalaya sa developer mula sa manual na pag-parse ng JSON at pamamahala ng mga HTTP connection.

Ang library ay lumitaw noong 2013 bilang alternatibo sa mga malalaking solusyon tulad ng AsyncTask at HttpURLConnection. Pagsapit ng 2025, ang Retrofit ay nananatiling de facto na pamantayan para sa network communication sa mga Android application dahil sa kasimplehan at kaligtasan ng tipo. Ayon sa survey ng JetBrains Developer Ecosystem 2024, mahigit 65% ng mga Android developer ang gumagamit ng Retrofit sa mga komersyal na proyekto.

Ang pangunahing pagkakaiba ng Retrofit mula sa mga alternatibo — ang declarative na diskarte: inilalarawan ng developer kung ano ang gagawin (aling endpoint ang tatawagin, anong mga parameter ang ipapasa), hindi kung paano gagawin (paano buksan ang koneksyon, paano basahin ang InputStream, paano i-parse ang JSON). Binabawasan nito ang dami ng boilerplate code ng 60–70% kumpara sa manual na paggamit ng HttpURLConnection.

Paano gumagana ang Retrofit

Prinsipyo ng pagpapatakbo ng Retrofit ay batay sa dynamic na proxy ng Java. Kapag ang developer ay tumawag ng isang method ng interface na may markang annotation, ang Retrofit sa pamamagitan ng Proxy.newProxyInstance mechanism ay sumasalo ng tawag at ginagawa itong HTTP request. Ang buong proseso ay nagaganap sa runtime nang walang code generation sa compilation phase.

Sa paggawa ng instance ng Retrofit.Builder, tinutukoy ang base URL at factory ng converter. Ang Builder ay nagca-configure ng OkHttpClient — nagtatakda ng mga timeout, interceptor, connection pool, at cache. Ang method na create(Class) ay bumubuo ng implementasyon ng interface, na nagbabalik ng proxy object na maaaring tawagin tulad ng ordinaryong klase.

Ang chain ng pagpapatupad ng request ay ganito: kinukuha ng mga annotation ang HTTP method, ang mga parameter ay ipinapasok sa URL o body ng request, sine-serialize ng converter ang body, isinasagawa ng OkHttp ang request, dine-deserialize ng converter ang tugon, ang resulta ay ibinabalik sa tinukoy na tipo. Ang bawat yugto ay isolated at maaaring palitan ng custom na implementasyon, halimbawa pagpapalit ng OkHttpClient ng MockWebServer para sa testing o pagpapalit ng converter sa pagbabago ng API.

Mahalagang katangian — hindi direktang sinusuportahan ng Retrofit ang streaming ng data. Para sa streaming, ginagamit ang OkHttp ResponseBody bilang return type ng interface method. Hindi rin awtomatikong pinamamahalaan ng Retrofit ang pagkansela ng mga request — para kanselahin, kailangang mag-imbak ng reference sa Call at tawagin ang cancel(). Sa Kotlin na may suspend function, awtomatikong nagaganap ang pagkansela ng request sa pagkansela ng parent coroutine.

Lifecycle ng Call object

Call<T> — ay isang object na kumakatawan sa isang HTTP request. Pagkatapos ng pagpapatupad (execute o enqueue), hindi maaaring gamitin muli ang Call — para sa paulit-ulit na request, kailangang gumawa ng bagong Call sa pamamagitan ng pagtawag sa interface method. Pinoprotektahan nito laban sa aksidenteng pagpapadala ng parehong request nang dalawang beses, na maaaring humantong sa pagdoble ng mga operasyon sa server.

Sa Kotlin, sa halip na Call, ginagamit ang mga suspend function na awtomatikong namamahala ng lifecycle ng request. Ang Retrofit mismo ay lumilipat ng execution sa Dispatchers.IO at ibinabalik ang resulta sa coroutine. Pinaikli nito ang code ng 30–40% kumpara sa bersyon sa Call at Callback.

Mga annotation ng Retrofit para sa mga HTTP method

Ang mga annotation — ay ang pangunahing mekanismo ng configuration ng mga HTTP request sa Retrofit. Bawat annotation ay tumutugma sa isang standard na HTTP method at tumatanggap ng relative path papunta sa endpoint. Sinusuportahan ng Retrofit ang GET, POST, PUT, DELETE, PATCH, HEAD, at OPTIONS.

Mga annotation ng parameter ng request

@Path ay nagpapalit ng halaga sa segment ng URL: @Path(id) Int id ay nagpapalit ng {id} sa path. @Query ay nagdadagdag ng query parameter: @Query(page) Int page ay nagiging ?page=5. @Body ay nagpapasa ng object sa body ng request na may automatic serialization sa pamamagitan ng napiling converter. @Header at @Headers ay namamahala ng mga HTTP header — static o dynamic.

Sa pamamagitan ng pagsasama ng mga annotation na ito, maaaring ilarawan ang anumang REST endpoint. Halimbawa, para sa endpoint na POST /api/users/{id}/posts?limit=10, kailangan ang @POST, @Path para sa id, @Query para sa limit, at @Body para sa ipapasang object. Awtomatikong bubuo ang Retrofit ng tamang HTTP request. Dagdag pa, sinusuportahan ang @Url (dynamic na URL), @Field (form-encoded body), @Part at @PartMap para sa multipart request na may mga file.

Mga halimbawa ng code ng Retrofit sa Kotlin

Tingnan natin ang isang praktikal na halimbawa — isang interface para sa GitHub API. Gumagawa ng Kotlin interface na may method para sa pagkuha ng listahan ng mga repository. Inilalarawan ng Data class Repo ang istraktura ng JSON response.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Pagkatapos ilarawan ang interface, gumagawa ng instance ng Retrofit sa pamamagitan ng Builder. Ang base URL, converter, at OkHttpClient ay naka-configure nang isang beses at ginagamit muli sa pamamagitan ng dependency injection.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

val api = retrofit.create(GitHubApi::class.java)

Pagproseso ng tugon gamit ang Response wrapper

Para sa flexible na pagproseso ng mga HTTP status, gamitin ang Response<T> wrapper. Nagbibigay ito ng access sa response code, mga header, at body, nang hindi nagtatapon ng exception sa mga error na 4xx at 5xx. Pinapayagan nito ang pagproseso ng 404 at 500 nang walang try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Mga converter at serialization sa Retrofit

Mga Converter — ay mga component ng Retrofit na responsable sa pag-convert ng mga object sa HTTP body at vice versa. Hindi isinasama ng Retrofit ang serialization sa core — sa halip, ginagamit ang modular approach sa pamamagitan ng Converter.Factory, na nagpapahintulot na magkonekta ng anumang serialization library.

Ang pinakasikat na converter — GsonConverterFactory mula sa Google batay sa Gson library. Ito ay angkop para sa karamihan ng mga proyekto, sumusuporta sa custom na TypeAdapter at JsonDeserializer. Gayunpaman, gumagamit ang Gson ng reflection at hindi isinasaalang-alang ang null safety ng Kotlin, na maaaring humantong sa NPE sa mga hindi inaasahang null field.

Alternatibo — MoshiConverterFactory mula sa Square: mas mahigpit sa mga tipo, na may mas mahusay na suporta sa Kotlin (null safety, default values) at walang reflection. Para sa mga proyekto sa purong Kotlin, optimal — Kotlinx Serialization Converter, na gumagana sa @Serializable annotation sa compilation phase. Hindi gumagamit ng reflection, sumusuporta sa sealed class, default values, at multiplatform.

Ang pagpili ng converter ay nakakaapekto sa performance at kaligtasan ng mga tipo. Ang Gson nang walang custom na configuration ay maaaring mag-deserialize ng null sa non-null field ng Kotlin, na nagdudulot ng NPE sa pag-access. Nilulutas ng Moshi ang problemang ito sa pamamagitan ng @Json(name) annotation at failOnUnknown. Ang Kotlinx Serialization ay ang pinakaligtas — bumubuo ito ng code sa compilation phase, ganap na inaalis ang mga tipo error sa runtime.

Mga karaniwang pagkakamali sa pagtatrabaho sa Retrofit

Kawalan ng paghawak ng HTTP error sa mga suspend function — ang pinakakaraniwang problema. Kung ang server ay nagbalik ng 4xx o 5xx, ang Retrofit ay nagtatapon ng HttpException. Nang walang try-catch, ang application ay magca-crash. Ang paggamit ng Response<T> bilang return type ay nilulutas ang problemang ito, na nagpapahintulot sa pagsuri ng isSuccessful bago ma-access ang body.

Maling configuration ng caching ay humahantong sa labis na trapiko. Hindi nagca-cache ang Retrofit ng mga tugon nang mag-isa — ang gawaing ito ay nilulutas ng OkHttpClient sa pamamagitan ng Cache. Nang walang cache, ang bawat request ay isinasagawa nang buo, kahit na ang data ay hindi nagbago. Ang pagdagdag ng Cache na may sukat na 10 MB sa OkHttpClient ay nagbabawas ng trapiko ng 40–60% sa mga paulit-ulit na request ng parehong impormasyon.

Paggawa ng Retrofit para sa bawat request — karaniwang pagkakamali ng mga baguhan. Ang Retrofit.Builder ay isang resource-intensive na operasyon na kinabibilangan ng pagbuo ng mga proxy class sa runtime. Ang tamang praktika — gumawa ng isang instance ng Retrofit at gamitin itong muli sa pamamagitan ng DI frameworks. Hilt, Koin o Dagger ay nagbibigay ng singleton instance ng Retrofit para sa buong application, na nakakatipid ng memory at nagpapabilis ng mga request.

Pagbalewala sa Interceptor para sa awtorisasyon — ang ika-apat na problema. Sa halip na manu-manong magdagdag ng Authorization header sa bawat tawag, mag-configure ng global na Interceptor sa OkHttpClient. Ang Interceptor ay sumasalo ng bawat request, nagdadagdag ng Bearer token, at ang Authenticator ay nagpoproseso ng 401 response, nagre-renew ng token at inuulit ang request nang awtomatiko. Ito ay nagse-centralize ng authentication logic.