Retrofit لجافا: عميل HTTP آمن للأنواع لتطبيقات Android وJava

1. ما هي مكتبة Retrofit ولماذا تحتاجها؟

Retrofit هي مكتبة قوية وأنيقة للغة Java (وأندرويد)، تحول واجهات HTTP البرمجية (API) إلى واجهة Java بسيطة. بدلاً من كتابة كود متكرر لإنشاء طلبات HTTP ومعالجة الردود وتحليل JSON، تقوم Retrofit بكل هذا العمل نيابة عنك. تقوم تلقائياً بتحويل كائنات Java إلى JSON (أو تنسيق آخر) لإرسالها إلى الخادم، وتحويل ردود الخادم مرة أخرى إلى كائنات Java. هذا يجعل الكود نظيفاً وسهل القراءة والصيانة.

لماذا تحتاجها؟ تخيل أنك تريد بناء تطبيق يتواصل مع REST API (مثل GitHub API أو OpenWeatherMap أو خادمك الخاص). بدون Retrofit، ستضطر لاستخدام كلاسيات منخفضة المستوى مثل HttpURLConnection أو HttpClient، وبناء عناوين URL يدوياً، وتعيين الترويسات (Headers)، ومعالجة أكواد الأخطاء، وتحليل JSON. هذا ليس فقط مملاً، بل أيضاً عرضة للأخطاء. Retrofit تحل هذه المشاكل بتوفير طريقة تعريفية لوصف API. كل ما عليك فعله هو إنشاء واجهة (Interface) مع دوال (Methods) وإضافة التعليقات التوضيحية (مثل @GET، @POST)، وستقوم Retrofit بتوليد تنفيذ هذه الواجهة تلقائياً.

Retrofit هي المعيار الفعلي للعمل مع HTTP في عالم Android وJava. تتكامل بشكل وثيق مع OkHttp (لإدارة الشبكة بكفاءة) وGson/Moshi (لتحويل JSON). تدعم المكتبة الطلبات المتزامنة وغير المتزامنة، رفع الملفات، المصادقة، التخزين المؤقت، والعديد من الميزات الأخرى. بفضل بساطتها ومرونتها، تُستخدم Retrofit في آلاف التطبيقات والخدمات حول العالم.

2. طريقة التثبيت

يتم توزيع Retrofit عبر Maven Central. لاستخدامها في مشروع Java الخاص بك (مع Maven أو Gradle)، أضف التبعيات (Dependencies) المناسبة. لاحظ أنك ستحتاج أيضاً إلى محول (Converter) للتحويل التسلسلي (غالباً Gson أو Moshi) ومكتبة OkHttp نفسها (التي تستخدمها Retrofit داخلياً).

Maven (pom.xml)

<!-- Retrofit -->
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.9.0</version>
</dependency>

<!-- محول Gson (لـ JSON) -->
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.9.0</version>
</dependency>

<!-- OkHttp (عادةً ما يتم جلبها تلقائياً، ولكن يمكن تحديد الإصدار صراحةً) -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

Gradle (build.gradle)

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

ملاحظة مهمة: قد تصبح الإصدارات قديمة. تحقق دائماً من أحدث الإصدارات على الموقع الرسمي أو في مستودع Maven Central. إذا كنت تستخدم محولاً آخر (مثل Moshi أو Jackson)، استبدل converter-gson بالقطعة الأثرية المناسبة (converter-moshi، converter-jackson).

3. البداية السريعة — مثال عملي بسيط

لنكتب مثالاً بسيطاً لجلب قائمة المستخدمين من خادم JSONPlaceholder (REST API تجريبي).

الخطوة 1: إنشاء نموذج البيانات (POJO)

// User.java
public class User {
    private int id;
    private String name;
    private String username;
    private String email;

    // دوال الحصول (Getters) - إلزامية لـ Gson
    public int getId() { return id; }
    public String getName() { return name; }
    public