streamalism.org

1. סקירה כללית

במאמר זה נסתכל על ספריית הלקוחות HTTP של גוגל עבור Java, שהיא ספריה מהירה ומופשטת היטב לגישה לכל משאבים באמצעות פרוטוקול חיבור HTTP.

המאפיינים העיקריים של הלקוח הם:

• שכבת הפשטה HTTP המאפשרת לך לקשר כל ספרייה ברמה נמוכה
• מודלים לניתוח מהיר, יעיל וגמיש של JSON ו- XML ​​של תגובת HTTP ותוכן בקשה
• הערות והפשטות קלות לשימוש למיפוי משאבי HTTP

ניתן להשתמש בספרייה גם ב- Java 5 ומעלה, מה שהופך אותה לבחירה ניכרת לפרויקטים מורשת (SE ו- EE).

במאמר זה, אנו הולכים לפתח יישום פשוט זה יתחבר ל- API של GitHub ויאחזר משתמשים, תוך כיסוי על כמה מהתכונות המעניינות ביותר בספרייה.

2. תלות Maven

כדי להשתמש בספריה נצטרך את ה- google-http-client תלות:

 com.google.http-client google-http-client 1.23.0 

את הגרסה האחרונה ניתן למצוא ב- Maven Central.

3. הגשת בקשה פשוטה

נתחיל בהגשת בקשת GET פשוטה לדף GitHub כדי להציג כיצד פועל לקוח Http של Google מחוץ לקופסה:

HttpRequestFactory requestFactory = NetHttpTransport חדש (). CreateRequestFactory (); HttpRequest בקשה = requestFactory.buildGetRequest (GenericUrl חדש ("// github.com")); מחרוזת rawResponse = request.execute (). ParseAsString ()

כדי לקבל את הבקשה הכי פשוטה נצטרך לפחות:

• HttpRequestFactory זה משמש לבניית הבקשות שלנו
• HttpTransport הפשטה של ​​שכבת התחבורה HTTP ברמה נמוכה
• GenericUrl שיעור שעוטף את כתובת האתר
• HttpRequest מטפל בביצוע הבקשה בפועל

נעבור על כל אלה ודוגמה מורכבת יותר עם ממשק API שמחזיר פורמט JSON בסעיפים הבאים.

4. הובלת HTTP ניתנת לחיבור

בספרייה יש מופשט היטב HttpTransport מעמד המאפשר לנו לבנות על גבי זה ו שנה לספריית התחבורה HTTP ברמה הנמוכה שבחרת:

מחלקה ציבורית GitHubExample {static HttpTransport HTTP_TRANSPORT = NetHttpTransport חדש (); }

בדוגמה זו אנו משתמשים ב- NetHttpTransport, אשר מבוסס על חיבור HttpURLC שנמצא בכל Java SDKs. זוהי בחירה התחלתית טובה שכן היא ידועה ואמינה.

כמובן, יכול להיות שהמקרה בו אנו זקוקים להתאמה אישית מתקדמת, וכך הדרישה לספריה מורכבת יותר ברמה נמוכה.

עבור מקרים מסוג זה, יש ApacheHttp תחבורה:

מחלקה ציבורית GitHubExample {static HttpTransport HTTP_TRANSPORT = ApacheHttpTransport () חדש; }

ה ApacheHttpTransport מבוסס על Apache HttpClient הפופולרי הכולל מגוון רחב של אפשרויות להגדרת חיבורים.

בנוסף, הספרייה מספקת אפשרות לבנות את היישום ברמה נמוכה שלך, מה שהופך אותו לגמיש מאוד.

5. ניתוח JSON

לקוח Http של Google כולל הפשטה נוספת לניתוח JSON. יתרון גדול בכך הוא הבחירה בספריית הניתוח ברמה נמוכה ניתנת להחלפה.

יש שלוש אפשרויות מובנות, שכולן מתרחבות JsonFactory, וזה כולל גם אפשרות ליישם את שלנו.

5.1. ספריית ניתוח מתחלפת

בדוגמה שלנו, אנו נשתמש ביישום Jackson2, הדורש את ה- google-http-client-jackson2 תלות:

 com.google.http-client google-http-client-jackson2 1.23.0 

בעקבות זאת, כעת ניתן לכלול את ה- JsonFactory:

