Retrofit — ano ito, HTTP-aklatan at paggamit sa mga application

Ano ang Retrofit?

Retrofit ay isang aklatan para sa pagsasagawa ng HTTP request sa Android applications, na binuo ng kumpanyang Square. Nagbibigay ito ng deklaratibong approach sa pagtukoy ng REST API sa pamamagitan ng Java interfaces na may mga anotasyon, na ginagawang malinis at predictable ang network communication code.

Ang pangunahing ideya ng Retrofit ay inilalarawan ng developer ang API bilang isang interface na may mga method at anotasyon, at ang aklatan ay bumubuo ng implementasyon nang mag-isa. Ginagarantiyahan ng approach na ito na ang lahat ng endpoints ay naka-type, at ang mga error sa URL o parameter ay natutukoy sa compilation phase, hindi sa runtime.

Sinusuportahan ng Retrofit ang lahat ng sikat na HTTP method at data format. Ang aklatan ay aktibong pinapanatili ng Square at komunidad: ang mga bagong bersyon ay regular na inilalabas, at ang kasalukuyang bersyon 2.11 ay may suporta para sa Java 17 at Kotlin 2.0. Ang Retrofit ay nananatiling pinakasikat na HTTP client para sa Android.

Gumagana ang Retrofit sa ibabaw ng OkHttp — isang mahusay na HTTP client din mula sa Square. Ang kombinasyong ito ay nagbibigay ng caching, pag-intercept ng request, at pamamahala ng koneksyon sa antas ng transport protocol. Sinusuportahan ng aklatan ang parehong synchronous at asynchronous na tawag.

Mula noong unang release noong 2013, ang Retrofit ay dumaan sa ilang malalaking update. Ang kasalukuyang bersyon na Retrofit 2 ay ganap na muling isinulat na isinasaalang-alang ang karanasan mula sa unang bersyon at nag-aalok ng mas flexible na sistema ng mga converter at adaptor para sa asynchronisidad.

Ang arkitektura ng Retrofit ay sumusunod sa prinsipyo ng paghihiwalay ng responsibilidad: ang interface ay tumutukoy lamang ng API contract, ang mga converter ay may pananagutan sa serialization, at ang mga adaptor ay namamahala ng asynchronisidad. Ito ay nagpapahintulot sa pagpapalit ng anumang bahagi nang hindi binabago ang natitirang code. Halimbawa, maaaring lumipat mula Gson patungong Moshi nang hindi binabago ang mga depinisyon ng endpoint.

Mga pangunahing kakayahan ng Retrofit

Retrofit ay nagbibigay ng isang set ng mga function na sumasaklaw sa halos lahat ng senaryo ng network communication sa mobile applications. Ang pangunahing bentahe ay ang deklaratibong estilo ng pagtukoy ng API.

Deklaratibong anotasyon ng endpoints

Mga anotasyon @GET, @POST, @PUT, @PATCH, @DELETE at @HTTP ay nagpapahintulot sa pagtukoy ng HTTP method at URL template direkta sa interface. Ang path parameters ay itinakda sa pamamagitan ng @Path, query parameters sa pamamagitan ng @Query, at request body sa pamamagitan ng @Body. Ang approach na ito ay ginagawang ganap na naka-type ang API layer ng application.

Mga converter para sa serialization

Mga converter ay ginagawang Java objects ang HTTP responses at vice versa. Sinusuportahan ng Retrofit ang Gson, Moshi, Jackson, Protobuf at Wire. Ikinokonekta ng developer ang kinakailangang converter sa pamamagitan ng Converter.Factory, at awtomatikong inilalapat ito ng aklatan sa lahat ng request at response.

Mga adaptor para sa asynchronisidad

Mga adaptor CallAdapter ay nagpapahintulot sa pagbabago ng return type ng API methods. Sa halip na standard Call, maaaring gumamit ng Observable para sa RxJava, Deferred para sa Kotlin coroutines o LiveData. Ito ay nag-iintegrate ng network request sa napiling arkitektura ng application.

Dynamic na URL at headers

Dynamic na URL ay itinakda sa pamamagitan ng @Url annotation, na nagpapahintulot sa pagpasa ng endpoint sa runtime. Ang headers ay maaaring tukuyin nang statically sa pamamagitan ng @Headers o dynamically sa pamamagitan ng @Header parameter. Para sa global headers ng lahat ng request, ginagamit ang OkHttp interceptor na nagdaragdag ng headers sa bawat papalabas na request.

Paano gumagana ang Retrofit?

Retrofit ay gumagana sa tatlong yugto: pagtukoy ng API interface, paggawa ng Retrofit instance, at pagsasagawa ng request. Ang aklatan ay bumubuo ng implementasyon ng interface sa runtime batay sa mga anotasyon at converter.

Siklo ng buhay ng request

Kapag ang isang API method ay tinawag, ang Retrofit ay gumagawa ng Request object batay sa mga anotasyon at argumento. Ang request ay ipinapasa sa OkHttp para sa pagpapatupad. Pagkatapos matanggap ang response, ipinapadala ito ng aklatan sa Converter.Factory para sa conversion sa kinakailangang uri. Binalot ng CallAdapter ang resulta sa isang asynchronous na wrapper. Ang bawat yugto ay maaaring i-customize.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

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

