کار با کتابخانه Retrofit

امروزه کمتر اپلیکیشنی را می‌توان یافت که به ارتباط با سرور و ارسال و دریافت اطلاعات بی نیاز باشد. فرایند دریافت لیست محصولات یک فروشگاه آنلاین، ثبت سفارش مشتری و پرداخت آن همگی نیاز به برقراری ارتباط بین کلاینت (یعنی دستگاه کاربر) و سرور را دارد. مدیریت این ارتباط به صورت دستی مستلزم تخصص و صرف وقت فراوان بوده که می‌تواند باعث بروز مشکلات متعدد نیز بشود. برای حل این مشکل کتابخانه‌های متعددی توسعه داده شده که برنامه نویس را از نوشتن صدها خط کد پیچیده و درگیر شدن با جزئیات بی نیاز کرده است. در این بخش ابتدا به معرفی کتابخانه Retrofit نسخه ۲ پرداخته سپس در قالب یک مثال ساده به تشریح جزئیات آن می‌پردازیم که شامل مباحث زیر می باشد:

این مبحث در قالب PDF و در ۳۶ صفحه تهیه شده که در ادامه چند صفحه‌ی ابتدایی آن را مشاهده می کنید:

به‌نام خدا. در مبحث گذشته با مفهوم وب سرویس و کاربردهای آن آشنا شدیم. در این جلسه به معرفی کتابخانه قدرتمند Retrofit پرداخته و در قالب یک مثال خیلی ساده، نحوه کار با آن را تشریح می‌کنیم.

معرفی کتابخانه Retrofit 2

کافیست فقط چند ثانیه به کاربرد وب سرویس برای ارتباط یک اپلیکیشن اندرویدی با سرور فکر کنید. چندین مثال به ذهنتان خطور خواهد کرد. از اپلیکیشن‌های فروشگاهی گرفته تا سرویس‌ها و بازی‌های آنلاین که همگی نیازمند ارسال و دریافت داده‌ها از یک سرور در بستر اینترنت هستند.
پیاده سازی قابلیت ارتباط بین سرور و اپلیکیشن به روش دستی و نوشتن کامل کدها بسیار پیچیده و زمان‌گیر بوده و همواره می‌بایست پارامترهای متعددی مانند ساخت کانکشن، ارسال مجدد درخواست‌های ناموفق، تردها (Thread)، ارورها، Parse (تجزیه) کردن پاسخ و…را خودمان هندل (مدیریت) کنیم. بنابراین بهتر است سراغ کتابخانه‌هایی برویم که توسط شرکت‌های معتبر منتشر و پشتیبانی می‌شوند. کتابخانه Retrofit یکی از این کتابخانه هاست. رتروفیت توسط شرکت Square پشتیبانی می‌شود.