מחלקה ציבורית GitHubExample {static HttpTransport HTTP_TRANSPORT = NetHttpTransport חדש (); staticJsonFactory JSON_FACTORY = JacksonFactory חדש (); }

ה JacksonFactory היא הספרייה המהירה והפופולארית ביותר עבור פעולות ניתוח / סידור.

זה כרוך במחיר גודל הספרייה (מה שיכול להוות חשש במצבים מסוימים). מסיבה זו, גוגל מספקת גם את GsonFactory, שהיא יישום של ספריית Google GSON, ספריית ניתוח JSON קלה.

יש גם אפשרות לכתוב את היישום המנתח שלנו ברמה נמוכה.

5.2. ה @מַפְתֵחַ ביאור

אנחנו יכולים להשתמש ב- @מַפְתֵחַ ביאור כדי לציין שדות שיש לנתח אותם או לסדרם אותם ל- JSON:

משתמש בכיתה ציבורית {@ מפתח פרטי מחרוזת פרטי; מזהה פרטי פרטי @ Key; @Key ("דוא"ל") דוא"ל מחרוזת פרטי; // סטרים וקובעים סטנדרטיים}

הנה אנחנו מכינים מִשׁתַמֵשׁ הפשטה, אותה אנו מקבלים אצווה מ- API של GitHub (נגיע לניתוח בפועל בהמשך מאמר זה).

שים לב ש שדות שאין להם את @מַפְתֵחַ הערה נחשבת פנימית ואינה מנותחת או מסדרת JSON. כמו כן, הנראות של השדות לא משנה, וגם קיומם של שיטות הגטר או הקובע אינו חשוב.

אנו יכולים לציין את הערך של ה- @מַפְתֵחַ ביאור, כדי למפות אותו למפתח JSON הנכון.

5.3. GenericJson

רק את השדות אנו מצהירים ומסמנים כ- @מַפְתֵחַ הם מעובדים.

כדי לשמור על התוכן האחר, אנו יכולים להכריז על כיתתנו להרחיב GenericJson:

משתמש בכיתה ציבורית מרחיב את GenericJson {// ...}

GenericJson מיישם את מַפָּה ממשק, מה שאומר שאנחנו יכולים להשתמש בשיטות get and put כדי להגדיר / לקבל תוכן JSON בבקשה / בתגובה.

6. ביצוע השיחה

כדי להתחבר לנקודת קצה עם לקוח Http של Google, נצטרך HttpRequestFactory, אשר יוגדרו עם ההפשטות הקודמות שלנו HttpTransport ו JsonFactory:

מחלקה ציבורית GitHubExample {static HttpTransport HTTP_TRANSPORT = NetHttpTransport חדש (); סטטי JsonFactory JSON_FACTORY = JacksonFactory חדש (); ריצה ריקנית סטטית פרטית () זורקת Exception {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest request) -> {request.setParser (JsonObjectParser חדש (JSON_FACTORY));}); }}

הדבר הבא שנצטרך הוא כתובת URL להתחברות אליה. הספרייה מטפלת בכך ככיתה המרחיבה GenericUrl עליו מתייחסים לכל שדה שהוכרז כפרמטר שאילתה:

מחלקה ציבורית GitHubUrl מרחיב את GenericUrl {public GitHubUrl (String encodedUrl) {super (encodedUrl); } @ מפתח ציבורי לכל דף; }

כאן שלנו GitHubUrl, אנו מכריזים על לכל דף מאפיין כדי לציין כמה משתמשים אנו רוצים בשיחה אחת ל- API של GitHub.

בואו נמשיך לבנות את השיחה שלנו באמצעות ה- GitHubUrl:

ריצה ריקנית סטטית פרטית () זורקת Exception {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest request) -> {request.setParser (JsonObjectParser חדש (JSON_FACTORY));}); כתובת אתר GitHubUrl = GitHubUrl חדשה ("// api.github.com/users"); url.per_page = 10; HttpRequest בקשה = requestFactory.buildGetRequest (url); סוג סוג = סוג חדש() {} .getType (); משתמשים ברשימה = (רשימה) מבקשים .execute () .parseAs (סוג); }

שימו לב כיצד אנו מציינים כמה משתמשים נצטרך לשיחת ה- API, ואז אנו בונים את הבקשה עם ה- HttpRequestFactory.