Pag-install at configuration ng Retrofit

Pag-install ng Retrofit ay ginagawa sa pamamagitan ng Gradle — ang standard build system ng Android. Ang aklatan ay ipinamamahagi sa pamamagitan ng Maven Central at nangangailangan ng pagdagdag ng ilang dependencies sa build.gradle ng proyekto.

Pagdagdag ng dependencies

Sa build.gradle file (antas ng modyul) magdagdag ng dependencies para sa Retrofit, Gson converter at OkHttp. Ang mga bersyon ng aklatan ay inirerekomenda na ilagay sa mga variable sa root build.gradle para sa sentralisadong pamamahala. Ang Retrofit 2 ay nangangailangan ng minimum na Android API 21.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Paggawa ng Retrofit instance

Ang Retrofit instance ay ginagawa sa pamamagitan ng Builder. Mga mandatoryong parameter: baseUrl at ConverterFactory. Inirerekomenda ang paggamit ng singleton para sa Retrofit at OkHttpClient upang maiwasan ang paggawa ng mga labis na koneksyon. Ang pagdagdag ng logging-interceptor ay nagpapadali sa debugging ng network request sa panahon ng development.

Para sa mga proyekto sa Kotlin, inirerekomenda ang paggamit ng suspend functions sa API interface sa halip na Call types. Ito ay nagpapasimple ng code at nagpapahintulot sa paggamit ng structured concurrency ng coroutines. Sa paglipat mula Call patungong suspend, sapat na baguhin ang return type sa interface — ang natitirang code ay awtomatikong umaangkop.

Mga halimbawa ng paggamit ng Retrofit

Mga halimbawa sa ibaba ay nagpapakita ng mga tipikal na senaryo ng pagtatrabaho sa Retrofit sa Android applications: mula sa simpleng GET request hanggang sa pag-upload ng file sa server.

GET request na may query parameters

Simpleng GET request na may query string parameters — pangunahing operasyon. Ang @Query annotation ay awtomatikong nagdaragdag ng parameters sa URL, at ang suspend function ay nagpapahintulot sa pagtawag ng request mula sa coroutine nang hindi binabangga ang main thread.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

POST request na may JSON body

POST request na may JSON body ay gumagamit ng @Body annotation para sa pagpapadala ng object. Ang GsonConverterFactory ay awtomatikong nagse-serialize ng User object sa JSON. Ang Kotlin coroutines ay tinitiyak ang pagpapatupad ng request sa background thread nang walang Callback interfaces.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Anna Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Pag-upload ng file sa pamamagitan ng Multipart

Ang @Multipart annotation na may @Part ay nagpapahintulot sa pag-upload ng mga file sa server. Awtomatikong gumagawa ang Retrofit ng multipart request na may kinakailangang headers. Pinamamahalaan ng OkHttp ang progreso ng pag-upload sa pamamagitan ng RequestBody, na nagpapahintulot sa pagpapakita ng indicator sa user.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Pangangasiwa ng error at mga interceptor sa Retrofit

Pangangasiwa ng error sa Retrofit ay batay sa kombinasyon ng OkHttp mechanisms at Kotlin coroutines. Ang OkHttp interceptors ay nagpapahintulot sa pag-log ng request, pagdagdag ng authentication headers, at pangangasiwa ng error bago maabot ang application code.

Para sa sentralisadong pangangasiwa ng error, madalas gumawa ng wrapper sa paligid ng API calls sa anyo ng sealed class Result. Ang ganitong klase ay naglalaman ng dalawang subclass: Success na may data at Error na may exception. Ang ViewModel ay tumatanggap ng unified na resulta at maaaring magpakita ng kaukulang estado ng user interface nang hindi nadu-duplicate ang error handling code sa bawat function.

Mga interceptor ay may dalawang uri: application interceptors ay nagmo-modify ng request bago ipadala sa server, at network interceptors ay gumagana sa response pagkatapos matanggap. Halimbawa, ang isang interceptor ay maaaring awtomatikong mag-refresh ng access token kapag nakatanggap ng 401 at ulitin ang request gamit ang bagong token nang walang partisipasyon ng developer.

Pag-log ng request sa pamamagitan ng Interceptor

Logging interceptor HttpLoggingInterceptor — isang kailangang-kailangan na kasangkapan sa debugging ng network request. Ipinapakita nito sa Logcat ang request method, URL, headers, body at response code. Ang antas ng pag-log ay maaaring i-configure: BASIC para sa minimal na impormasyon, HEADERS para sa headers o BODY para sa buong nilalaman. Sa produksyon, inirerekomenda ang BASIC o ganap na pag-disable ng pag-log.

Mga interceptor sa OkHttp ay nahahati sa dalawang uri: application interceptors para sa pagmo-modify ng request at network interceptors para sa pagtatrabaho sa raw network data. Ang logging interceptor ay awtomatikong nagpapakita ng request at response details sa Logcat.

Pangangasiwa ng error sa antas ng coroutine ay ginagawa sa pamamagitan ng try-catch sa paligid ng tawag sa suspend function. Ang Retrofit ay nagbabalik ng mga error bilang HttpException para sa codes 4xx at 5xx, UnknownHostException kapag walang network, at SocketTimeoutException kapag lumampas sa timeout. Inirerekomenda ang paggamit ng sealed class Result para sa unified handling.