Retrofit یک HTTP client امن برای جاوا و اندروید است که به واسطه آن، ارتباط از نوع HTTP بین سرور و کلاینت (اپلیکیشن) برقرار می‌شود. در واقع از رتروفیت برای اتصال به وب سرویس از طریق HTTP Connection استفاده می‌شود.
کتابخانه Volley (والی) را می‌توان به عنوان رقیب اصلی Retrofit معرفی کرد. والی توسط گوگل پشتیبانی می‌شود. در حال حاضر Retrofit به دلیل مزایایی که نسبت به Volley دارد در بین توسعه دهندگان اندروید سهم بیشتری را به خود اختصاص داده. مدتی از ارائه نسخه ۲ کتابخانه Retrofit می‌گذرد که نسبت به نسخه ۱ تغییرات گسترده ای به همراه داشته که علاوه بر سهولت بیشتر در پیاده سازی نسبت به نسخه قبل، امکانات جدیدی نیز در اختیار توسعه دهنده قرار می‌دهد.
توجه داشته باشید استفاده از Retrofit به معنی نفی Volley یا سایر کتابخانه‌های مشابه نیست. هر شخصی برای انتخاب یک گزینه دلایلی دارد. اصلی ترین دلایل من برای انتخاب رتروفیت، سهولت در پیاده سازی و سرعت بالاتر آن نسبت به والی است. البته وقتی از مقایسه سرعت در این دو کتابخانه صحبت می‌کنیم در واقع تفاوت چیزی در حد چند میلی ثانیه است!
بیشتر از این ذهن شما را درگیر تفاوت‌های این دو کتابخانه نمی‌کنم. اگر مایل هستید بیشتر در مورد مزایا و معایب هرکدام بدانید کافیست چند دقیقه وقت گذاشته و از گوگل کمک بگیرید:
” Retrofit vs Volley” یا “مقایسه Retrofit و Volley”
بیشتر از این شما را غرق تعاریف نمی‌کنم. مابقی نکات و توضیحات را در حین کار با پروژه ذکر می‌کنم.
همانطور که ابتدای مبحث اشاره شد، می‌خواهم این بخش را با یک مثال خیلی ساده پیش ببرم تا ذهن شما صرفا درگیر مطالب اصلی و پایه شود.
یک پروژه با نام SimpleRetrofit و یک Empty Activity ایجاد می‌کنم. کاری که در این پروژه انجام می‌دهیم، دریافت داده ها در قالب JSON و نمایش آنها درون یک ListView است.
اگر بخاطر داشته باشید در مبحث گذشته به این نکته اشاره شد که در اندروید از فرمت JSON برای تبادل داده بین وب سرویس و کلاینت (دیوایس کاربر) استفاده می‌شود. البته استفاده از فرمت‌ XML نیز امکان‌پذیر است اما دلایل متعددی وجود دارد که توسعه دهندگان را ترغیب به استفاده از JSON می‌کند.

JSON چیست؟

JSON (مخفف Javascript Object Notation) (تلفظ: جِی‌سُن یا جِی‌سان) یک فرمت بسیار سبُک و ساده برای ذخیره و تبادل اطلاعات است که خواندن و نوشتن آن برای انسان و تولید و Parse (تجزیه) کردن آن برای ماشین‌ها آسان است. JSON بصورت text (متنی) بوده و مستقل از زبان‌های برنامه نویسی است. یعنی تفاوتی نمی‌کند اپلیکیشن اندرویدی ما یا وب سرویسی که قرار است به این اپلیکیشن متصل شود و داده ارسال و دریافت کند، با چه زبان‌های نوشته شده اند زیرا تمام زبان‌های برنامه نویسی روز دنیا مانند Java، PHP، C#، Python و… از JSON پشتیبانی می‌کنند.
در گذشته برای تبادل اطلاعات از فرمت XML استفاده می‌شد که با معرفی فرمت JSON توسط Douglas Crockford در سال ۲۰۰۰، نظر اکثر برنامه نویسان را به خود جلب کرد.
به کدهای زیر دقت کنید:

کد اول در فرمت JSON و کد دوم در فرمت XML نوشته شده. هردو اطلاعات یکسانی را نشان می‌دهند که شامل نام و نام خانوادگی سه دانشجو است. اما همانطور که ملاحظه می‌کنید کدهای XML از پیچیدگی بالاتری نسبت به JSON برخوردار بوده و درنتیجه حجم بیشتری را نیز اشغال می‌کند. علاوه بر این، خوانایی XML نیز در مقایسه با JSON برای انسان مقداری سخت‌تر است. بنابراین منطقی ست گزینه ای را انتخاب کنیم که حجم کمتر و در نهایت نیز پهنای باند کمتری را برای انتقال اطلاعات مصرف کند.
در ادامه به بررسی ساختار JSON می‌پردازم.
در JSON یک شیء (Object) یک مجموعه از زوج‌های نام/مقدار (name/value) است. یک object با { (آکولاد باز) شروع، و با } (آکولاد بسته) تمام می‌شود. در انتهای هر نام یک علامت : (دو نقطه) قرار می‌گیرد و زوج‌های نام/مقدار با علامت , (ویرگول) جدا می‌شوند.

نمونه کد زیر، ساده ترین حالت JSON است. یک Object با یک جفت نام/مقدار:

