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

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

آنچه در این آموزش می‌خوانید:

  • معرفی کتابخانه Retrofit
  • معرفی فرمت JSON (جی سون) و آشنایی با ساختار آن
  • مقایسه JSON با XML
  • معرفی سرویس‌های صحت سنجی کد JSON
  • تشریح HTTP URL و baseUrl در Retrofit
  • تعیین حق دسترسی اپلیکیشن اندرویدی جهت اتصال به اینترنت
  • معرفی کتابخانه مبدل Gson Converter
  • نحوه دریافت اطلاعات با فرمت JSON از وب سرور و نمایش آنها در قالب ListView
  • آشنایی با متدهای GET و Call و addConverterFactory در رتروفیت
  • آشنایی با متد enqueue و دو حالت onResponse و onFailure
  • معرفی سرویس‌های fake JSON Server برای ساخت وب سرور آزمایشی
  • آشنایی با وب سرور محلی (local) جهت استفاده بجای وب سرور حقیقی
  • آشنایی با WampServer جهت راه اندازی وب سرور محلی و نحوه کار با آن
  • دریافت داده‌های JSON از روی لوکال بجای دریافت از سرور حقیقی در بستر اینترنت

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

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

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

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

تذکر: Parse در لغت به معنی تجزیه است. در زبان‌های برنامه نویسی هم parse کردن یعنی تجزیه کردن داده‌های گرفته شده. مانند پروژه همین مبحث که اپلیکیشن ما داده ها را با فرمت JSON از سرور دریافت کرده سپس به فرمتی تجزیه می‌کند که برای زبان Java قابل فهم باشد.

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

مقایسه فرمت JSON و XML

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

آبجکت JSON

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

مثال ساده کد JSON

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

JSON Value

نکته: داده‌های JSON با پسوند .json ذخیره می‌شوند. کافیست یک فایل متنی ایجاد کنید و .txt را به .json تغییر نام دهید. یا از ادیتوری مثل ++Notepad استفاده کنید.

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

آبجکت ساده جی سون

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

مقدارهای مجاز در JSON

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

آرایه ها در JSON

آرایه در جی سون

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

نکته: آبجکت‌ها و آرایه‌ها تا بی‌نهایت می‌تواند تو در تو باشد. به عنوان مثال بجای مقدار Saffron می‌توان یک آبجکت ساخت و انواع زعفران را لیست کرد.
نکته: سرویس‌های متعددی برای بررسی صحت کد JSON به صورت آنلاین در دسترس هستند که این امکان را به ما می‌دهد تا بتوانیم خطاهای کدی که نوشته ایم را بیابیم. کافیست json validator را گوگل کنید. https://jsonformatter.curiousconcept.com و https://jsonlint.com دو نمونه از این سرویس‌های رایگان هستند. در وب‌سایت اول پس از صحت سنجی کد، ساختار جی‌سون را نیز نمایش می‌دهد.

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

آرایه در JSON

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

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

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

نمایش محتوای JSON روی مرورگر

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

نمایش جی سون در حالت Raw Data روی مرورگر

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

نمایش JSON روی مرورگر از آدرس لوکال

حتما با 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

اضافه کردن کتابخانه Retrofit به پروژه اندرویدی در gradle

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

نکته: گاهی ممکن است بجای ذکر عدد مربوط به آخرین نسخه منتشر شده (مانند عدد ۲٫۴٫۰ در تصویر بالا) عبارت latest.version نمایش داده شود که لازم است برای یافتن عدد مربوط به ورژن نهایی، لینک دانلودی که مربوط به فایل JAR کتابخانه هست را باز کنید.
بعد از کلیک روی لینک یا به صفحه ای در maven.org منتقل می‌شوید که اطلاعات کتابخانه ازجمله ورژن آن را نمایش می‌دهد یا مستقیم شروع به دانلود فایل میکند که عدد مربوط به ورژن در نام فایل دیده می‌شود (مانند retrofit2-2.4.0.jar). در نهایت این عدد را جایگزین latest.version کرده سپس پروژه را Sync کنید.
نکته: Retrofit برای لایه شبکه از کتابخانه Okhttp استفاده می‌کند که این کتابخانه هم توسط Square منتشر شده است. بنابراین نیازی به اضافه کردن Okhttp به طور مجزا در کنار Retrofit نیست مگر آنکه نیاز به نسخه خاصی از Okhttp داشته باشیم و بدانیم هدفمان از اضافه کردن Okhttp در کنار Retrofit دقیقا چیست.

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

مبدل JSON به Java در Retrofit

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

Gson Converter

Retrofit Gson Converter

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

نکته: Gson Converter از کتابخانه Gson گوگل استفاده می‌کند بنابراین نیازی به اضافه کردن Gson گوگل به طور مجزا در کنار Gson Converter نیست.

پس تا اینجا وظایف این دو کتابخانه برای ما روشن شد. 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 قرار داده شده است.

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

دانلود نسخه کامل این آموزش به همراه سورس و فایل‌های پروژه
تعداد صفحات : ۳۶
حجم : ۲ مگابایت
قیمت : ۲۴ هزار تومان
توجه: صرفا در صورتی از درگاه پشتیبان استفاده کنید که قادر به پرداخت از طریق سبد دانلود نباشید.
افزودن به سبد دانلود درگاه پشتیبان
این مطلب چقدر برایتان مفید بود؟ لطفا امتیاز دهید
4.7/5 - (15 امتیاز)
پرسش‌ها و دیدگاه‌های کاربران
دوره آموزش برنامه نویسی اندروید
دوره آموزش برنامه نویسی اندروید

با دریافت این دوره به تمامی آموزش‌های غیر رایگان و رایگان موجود در وب سایت دسترسی دارید که تخفیفی برای آموزش‌های غیر رایگان نیز درنظر گرفته شده. این پکیج به دو صورت دانلودی و ارسال پستی ارائه می‌گردد.
آموزش‌های اندروید استودیو در دو دسته «پایه» و «تکمیلی» منتشر می‌شوند.
آموزش‌های پایه شامل مباحث اصلی و ضروری و آموزش‌های تکمیلی مطالبی است که می‌بایست در کنار مطالب اصلی بررسی شود.
با خرید این دوره، به تمامی آموزش‌های غیر رایگانی که در آینده منتشر می‌شود نیز به صورت رایگان دسترسی خواهید داشت!

یک دیدگاه بنویسید

پرسش‌های زیر تایید و پاسخ داده نـــخواهند شد:
۱: جزء موارد مطرح شده در صفحات مشکلات و پرسش‌های رایج و بروزرسانی‌های محتوای آموزشی باشد
۲: سوال قبلا توسط کاربران در دیدگاه‌ها مطرح و پاسخ داده شده باشد
۳: پرسش خارج از مبحث آموزشی موجود در این صفحه باشد