Retrofit — คืออะไร, ไลบรารี HTTP และการใช้งานในแอปพลิเคชัน

Retrofit คืออะไร?

Retrofit คือไลบรารีสำหรับดำเนินการคำขอ HTTP ในแอปพลิเคชัน Android ที่พัฒนาโดย Square โดยมีวิธีการประกาศเพื่อกำหนด REST API ผ่านอินเทอร์เฟซ Java พร้อมคำอธิบายประกอบ ทำให้โค้ดการโต้ตอบเครือข่ายสะอาดและคาดการณ์ได้

แนวคิดหลักของ Retrofit คือนักพัฒนาอธิบาย API เป็น อินเทอร์เฟซ พร้อมเมธอดและคำอธิบายประกอบ และไลบรารีสร้างการใช้งานโดยอัตโนมัติ วิธีการนี้รับประกันว่า endpoints ทั้งหมดถูกกำหนดชนิด และข้อผิดพลาดใน URL หรือพารามิเตอร์จะถูกตรวจจับในเวลาคอมไพล์ ไม่ใช่เวลารันไทม์

Retrofit รองรับเมธอด HTTP และรูปแบบข้อมูลยอดนิยมทั้งหมด ไลบรารีได้รับการบำรุงรักษา อย่างแข็งขัน โดย Square และชุมชน: เวอร์ชันใหม่ออกเป็นประจำ และเวอร์ชันปัจจุบัน 2.11 รวมการรองรับ Java 17 และ Kotlin 2.0 Retrofit ยังคงเป็น HTTP ไคลเอนต์ยอดนิยมที่สุดสำหรับ Android

Retrofit ทำงานบน OkHttp ซึ่งเป็น HTTP ไคลเอนต์ที่มีประสิทธิภาพจาก Square เช่นกัน การรวมกันนี้ให้การแคช การสกัดกั้นคำขอ และการจัดการการเชื่อมต่อในระดับโปรโตคอลการขนส่ง ไลบรารีรองรับทั้งการเรียกแบบซิงโครนัสและอะซิงโครนัส

นับตั้งแต่เปิดตัวครั้งแรกในปี 2013 Retrofit ผ่านการอัปเดตครั้งใหญ่หลายครั้ง เวอร์ชันปัจจุบัน Retrofit 2 ถูกเขียนใหม่ทั้งหมดจากประสบการณ์ของเวอร์ชันแรก และมีระบบตัวแปลงและอะแดปเตอร์ที่ยืดหยุ่นมากขึ้นสำหรับการทำงานแบบอะซิงโครนัส

สถาปัตยกรรมของ Retrofit เป็นไปตามหลัก การแยก ความรับผิดชอบ: อินเทอร์เฟซกำหนดเฉพาะสัญญา API ตัวแปลงจัดการการซีเรียลไลซ์ และอะแดปเตอร์จัดการการทำงานแบบอะซิงโครนัส ซึ่งช่วยให้เปลี่ยนคอมโพเนนต์ใดก็ได้โดยไม่ต้องเปลี่ยนโค้ดที่เหลือ ตัวอย่างเช่น คุณสามารถเปลี่ยนจาก Gson เป็น Moshi โดยไม่ต้องเปลี่ยนคำจำกัดความของ endpoints

คุณสมบัติหลักของ Retrofit

Retrofit มีชุดคุณสมบัติที่ครอบคลุมสถานการณ์การโต้ตอบเครือข่ายเกือบทั้งหมดในแอปพลิเคชันมือถือ ข้อได้เปรียบหลักคือรูปแบบการประกาศของคำจำกัดความ API

คำอธิบายประกอบ endpoints แบบประกาศ

คำอธิบายประกอบ @GET, @POST, @PUT, @PATCH, @DELETE และ @HTTP ช่วยระบุเมธอด HTTP และเทมเพลต URL โดยตรงในอินเทอร์เฟซ พารามิเตอร์เส้นทางกำหนดผ่าน @Path พารามิเตอร์คำค้นหาผ่าน @Query และเนื้อหาคำขอผ่าน @Body วิธีการนี้ทำให้ชั้น API ของแอปพลิเคชันถูกกำหนดชนิดอย่างสมบูรณ์

ตัวแปลงสำหรับการซีเรียลไลซ์

ตัวแปลง แปลงการตอบสนอง HTTP เป็นออบเจกต์ Java และในทางกลับกัน Retrofit รองรับ Gson, Moshi, Jackson, Protobuf และ Wire นักพัฒนาเชื่อมต่อตัวแปลงที่ต้องการผ่าน Converter.Factory และไลบรารีใช้โดยอัตโนมัติกับคำขอและการตอบสนองทั้งหมด

อะแดปเตอร์สำหรับการทำงานแบบอะซิงโครนัส