در کد فوق یک جفت نام/مقدار مشاهده می‌کنید که نام آن “city” و مقدارش “Ferdows” است. دقت کنید نام و مقدار هردو داخل “” قرار گرفته اند زیرا هردو از جنس string هستند. نام همیشه باید یک string باشد اما مقدار می‌تواند رشته (string)، اعداد (number)، آبجکت (object)، آرایه (array)، مقدار بولی (true/false) و یا نال (null) باشد:

کد زیر یک آبجکت با ۴ جفت زوج نام/مقدار است که اطلاعات مربوط به یک شخص را نشان می‌دهد:

در انتهای نام/مقدار age نباید علامت “,” بکار ببریم زیرا بعد از آن نام/مقدار دیگری نیست.
طبق تعریفی که کردیم، مقدار (value) خود می‌تواند یک Object دیگر باشد:

در کد فوق، نام products (به معنی محصولات) در قسمت مقدار دارای یک آبجکت است که این آبجکت ۳ جفت نام/مقدار شامل نام محصولات کشاورزی می‌باشد.
اطلاعات ممکن است از این هم پیچیده‌تر باشند. مثلا یک لیست از دانشجوها که شامل نام و نام خانوادگی، شماره دانشجویی و کد ملی است. در اینجا لازم است مقادیر در قالب آرایه (array) تعریف شوند.
یک آرایه با [ (براکت باز) شروع، و با ] (براکت بسته) تمام می‌شود. مقدارها نیز توسط “,” از یکدیگر جدا می‌شوند.

در کد فوق یک آبجکت داریم که شامل یک جفت نام/مقدار است که این مقدار خود شامل یک آرایه با چهار آبجکت می‌باشد.

خب! به اندازه کافی با فرمت JSON آشنا شدیم. به محیط پروژه برمی‌گردم. می‌خواهم نام چند شهر در استان‌های خراسان را از طریق یک سرور دریافت و درون اپلیکیشن نمایش دهم.
ابتدا یک فایل جی‌سون ایجاد می‌کنم. من نام این فایل را city.json گذاشتم. درون این فایل یک آرایه با ۵ آبجکت است که درون هر آبجکت یک جفت نام/مقدار قرار گرفته:

فایل جی‌سون را روی فضای مربوط به فایل‌های دانلودی وب‌سایت اندروید استودیو آپلود می‌کنم. URL فایل به اینصورت است:

http://dl.android-studio.ir/files/city.json

با کلیک روی لینک، محتوای فایل روی مرورگر نمایش داده می‌شود. تمامی مرورگرها از فرمت JSON پشتیبانی می‌کنند.

در مرورگر فایرفاکس برای محتوای جی‌سون سه تب تعریف شده که به ترتیب JSON، Raw Data و Headers هستند. در تب اول محتوا بر اساس ساختار جی‌سون مرتب می‌شود و اثری از علامت‌های آکولاد، براکت و ویرگول نیست. می‌توان با کلیک روی هر آبجکت، آنها را باز و بسته کرد. همانطور که مشاهده می‌کنید آبجکت‌ها به ترتیب شماره گذاری شده اند. اما در حالت Raw Data اطلاعات عینا مطابق آنچه در ادیتور دیدیم نمایش داده می‌شود:

فایل جی‌سون را بدون آپلود روی هاست و سرور هم می‌توان روی مرورگر باز کرد. کافیست آدرس فایل روی سیستم خود را در قسمت آدرس‌بار مرورگر وارد کنید:

حتما با Permission (مجوز دسترسی) در اندروید آشنا هستید. کاربر هنگام نصب اپلیکیشن روی دیوایس خود، دسترسی‌های اپ را مشاهده و تایید می‌کند. یکی از این مجوزها دسترسی به شبکه و اینترنت است. ما در این پروژه می‌خواهیم لیست شهرها را از یک سرور دریافت کنیم بنابراین ابتدا باید مجوز دسترسی به اینترنت را تعریف کنیم. اینکار در AndroidManifest.xml انجام می‌شود:

<uses-permission android:name="android.permission.INTERNET" />

یک تگ با نام uses-permission و مقدار android.permission.INTERNET به مانیفست اضافه شد. حالا اپلیکیشن ما امکان اتصال و تبادل اطلاعات از طریق شبکه و اینترنت را دارد.
AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.simpleretrofit">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