בעקבות זאת, מכיוון שתגובת ה- API של GitHub מכילה רשימת משתמשים, עלינו לספק מתחם סוּג, שהוא א רשימה.

ואז, בשורה האחרונה, אנו מבצעים את השיחה ומנתחים את התגובה לרשימה שלנו מִשׁתַמֵשׁ מעמד.

7. כותרות בהתאמה אישית

דבר אחד שאנו עושים בדרך כלל כשאנחנו מגישים בקשת API הוא לכלול סוג כותרת מותאמת אישית או אפילו שינוי אחד:

כותרות HttpHeaders = request.getHeaders (); headers.setUserAgent ("לקוח באלדונג"); headers.set ("אזור זמן", "אירופה / אמסטרדם");

אנו עושים זאת על ידי קבלת ה- HttpHeaders לאחר שיצרנו את בקשתנו אך לפני ביצועה והוספת הערכים הדרושים.

שים לב שלקוח Http של Google כולל כמה כותרות כשיטות מיוחדות. ה סוכן משתמש כותרת למשל, אם ננסה לכלול אותו רק בשיטת ההגדרה זה היה זורק שגיאה.

8. כיבוי אקספוננציאלי

מאפיין חשוב נוסף של לקוח Http של Google הוא האפשרות לנסות שוב בקשות על סמך קודי סטטוס וספים מסוימים.

אנו יכולים לכלול את הגדרות ה- backoff האקספוננציאליות מיד לאחר שיצרנו את אובייקט הבקשה שלנו:

ExponentialBackOff backoff = חדש ExponentialBackOff.Builder () .setInitialIntervalMillis (500). SetMaxElapsedTimeMillis (900000) .setMaxIntervalMillis (6000). SetMultiplier (1.5). SetRandomizationFactor (0.5) .build (); request.setUnsuccessfulResponseHandler (HttpBackOffUnsuccessfulResponseHandler חדש (backoff));

Backoff אקספוננציאלי כבוי כברירת מחדל ב- HttpRequestאז עלינו לכלול מופע של HttpUnsuccessfulResponseHandler אל ה HttpRequest להפעיל אותו.

9. כניסה

לקוח Http של Google משתמש java.util.logging.Logger לרישום פרטי בקשת HTTP ותגובה, כולל URL, כותרות ותוכן.

בדרך כלל, רישום מנוהל באמצעות א logging.properties קוֹבֶץ:

מטפלים = java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level = ALL com.google.api.client.http.level = ALL

בדוגמה שלנו אנו משתמשים ConsoleHandler, אבל אפשר גם לבחור את FileHandler.

קובץ המאפיינים מגדיר את פעולתו של מתקן הרישום של JDK. ניתן לציין קובץ תצורה זה כמאפיין מערכת:

-Djava.util.logging.config.file = logging.properties

אז לאחר הגדרת מאפיין הקובץ והמערכת, הספרייה תייצר יומן כמו הבא:

-------------- בקשה -------------- GET //api.github.com/users?page=1&per_page=10 קבל-קידוד: gzip סוכן משתמש: Google-HTTP-Java-Client / 1.23.0 (gzip) 12 בנובמבר, 2017 18:43:15 com.google.api.client.http.HttpRequest לבצע תלתל -v - דחוס -H 'קבל -קידוד: gzip '-H' סוכן משתמש: Google-HTTP-Java-Client / 1.23.0 (gzip) '-' //api.github.com/users?page=1&per_page=10 '12 בנובמבר 2017 18:43:16 com.google.api.client.http.Http תגובה -------------- תגובה -------------- HTTP / 1.1 200 OK מצב: 200 OK העברת קידוד: chunked שרת: GitHub.com בקרת גישה-אפשר-מקור: * ... קישור:; rel = "הבא",; rel = "first" X-GitHub-Request-Id: 8D6A: 1B54F: 3377D97: 3E37B36: 5A08DC93 סוג תוכן: application / json; ערכת = utf-8 ...

10. מסקנה

במדריך זה הראינו את ספריית הלקוחות HTTP של גוגל עבור Java ואת התכונות היעילות יותר שלה. ה- Github שלהם מכיל מידע נוסף עליו, כמו גם את קוד המקור של הספרייה.

כמו תמיד, קוד המקור המלא של הדרכה זו זמין באתר GitHub.