อะแดปเตอร์ CallAdapter ช่วยเปลี่ยนชนิดส่งคืนของเมธอด API แทนที่จะใช้ Call มาตรฐาน สามารถใช้ Observable สำหรับ RxJava, Deferred สำหรับ coroutines ของ Kotlin หรือ LiveData ซึ่งรวมคำขอเครือข่ายเข้ากับสถาปัตยกรรมแอปพลิเคชันที่เลือก

URL แบบไดนามิกและส่วนหัว

URL แบบไดนามิก กำหนดผ่านคำอธิบายประกอบ @Url ซึ่งช่วยให้ส่ง endpoint ในเวลารันไทม์ ส่วนหัวสามารถระบุแบบคงที่ผ่าน @Headers หรือแบบไดนามิกผ่านพารามิเตอร์ @Header สำหรับส่วนหัวส่วนกลางของคำขอทั้งหมด จะใช้อินเตอร์เซปเตอร์ OkHttp ที่เพิ่มส่วนหัวให้กับทุกคำขอขาออก

Retrofit ทำงานอย่างไร?

Retrofit ทำงานในสามขั้นตอน: การกำหนดอินเทอร์เฟซ API การสร้างอินสแตนซ์ Retrofit และการดำเนินการคำขอ ไลบรารีสร้างการใช้งานอินเทอร์เฟซในเวลารันไทม์ตามคำอธิบายประกอบและตัวแปลง

วงจรชีวิตของคำขอ

เมื่อเรียกเมธอด API Retrofit สร้างออบเจกต์ Request ตามคำอธิบายประกอบและอาร์กิวเมนต์ คำขอถูกส่งไปยัง OkHttp เพื่อดำเนินการ หลังจากได้รับการตอบสนอง ไลบรารีส่งไปยัง Converter.Factory เพื่อแปลงเป็นชนิดที่ต้องการ CallAdapter ห่อผลลัพธ์ใน wrapper แบบอะซิงโครนัส แต่ละขั้นตอนสามารถปรับแต่งได้

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)

การติดตั้งและกำหนดค่า Retrofit

การติดตั้ง Retrofit ทำผ่าน Gradle ซึ่งเป็นระบบบิวด์มาตรฐานของ Android ไลบรารีเผยแพร่ผ่าน Maven Central และต้องการเพิ่ม dependencies หลายรายการใน build.gradle ของโปรเจกต์

การเพิ่ม dependencies

ในไฟล์ build.gradle (ระดับโมดูล) เพิ่ม dependencies สำหรับ Retrofit ตัวแปลง Gson และ OkHttp แนะนำให้แยกเวอร์ชันไลบรารีเป็นตัวแปรใน build.gradle ระดับรากเพื่อการจัดการแบบรวมศูนย์ Retrofit 2 ต้องการอย่างน้อย 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"
}

การสร้างอินสแตนซ์ Retrofit

อินสแตนซ์ Retrofit สร้างผ่าน Builder พารามิเตอร์บังคับ: baseUrl และ ConverterFactory แนะนำให้ใช้ซิงเกิลตันสำหรับ Retrofit และ OkHttpClient เพื่อหลีกเลี่ยงการสร้างการเชื่อมต่อที่ซ้ำซ้อน การเพิ่ม logging-interceptor ช่วยให้การดีบักคำขอเครือข่ายง่ายขึ้นระหว่างการพัฒนา

สำหรับโปรเจกต์ Kotlin แนะนำให้ใช้ ฟังก์ชัน suspend ในอินเทอร์เฟซ API แทนชนิด Call ซึ่งทำให้โค้ดง่ายขึ้นและช่วยใช้การทำงานพร้อมกันแบบมีโครงสร้างของ coroutines เมื่อเปลี่ยนจาก Call เป็น suspend เพียงเปลี่ยนชนิดส่งคืนในอินเทอร์เฟซ — โค้ดที่เหลือปรับตัวโดยอัตโนมัติ

ตัวอย่างการใช้งาน Retrofit

ตัวอย่าง ด้านล่างแสดงสถานการณ์ทั่วไปของการทำงานกับ Retrofit ในแอปพลิเคชัน Android: จากคำขอ GET ง่ายไปจนถึงการอัปโหลดไฟล์ไปยังเซิร์ฟเวอร์

คำขอ GET พร้อมพารามิเตอร์คำค้นหา

คำขอ GET อย่างง่ายพร้อมพารามิเตอร์สตริงคำค้นหาเป็นการดำเนินการพื้นฐาน คำอธิบายประกอบ @Query เพิ่มพารามิเตอร์ใน URL โดยอัตโนมัติ และฟังก์ชัน suspend ช่วยให้เรียกคำขอจาก coroutine โดยไม่บล็อกเธรดหลัก

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 พร้อมเนื้อหา JSON