در قدم بعد باید کتابخانه Retrofit را به پروژه اضافه کنیم.
صفحه رسمی کتابخانه:

https://square.github.io/retrofit/

صفحه گیت‌هاب:

https://github.com/square/retrofit

کافیست خط بالا را از انتهای صفحه معرفی کتابخانه کپی کرده و به build.gradle (app) پروژه اضافه کنیم (ممکن است زمانی که شما در حال مطالعه این آموزش هستید نسخه جدیدتری از این کتابخانه منتشر شده باشد).

همانطور که قبلا اشاره شد، رتروفیت مدیریت دریافت و ارسال اطلاعات بین دیوایس و وب سرویس را برعهده دارد. اما رتروفیت به طور مستقل نمی‌تواند داده‌های دریافتی از وب سرویس را درک کند یا داده ها را به فرمتی که برای وب سرویس قابل پذیرش است ارسال کند. در اینجا باید از تبدیل کننده‌هایی که بازهم ساخت شرکت Square هستند استفاده کنیم.
در صفحه گیت‌هاب Retrofit قسمتی با نام Converters وجود دارد که لیست کتابخانه‌های مبدل برای فرمت‌های JSON و XML را نشان می‌دهد:

ما با JSON سروکار داریم بنابراین باید علاوه بر رتروفیت، کتابخانه Gson Converter را هم به پروژه اضافه کنیم.
به قسمت retrofit-converters و سپس gson در صفحه گیت‌هاب رتروفیت می‌روم:

Retrofit Gson Converter خود از کتابخانه Gson گوگل استفاده می‌کند. وظیفه این کتابخانه تبدیل داده‌های Java به Json و بلعکس است.

پس تا اینجا وظایف این دو کتابخانه برای ما روشن شد. Retrofit اطلاعاتی که می‌بایست از به سرور ارسال شود را در فرمت Java به کتابخانه Gson Converter ‌می‌فرستد. سپس Gson Converter اطلاعات را به فرمت JSON تبدیل کرده و به سرور ارسال می‌کند. همینطور اطلاعاتی که باید از سرور به دیوایس ارسال شود ابتدا با فرمت JSON به Gson Converter می‌رسد. این کتابخانه اطلاعات را از JSON به Java تبدیل کرده و به Retrofit انتقال می‌دهد.
ملاحظه می‌کنید خط مربوط به Gradle، در قسمت ورژن بجای عدد latest.version قید شده که با کلیک روی لینک the latest JAR یا Maven عدد را پیدا می‌کنیم:

در زمان تهیه این آموزش، نسخه نهایی ۲٫۴٫۰ است.
بعد از retrofit این کتابخانه را هم به پروژه اضافه و سینک می‌کنم تا کتابخانه‌ها از مخزن آنلاین، دانلود شوند:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.squareup.retrofit2:retrofit:2.4.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
}

می‌خواهیم نام چند شهر در قالب یک ListView نمایش داده شود لذا یک کلاس Model با نام City به پروژه اضافه می‌کنم. آبجکت‌های JSON ای که از سرور دریافت می‌کنیم یک نام/مقدار با عنوان name و از جنس String هستند. بنابراین name را درون این کلاس تعریف کرده، سپس متد سازنده (Constructor) و Getter آنرا نیز ایجاد می‌کنم. در این پروژه فقط دریافت اطلاعات از سرور داریم بنابراین فقط به Getter نیاز خواهیم داشت. ساخت Constructor و Getter بدون نیاز به نوشتن دستی کدها و از طریق کلیدهای میانبر alt + insert امکانپذیر است که در مباحث قبل آشنا شدیم.

جهت مطالعه ادامه آموزش، فایل PDF را دانلود نمائید

توجه : سورس پروژه به همراه فایل آموزشی داخل پوشه Exercises قرار داده شده است.

با توجه به اینکه آموزشهای پایه با قیمت پایین در اختیار کاربر قرار گرفته و درآمد حاصل صرف تامین هزینه های وب سایت و تهیه آموزش های آتی می شود، به اشتراک گذاری این فایل با دیگران خلاف اخلاق می‌باشد.