Retrofit — nó là gì, thư viện HTTP và sử dụng trong các ứng dụng

Retrofit là gì?

Retrofit là một thư viện để thực hiện các yêu cầu HTTP trong ứng dụng Android, được phát triển bởi Square. Nó cung cấp một cách tiếp cận khai báo để định nghĩa REST API thông qua các giao diện Java với chú thích, làm cho mã tương tác mạng trở nên sạch sẽ và có thể dự đoán trước.

Ý tưởng cốt lõi của Retrofit là nhà phát triển mô tả API như một giao diện với các phương thức và chú thích, và thư viện tự động tạo ra triển khai. Cách tiếp cận này đảm bảo tất cả các endpoint đều được phân loại kiểu và các lỗi trong URL hoặc tham số được phát hiện tại thời điểm biên dịch chứ không phải lúc chạy.

Retrofit hỗ trợ tất cả các phương thức HTTP phổ biến và định dạng dữ liệu. Thư viện được Square và cộng đồng tích cực duy trì: các phiên bản mới được phát hành thường xuyên và phiên bản hiện tại 2.11 bao gồm hỗ trợ Java 17 và Kotlin 2.0. Retrofit vẫn là HTTP client phổ biến nhất cho Android.

Retrofit hoạt động trên OkHttp — một HTTP client hiệu quả cũng từ Square. Sự kết hợp này cung cấp bộ nhớ đệm, chặn yêu cầu và quản lý kết nối ở cấp giao thức vận chuyển. Thư viện hỗ trợ cả lời gọi đồng bộ và bất đồng bộ.

Kể từ lần phát hành đầu tiên vào năm 2013, Retrofit đã trải qua nhiều bản cập nhật lớn. Phiên bản hiện tại Retrofit 2 đã được viết lại hoàn toàn dựa trên kinh nghiệm của phiên bản đầu tiên và cung cấp một hệ thống linh hoạt hơn của các trình chuyển đổi và bộ chuyển đổi cho xử lý bất đồng bộ.

Kiến trúc Retrofit tuân theo nguyên tắc phân tách mối quan tâm: giao diện chỉ xác định hợp đồng API, các trình chuyển đổi xử lý tuần tự hóa và các bộ chuyển đổi quản lý bất đồng bộ. Điều này cho phép thay thế bất kỳ thành phần nào mà không cần thay đổi phần còn lại của mã. Ví dụ, bạn có thể chuyển từ Gson sang Moshi mà không cần thay đổi định nghĩa endpoint.

Các tính năng chính của Retrofit

Retrofit cung cấp một tập hợp các tính năng bao phủ hầu hết tất cả các tình huống tương tác mạng trong ứng dụng di động. Lợi thế chính là phong cách khai báo của định nghĩa API.

Chú thích endpoint khai báo

Các chú thích @GET, @POST, @PUT, @PATCH, @DELETE và @HTTP cho phép chỉ định phương thức HTTP và mẫu URL trực tiếp trong giao diện. Tham số đường dẫn được đặt qua @Path, tham số truy vấn qua @Query và phần thân yêu cầu qua @Body. Cách tiếp cận này làm cho lớp API của ứng dụng được phân loại kiểu hoàn toàn.

Trình chuyển đổi cho tuần tự hóa

Các trình chuyển đổi biến phản hồi HTTP thành các đối tượng Java và ngược lại. Retrofit hỗ trợ Gson, Moshi, Jackson, Protobuf và Wire. Nhà phát triển kết nối trình chuyển đổi cần thiết qua Converter.Factory, và thư viện tự động áp dụng nó cho tất cả các yêu cầu và phản hồi.

Bộ chuyển đổi cho xử lý bất đồng bộ

Các bộ chuyển đổi CallAdapter cho phép thay đổi kiểu trả về của các phương thức API. Thay vì Call tiêu chuẩn, có thể sử dụng Observable cho RxJava, Deferred cho coroutines Kotlin hoặc LiveData. Điều này tích hợp các yêu cầu mạng với kiến trúc ứng dụng đã chọn.

URL động và tiêu đề

Các URL động được đặt qua chú thích @Url, cho phép truyền endpoint trong thời gian chạy. Tiêu đề có thể được chỉ định tĩnh qua @Headers hoặc động qua tham số @Header. Đối với tiêu đề toàn cục trên tất cả các yêu cầu, một bộ chặn OkHttp được sử dụng để thêm tiêu đề vào mỗi yêu cầu gửi đi.

Cách Retrofit hoạt động?

Retrofit hoạt động theo ba giai đoạn: xác định giao diện API, tạo phiên bản Retrofit và thực thi yêu cầu. Thư viện tạo ra triển khai giao diện trong thời gian chạy dựa trên các chú thích và trình chuyển đổi.

Vòng đời yêu cầu

Khi một phương thức API được gọi, Retrofit tạo một đối tượng Request dựa trên các chú thích và đối số. Yêu cầu được chuyển đến OkHttp để thực thi. Sau khi nhận được phản hồi, thư viện chuyển nó đến Converter.Factory để chuyển đổi thành kiểu cần thiết. CallAdapter bao bọc kết quả trong một wrapper bất đồng bộ. Mỗi giai đoạn có thể được tùy chỉnh.

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)