คำขอ POST พร้อมเนื้อหา JSON ใช้คำอธิบายประกอบ @Body เพื่อส่งออบเจกต์ GsonConverterFactory ซีเรียลไลซ์ออบเจกต์ User เป็น JSON โดยอัตโนมัติ coroutines ของ Kotlin รับประกันการดำเนินการคำขอในเธรดพื้นหลังโดยไม่ต้องใช้อินเทอร์เฟซ Callback

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

val user = User(name = "แอนนา อิวาโนวา", email = "anna@example.com")
val created = api.createUser(user)

การอัปโหลดไฟล์ผ่าน Multipart

คำอธิบายประกอบ @Multipart กับ @Part ช่วยอัปโหลดไฟล์ไปยังเซิร์ฟเวอร์ Retrofit สร้างคำขอ multipart โดยอัตโนมัติพร้อมส่วนหัวที่จำเป็น OkHttp จัดการความคืบหน้าการอัปโหลดผ่าน RequestBody ซึ่งช่วยให้แสดงตัวบ่งชี้ให้ผู้ใช้เห็น

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)

การจัดการข้อผิดพลาดและอินเตอร์เซปเตอร์ใน Retrofit

การจัดการ ข้อผิดพลาดใน Retrofit สร้างขึ้นบนการรวมกันของกลไก OkHttp และ coroutines ของ Kotlin อินเตอร์เซปเตอร์ OkHttp ช่วยบันทึกคำขอ เพิ่มส่วนหัวการตรวจสอบสิทธิ์ และจัดการข้อผิดพลาดก่อนที่จะถึงโค้ดแอปพลิเคชัน

สำหรับการจัดการข้อผิดพลาดแบบรวมศูนย์ มักสร้าง wrapper รอบการเรียก API เป็น sealed class Result คลาสดังกล่าวมีสองสืบทอด: Success พร้อมข้อมูลและ Error พร้อมข้อยกเว้น ViewModel รับผลลัพธ์ที่รวมเป็นหนึ่งและสามารถแสดงสถานะอินเทอร์เฟซผู้ใช้ที่สอดคล้องกันโดยไม่ต้องทำซ้ำโค้ดจัดการข้อผิดพลาดในแต่ละฟังก์ชัน

อินเตอร์เซปเตอร์ มีสองประเภท: อินเตอร์เซปเตอร์ระดับแอปพลิเคชันปรับเปลี่ยนคำขอก่อนส่งไปยังเซิร์ฟเวอร์ และอินเตอร์เซปเตอร์ระดับเครือข่ายทำงานกับการตอบสนองหลังจากได้รับ ตัวอย่างเช่น อินเตอร์เซปเตอร์สามารถรีเฟรชโทเคนการเข้าถึงโดยอัตโนมัติเมื่อได้รับ 401 และทำซ้ำคำขอด้วยโทเคนใหม่โดยไม่ต้องให้นักพัฒนามีส่วนร่วม

การบันทึกคำขอผ่าน Interceptor

อินเตอร์เซปเตอร์บันทึก HttpLoggingInterceptor เป็นเครื่องมือที่ขาดไม่ได้สำหรับการดีบักคำขอเครือข่าย โดยแสดงเมธอดคำขอ URL ส่วนหัว เนื้อหา และรหัสการตอบสนองใน Logcat ระดับการบันทึกสามารถกำหนดค่าได้: BASIC สำหรับข้อมูลขั้นต่ำ HEADERS สำหรับส่วนหัว หรือ BODY สำหรับเนื้อหาเต็ม ในโพรดักชัน แนะนำให้ใช้ BASIC หรือปิดการบันทึกทั้งหมด

อินเตอร์เซปเตอร์ ใน OkHttp แบ่งเป็นสองประเภท: อินเตอร์เซปเตอร์ระดับแอปพลิเคชันสำหรับปรับเปลี่ยนคำขอ และอินเตอร์เซปเตอร์ระดับเครือข่ายสำหรับทำงานกับข้อมูลเครือข่ายดิบ อินเตอร์เซปเตอร์บันทึกแสดงรายละเอียดคำขอและการตอบสนองใน Logcat โดยอัตโนมัติ

การจัดการ ข้อผิดพลาดในระดับ coroutine ดำเนินการผ่าน try-catch รอบการเรียกฟังก์ชัน suspend Retrofit ส่งคืนข้อผิดพลาดเป็น HttpException สำหรับรหัส 4xx และ 5xx UnknownHostException เมื่อไม่มีเครือข่าย และ SocketTimeoutException เมื่อเกินเวลาที่กำหนด แนะนำให้ใช้ sealed class Result สำหรับการจัดการแบบรวม