מבוא לחידוש
1. סקירה כללית
Retrofit הוא לקוח HTTP בטוח מסוג Android ו- Java - שפותח על ידי Square (Dagger, Okhttp).
במאמר זה נסביר כיצד להשתמש ב- Retrofit, תוך התמקדות בתכונות המעניינות ביותר שלו. במיוחד יש לדון בממשק ה- API הסינכרוני והאסינכרוני, כיצד להשתמש בו עם אימות, רישום וכמה שיטות דוגמנות טובות.
2. הגדרת הדוגמא
נתחיל בהוספת ספריית Retrofit וממיר Gson:
com.squareup.retrofit2 retrofit 2.3.0 com.squareup.retrofit2 converter-gson 2.3.0 לקבלת הגרסאות העדכניות, עיין ב- Retrofit ו- converter-gson במאגר Maven Central.
3. דוגמנות API
דגמי Retrofit נקודת קצה של REST כממשקי Java, מה שהופך אותם לפשוטים מאוד להבנה ולצריכה.
אנו מדגמים את ממשק ה- API של המשתמש מ- GitHub; לזה יש לקבל נקודת קצה המחזירה זאת בתבנית JSON:
{login: "mojombo", id: 1, url: "//api.github.com/users/mojombo", ...}רטרופיט עובד על ידי דוגמנות דרך כתובת URL בסיסית ועל ידי הפיכת ממשקים להחזרת הישויות מנקודת הקצה של REST.
למטרות פשטות אנו ניקח חלק קטן מה- JSON על ידי דוגמנות שלנו מִשׁתַמֵשׁ כיתה שהולכת לקחת את הערכים לאחר שנקבל אותם:
משתמש בכיתה ציבורית {פרטי כניסה למחרוזת; מזהה פרטי פרטי; כתובת מחרוזת פרטית; // ... // גטרים סטנדרטיים קובעים}אנו יכולים לראות שאנחנו לוקחים רק קבוצת משנה של מאפיינים לדוגמא זו. רטרופיט לא יתלונן על נכסים חסרים - מכיוון שהוא ממפה רק את מה שאנחנו צריכים, זה אפילו לא יתלונן אם היינו מוסיפים נכסים שאינם ב- JSON.
כעת נוכל לעבור למודל הממשק ולהסביר כמה מההערות של Retrofit:
ממשק ציבורי UserService {@GET ("/ משתמשים") שיחה ציבורית getUsers (@Query ("per_page") int per_page, @Query ("page") int int); @GET ("/ משתמשים / {username}") ציבורי להתקשר getUser (@Path ("שם משתמש") שם משתמש מחרוזת); }
המטא נתונים המסופקים עם ביאורים מספיקים בכלי לייצר מימושים עובדים.
ה @לקבל ביאור אומר ללקוח באיזו שיטת HTTP להשתמש ובאיזה משאב, כך למשל, על ידי מתן כתובת URL בסיסית של "//api.github.com" הוא ישלח את הבקשה אל "//api.github.com/users" .
המוביל "/" בכתובת האתר היחסית שלנו אומר ל- Retrofit שזה נתיב מוחלט על המארח.
דבר נוסף שיש לציין הוא שאנחנו משתמשים באופציונליות לחלוטין @שאילתא פרמטרים, שניתן להעבירם כ null אם איננו זקוקים להם, הכלי ידאג להתעלם מהפרמטרים הללו אם אין להם ערכים.
אחרון חביב, @נָתִיב מאפשר לנו לציין פרמטר נתיב שיוצב במקום הסימון בו השתמשנו בנתיב.
4. ממשק API סינכרוני / אסינכרוני
כדי לבנות שיחת בקשה ל- HTTP, עלינו לבנות תחילה את אובייקט ה- Retrofit שלנו:
OkHttpClient.Builder httpClient = חדש OkHttpClient.Builder (); Retrofit retrofit = new Retrofit.Builder () .baseUrl ("// api.github.com/") .addConverterFactory (GsonConverterFactory.create ()) .client (httpClient.build ()) .build ();רטרופיט מספק בנאי נוח לבניית האובייקט הנדרש שלנו. הוא זקוק לכתובת ה- URL הבסיסית אשר תשמש עבור כל קריאת שירות ומפעל ממיר - אשר דואג לניתוח הנתונים שאנו שולחים וגם לתגובות שאנו מקבלים.
בדוגמה זו נשתמש ב- GsonConverterFactory, אשר עומד למפות את נתוני JSON שלנו אל מִשׁתַמֵשׁ מעמד שהגדרנו קודם.
חשוב לציין כי מפעלים שונים משרתים מטרות שונות, לכן יש לזכור כי אנו יכולים גם להשתמש במפעלים עבור XML, מאגרי פרוטו או אפילו ליצור אחד עבור פרוטוקול מותאם אישית. לרשימת מפעלים שכבר יושמו, נוכל להסתכל כאן.
התלות האחרונה היא OKHttpClient - שהוא לקוח HTTP & HTTP / 2 ליישומי Android ו- Java. זה יטפל בחיבור לשרת ושליחה ואחזור מידע. נוכל להוסיף כותרות ומיירטים לכל שיחה, אותם אנו רואים בסעיף האימות שלנו.
כעת, כשיש לנו אובייקט Retrofit, נוכל לבנות את קריאת השירות שלנו, בואו נסתכל כיצד לעשות זאת בצורה סינכרונית:
שירות UserService = retrofit.create (UserService.class); התקשר להתקשרות callSync = service.getUser ("eugenp"); נסה את {Response response = callSync.execute (); משתמש משתמש = response.body (); } לתפוס (לשעבר חריג) {...}כאן אנו יכולים לראות כיצד רטרופיט דואגת לבניית ממשק השירות שלנו על ידי הזרקת הקוד הדרוש לביצוע הבקשה, בהתבסס על ההערות הקודמות שלנו.
לאחר מכן, אנו מקבלים שִׂיחָה אובייקט שהוא זה שמשמש לביצוע הבקשה ל- API של GitHub. השיטה החשובה ביותר כאן היא לבצע, המשמש לביצוע שיחה באופן סינכרוני ויחסום את השרשור הנוכחי בזמן העברת הנתונים.
לאחר ביצוע השיחה בהצלחה, אנו יכולים לאחזר את גוף התגובה - כבר על אובייקט משתמש - בזכות שלנו GsonConverterFactory.
ביצוע שיחה סינכרונית הוא קל מאוד, אך בדרך כלל אנו משתמשים בבקשה אסינכרונית שאינה חוסמת:
שירות UserService = retrofit.create (UserService.class); התקשר ל- callAsync = service.getUser ("eugenp"); callAsync.enqueue (Callback חדש () {@ ביטול ציבורי בטל onResponse (שיחת שיחה, תגובה תגובה) {משתמש משתמש = תגובה.גוף ();} @ ביטול בטל ציבורי onFailure (שיחה, זרק לזריקה) {System.out.println (ניתן לזריקה);}});כעת במקום שיטת הביצוע, אנו משתמשים ב- enqueue שיטה - שלוקחת א התקשר חזרהממשק כפרמטר לטיפול בהצלחת הבקשה או כישלונה. שים לב שהדבר יבוצע בשרשור נפרד.
לאחר סיום השיחה בהצלחה, אנו יכולים לאחזר את הגופה באותו אופן שעשינו בעבר.
5. ביצוע לשימוש חוזר ServiceGenerator מעמד
כעת, כשראינו כיצד לבנות את אובייקט ה- Retrofit שלנו וכיצד לצרוך API, אנו יכולים לראות כי איננו רוצים להמשיך לכתוב את הבנאי שוב ושוב.
מה שאנחנו רוצים זה מעמד רב פעמי שמאפשר לנו ליצור אובייקט זה פעם אחת ולעשות בו שימוש חוזר לכל אורך היישום שלנו:
מחלקה ציבורית GitHubServiceGenerator {מחרוזת סופית סטטית פרטית BASE_URL = "//api.github.com/"; סטטי פרטי Retrofit.Builder בונה = חדש Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); רטופיט פרטי סטטי פרטי retrofit = builder.build (); פרטי סטטי OkHttpClient.Builder httpClient = OkHttpClient.Builder חדש (); סטטי ציבורי S createService (Class serviceClass) {return retrofit.create (serviceClass); }}כל ההיגיון ביצירת האובייקט Retrofit מועבר כעת לכך GitHubServiceGenerator בכיתה, זה הופך אותו למעמד לקוחות בר קיימא שמונע מהקוד לחזור.
הנה דוגמה פשוטה לשימוש:
שירות UserService = GitHubServiceGenerator.createService (UserService.class);עכשיו אם היינו, למשל, ליצור a מאגר שירות, נוכל לעשות שימוש חוזר במעמד זה ולפשט את היצירה.
בחלק הבאאנו הולכים להרחיב אותו ולהוסיף יכולות אימות.
6. אימות
לרוב ה- API יש אימות מסוים כדי להבטיח גישה אליו.
אם ניקח בחשבון את מחלקת הגנרטורים הקודמת שלנו, אנו נוסיף להוסיף שיטת שירות ליצור, אשר לוקחת אסימון JWT עם ה- הרשאה כותרת:
S createService ציבורי סטטי (Class serviceClass, אסימון מחרוזת סופי) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (chain -> {בקש מקורי = chain.request (); בקשת בקשה = original.newBuilder (). כותרת ("הרשאה", אסימון) .build (); שרשרת החזרה. המשך (בקשה);}); builder.client (httpClient.build ()); רטרופיט = builder.build (); } להחזיר retrofit.create (serviceClass); }כדי להוסיף כותרת לבקשתנו, עלינו להשתמש ביכולות היירוט של OkHttp; אנו עושים זאת על ידי שימוש בבנאי שהגדרנו בעבר ועל ידי בנייה מחדש של אובייקט ה- Retrofit.
שים לב שזו דוגמת אימות פשוטה, אך עם שימוש במיירטים אנו יכולים להשתמש בכל אימות כגון OAuth, משתמש / סיסמה וכו '.
7. כניסה
בחלק זה נרחיב עוד יותר את שלנו GitHubServiceGenerator ליכולות רישום, החשובות מאוד לצורכי ניפוי באגים בכל פרויקט.
אנו נשתמש בידע הקודם שלנו על מיירטים, אך אנו זקוקים לתלות נוספת, שהיא ה- HttpLoggingInterceptor מ- OkHttp, בואו נוסיף אותו ל pom.xml:
com.squareup.okhttp3 רישום יירוט 3.9.0 עכשיו בואו נרחיב את שלנו GitHubServiceGenerator מעמד :
מחלקה ציבורית GitHubServiceGenerator {מחרוזת סופית סטטית פרטית BASE_URL = "//api.github.com/"; סטטי פרטי Retrofit.Builder בונה = חדש Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); רטופיט פרטי סטטי פרטי retrofit = builder.build (); פרטי סטטי OkHttpClient.Builder httpClient = OkHttpClient.Builder חדש (); רישום סטטי פרטי של HttpLoggingInterceptor = HttpLoggingInterceptor חדש () .setLevel (HttpLoggingInterceptor.Level.BASIC); סטטי ציבורי S createService (Class serviceClass) {אם (! httpClient.interceptors (). מכיל (רישום)) {httpClient.addInterceptor (רישום); builder.client (httpClient.build ()); רטרופיט = builder.build (); } להחזיר retrofit.create (serviceClass); } S ציבורי סטטי ציבורי (Class serviceClass, אסימון מחרוזת סופי) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (chain -> {בקש מקורי = chain.request (); בקשת Builder Builder1 = original.newBuilder (). כותרת ("הרשאה", אסימון); בקשת בקשה = builder1.build (); שרשרת החזרה. המשך (בקשה);}); builder.client (httpClient.build ()); רטרופיט = builder.build (); } להחזיר retrofit.create (serviceClass); }}זו הצורה הסופית של הכיתה שלנו, אנו יכולים לראות כיצד הוספנו את ה- HttpLoggingInterceptor, והגדרנו אותו לרישום רישום בסיסי, שהולך לרשום את הזמן שנדרש לביצוע הבקשה, נקודת הסיום, הסטטוס לכל בקשה וכו '.
חשוב לבחון כיצד אנו בודקים אם המיירט קיים, כך שלא נוסיף אותו בטעות פעמיים.
8. מסקנה
במדריך נרחב זה, הסתכלנו על ספריית ה- Retrofit המצוינת על ידי התמקדות בממשק ה- Sync / Async שלה, כמה שיטות עבודה מומלצות של דוגמנות, אימות ורישום.
ניתן להשתמש בספרייה בדרכים מורכבות ושימושיות מאוד; למקרה שימוש מתקדם עם RxJava, אנא עיין במדריך זה.
וכמו תמיד, ניתן למצוא את קוד המקור ב- GitHub.