Cài đặt và cấu hình Retrofit

Cài đặt Retrofit được thực hiện qua Gradle — hệ thống xây dựng tiêu chuẩn của Android. Thư viện được phân phối qua Maven Central và yêu cầu thêm một số phụ thuộc vào build.gradle của dự án.

Thêm phụ thuộc

Trong tệp build.gradle (cấp mô-đun), hãy thêm các phụ thuộc cho Retrofit, trình chuyển đổi Gson và OkHttp. Nên trích xuất các phiên bản thư viện vào các biến trong build.gradle gốc để quản lý tập trung. Retrofit 2 yêu cầu tối thiểu 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"
}

Tạo phiên bản Retrofit

Một phiên bản Retrofit được tạo qua Builder. Các tham số bắt buộc: baseUrl và ConverterFactory. Nên sử dụng singleton cho Retrofit và OkHttpClient để tránh tạo các kết nối dư thừa. Thêm logging-interceptor giúp đơn giản hóa việc gỡ lỗi các yêu cầu mạng trong quá trình phát triển.

Đối với các dự án Kotlin, nên sử dụng hàm suspend trong giao diện API thay vì các kiểu Call. Điều này đơn giản hóa mã và cho phép sử dụng tính đồng thời có cấu trúc của coroutines. Khi chuyển từ Call sang suspend, bạn chỉ cần thay đổi kiểu trả về trong giao diện — phần còn lại của mã tự động thích ứng.

Ví dụ sử dụng Retrofit

Các ví dụ dưới đây minh họa các kịch bản điển hình khi làm việc với Retrofit trong ứng dụng Android: từ một yêu cầu GET đơn giản đến tải tệp lên máy chủ.

Yêu cầu GET với tham số truy vấn

Một yêu cầu GET đơn giản với tham số chuỗi truy vấn là một thao tác cơ bản. Chú thích @Query tự động thêm tham số vào URL và hàm suspend cho phép gọi yêu cầu từ một coroutine mà không chặn luồng chính.

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

val users = api.getUsers(page = 1)

Yêu cầu POST với nội dung JSON

Một yêu cầu POST với nội dung JSON sử dụng chú thích @Body để truyền đối tượng. GsonConverterFactory tự động tuần tự hóa đối tượng User thành JSON. Coroutines Kotlin đảm bảo yêu cầu được thực thi trong luồng nền mà không cần giao diện Callback.

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)

Tải tệp lên qua Multipart

Chú thích @Multipart với @Part cho phép tải tệp lên máy chủ. Retrofit tự động tạo yêu cầu multipart với các tiêu đề cần thiết. OkHttp quản lý tiến trình tải lên qua RequestBody, cho phép hiển thị chỉ báo cho người dùng.

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)

Xử lý lỗi và bộ chặn trong Retrofit

Xử lý lỗi trong Retrofit được xây dựng trên sự kết hợp của cơ chế OkHttp và coroutines Kotlin. Các bộ chặn OkHttp cho phép ghi log yêu cầu, thêm tiêu đề xác thực và xử lý lỗi trước khi chúng đến mã ứng dụng.

Để xử lý lỗi tập trung, một wrapper xung quanh các lời gọi API thường được tạo dưới dạng lớp sealed Result. Lớp này có hai lớp con: Success với dữ liệu và Error với ngoại lệ. ViewModel nhận được kết quả thống nhất và có thể hiển thị trạng thái giao diện người dùng tương ứng mà không cần sao chép mã xử lý lỗi trong mỗi hàm.

Bộ chặn có hai loại: bộ chặn ứng dụng sửa đổi yêu cầu trước khi gửi đến máy chủ và bộ chặn mạng làm việc với phản hồi sau khi nhận được. Ví dụ, một bộ chặn có thể tự động làm mới token truy cập khi nhận được 401 và lặp lại yêu cầu với token mới mà không cần sự tham gia của nhà phát triển.

Ghi log yêu cầu qua Interceptor

Bộ chặn ghi log HttpLoggingInterceptor là một công cụ không thể thiếu khi gỡ lỗi các yêu cầu mạng. Nó xuất ra Logcat phương thức yêu cầu, URL, tiêu đề, nội dung và mã phản hồi. Mức ghi log có thể được cấu hình: BASIC cho thông tin tối thiểu, HEADERS cho tiêu đề hoặc BODY cho nội dung đầy đủ. Trong sản xuất, nên sử dụng BASIC hoặc tắt hoàn toàn tính năng ghi log.

Bộ chặn trong OkHttp được chia thành hai loại: bộ chặn ứng dụng để sửa đổi yêu cầu và bộ chặn mạng để làm việc với dữ liệu mạng thô. Bộ chặn ghi log tự động xuất chi tiết yêu cầu và phản hồi ra Logcat.

Xử lý lỗi ở cấp coroutine được thực hiện qua try-catch xung quanh lời gọi hàm suspend. Retrofit trả về lỗi dưới dạng HttpException cho mã 4xx và 5xx, UnknownHostException khi không có mạng và SocketTimeoutException khi vượt quá thời gian chờ. Nên sử dụng lớp sealed Result để xử lý thống nhất.