streamalism.org

1. הקדמה

לפרוטוקול ה- HTTP ולממשקי ה- API הבנויים עליו חשיבות מרכזית בתכנות בימינו.

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

במאמר זה, אנו נסתכל על khttp, ספריית קוטלין אידיומטית לצריכת משאבים מבוססי HTTP ו- API.

2. תלות

על מנת להשתמש בספרייה בפרויקט שלנו, ראשית עלינו להוסיף אותה לתלות שלנו:

 khttp khttp 0.1.0 

מכיוון שזה עדיין לא נמצא ב- Maven Central, עלינו לאפשר גם את המאגר JCenter:

 מרכזית //jcenter.bintray.com 

גרסה 0.1.0 היא הנוכחית בזמן כתיבת שורות אלה. אנחנו יכולים, כמובן, לבדוק אם JCenter נמצא חדש יותר.

3. שימוש בסיסי

היסודות של פרוטוקול HTTP הם פשוטים, למרות שהפרטים המשובחים יכולים להיות מורכבים למדי. לכן, ל- khttp יש גם ממשק פשוט.

עבור כל שיטת HTTP, אנו יכולים למצוא פונקציה ברמת החבילה ב- khttp חֲבִילָה, כמו לקבל, הודעה וכולי.

הפונקציות כולן לוקחות את אותה קבוצת ארגומנטים ומחזירות a תְגוּבָה לְהִתְנַגֵד; נראה את הפרטים הללו בסעיפים הבאים.

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

ייבא את khttp.delete כ- httpDelete

הערה: הוספנו הצהרות סוג לשם בהירות בכל דוגמאות הקוד כי בלי IDE הם יכולים להיות קשים למעקב.

4. בקשה פשוטה

לכל בקשת HTTP יש לפחות שני רכיבים נדרשים: שיטה וכתובת אתר. ב- khttp, השיטה נקבעת על ידי הפונקציה שאנו מפעילים, כפי שראינו בסעיף הקודם.

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

khttp.get ("// httpbin.org/get")

בחלקים הבאים נשקול את כל הבקשות להשלמה בהצלחה.

4.1. הוספת פרמטרים

לעתים קרובות עלינו לספק פרמטרים של שאילתות בנוסף לכתובת האתר הבסיסית, במיוחד עבור בקשות GET.

השיטות של khttp מקבלות א פאראמים טַעֲנָה שהוא א מַפָּה של צמדי ערך מפתח שייכללו בשאילתה חוּט:

khttp.get (url = "//httpbin.org/get", params = mapOf ("key1" to "value1", "keyn" to "valuen"))

שימו לב שהשתמשנו ב- מפה של פונקציה לבניית א מַפָּה בדרך; כתובת האתר של הבקשה שהתקבלה תהיה:

//httpbin.org/get?key1=value1&keyn=valuen

5. גוף מבקש

פעולה נפוצה נוספת שאנו צריכים לבצע לעתים קרובות היא שליחת נתונים, בדרך כלל כמשא מטען של בקשת POST או PUT.

לשם כך, הספרייה מציעה מספר אפשרויות שאותן נבחן בסעיפים הבאים.

5.1. שליחת מטען JSON

אנחנו יכולים להשתמש ב- ג'סון טיעון למשלוח אובייקט או מערך JSON. זה יכול להיות מכמה סוגים שונים:

• א JSONObject אוֹ JSON מערך כמסופק על ידי ספריית org.json
• א מַפָּה, שהופך לאובייקט JSON
• א אוסף, ניתן לנידון או מערך, אשר הופך למערך JSON

אנחנו יכולים להפוך את דוגמת ה- GET הקודמת שלנו בקלות ל- POST שתשלח אובייקט JSON פשוט:

khttp.post (url = "//httpbin.org/post", json = mapOf ("key1" to "value1", "keyn" to "valuen"))

שים לב שההפיכה מאוספים לאובייקטים של JSON היא רדודה. לדוגמא, א רשימה שֶׁל מַפָּהזה לא יומר למערך JSON של אובייקטים JSON, אלא למערך מחרוזות.

לצורך המרה עמוקה, נצטרך ספריית מיפוי JSON מורכבת יותר כמו ג'קסון. מתקן ההמרה של הספרייה נועד רק למקרים פשוטים.

5.2. שליחת נתוני טופס (כתובת אתר מקודדת)

כדי לשלוח נתוני טפסים (מקודדים לכתובת אתר, כמו בטופסי HTML) אנו משתמשים ב- נתונים ויכוח עם א מַפָּה:

khttp.post (url = "//httpbin.org/post", data = mapOf ("key1" to "value1", "keyn" to "valuen"))

5.3. העלאת קבצים (טופס מרובה חלקים)

אנו יכולים לשלוח קובץ אחד או יותר המקודדים כבקשת נתוני טופס מרובה חלקים.

במקרה זה, אנו משתמשים ב- קבצים טַעֲנָה:

khttp.post (url = "//httpbin.org/post", files = listOf (FileLike ("file1", "content1"), FileLike ("file2", File ("kitty.jpg"))))

אנו יכולים לראות ש- khttp משתמש ב- FileLike הפשטה, שהיא אובייקט עם שם ותוכן. התוכן יכול להיות מחרוזת, מערך בתים, א קוֹבֶץ, או א נָתִיב.

5.4. שליחת תוכן גולמי

אם אף אחת מהאפשרויות שלעיל אינן מתאימות, נוכל להשתמש ב- InputStream לשלוח נתונים גולמיים כגוף בקשת HTTP:

khttp.post (url = "//httpbin.org/post", data = someInputStream)

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

6. טיפול בתגובה

עד כה ראינו דרכים שונות לשליחת נתונים לשרת. אך פעולות HTTP רבות שימושיות בגלל הנתונים שהם מחזירים גם כן.

לכן khttp מבוסס על חסימת קלט / פלט כל הפונקציות המתאימות לשיטות HTTP מחזירות א תְגוּבָה לְהִתְנַגֵד המכילה את התגובה שהתקבלה מהשרת.

לאובייקט זה יש מאפיינים שונים אליהם אנו יכולים לגשת, תלוי בסוג התוכן.

6.1. תגובות JSON

אם אנו יודעים שהתגובה היא אובייקט או מערך JSON, נוכל להשתמש ב- jsonObject ו jsonArray נכסים:

תגובת val: תגובה = khttp.get ("// httpbin.org/get") val obj: JSONObject = response.jsonObject הדפסה (obj ["someProperty"])

6.2. טקסט או תגובות בינאריות

אם אנחנו רוצים לקרוא את התגובה כ- חוּט במקום זאת, אנו יכולים להשתמש ב- טֶקסט תכונה:

הודעת val: String = response.text

לחלופין, אם אנו רוצים לקרוא אותו כנתונים בינאריים (למשל הורדת קבצים) אנו משתמשים ב- תוֹכֶן תכונה:

val imageData: ByteArray = response.content

לבסוף, אנו יכולים גם לגשת לבסיס InputStream:

val inputStream: InputStream = response.raw

7. שימוש מתקדם

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

7.1. טיפול בכותרות ועוגיות

כל פונקציות khttp לוקחות a כותרות טַעֲנָה שהוא א מַפָּה של שמות וערכי כותרות.

val response = khttp.get (url = "//httpbin.org/get", headers = mapOf ("header1" to "1", "header2" to "2"))

באופן דומה לעוגיות:

val response = khttp.get (url = "//httpbin.org/get", cookies = mapOf ("cookie1" to "1", "cookie2" to "2"))

אנו יכולים לגשת לכותרות ולעוגיות שנשלחו על ידי השרת בתגובה:

val contentType: String = response.headers ["Type Content"] val sessionID: String = response.cookies ["JSESSIONID"]

7.2. טיפול בשגיאות

ישנם שני סוגים של שגיאות שיכולות להתעורר ב- HTTP: תגובות שגיאה, כגון 404 - לא נמצא, שהן חלק מהפרוטוקול; ושגיאות ברמה נמוכה, כגון "סירוב לחיבור".

הסוג הראשון אינו גורם לחריגות khttp לזרוק; במקום זאת, עלינו לבדוק את מצב תגובה קוד תכונה:

val response = khttp.get (url = "//httpbin.org/nothing/to/see/here") if (response.statusCode == 200) {process (response)} אחר {handleError (תגובה)}

שגיאות ברמה נמוכה יותר, במקום זאת, גורמות להוצאת חריגים מתת-מערכת ה- Java I / O הבסיסית, כגון ConnectException.

7.3. תגובות סטרימינג

לפעמים השרת יכול להגיב עם פיסת תוכן גדולה, ו / או לקחת זמן רב להגיב. במקרים אלה, ייתכן שנרצה לעבד את התגובה בנתחים, במקום להמתין להשלמתו ולתפוס זיכרון.

אם אנו רוצים להורות לספרייה לתת לנו מענה לסטרימינג, עלינו לעבור נָכוֹן כמו זרם טַעֲנָה:

תגובת val = khttp.get (url = "//httpbin.org", stream = true)

לאחר מכן נוכל לעבד אותו בנתחים:

response.contentIterator (chunkSize = 1024). forEach {arr: ByteArray -> handleChunk (arr)}

7.4. שיטות לא סטנדרטיות

במקרה הלא סביר שעלינו להשתמש בשיטת HTTP (או פועל) ש- khttp לא מספק באופן מקורי - נניח, עבור הרחבה כלשהי של פרוטוקול HTTP, כמו WebDAV - אנחנו עדיין מכוסים.

למעשה, כל הפונקציות בחבילת khttp, המתאימות לשיטות HTTP, מיושמות באמצעות כללי בַּקָשָׁה פונקציה שנוכל להשתמש בה גם:

khttp.request (method = "COPY", url = "//httpbin.org/get", headers = mapOf ("Destination" to "/ copy-of-get"))

7.5. תכונות אחרות

לא נגענו בכל התכונות של khttp. לדוגמה, לא דנו בפסקי זמן, הפניות מחדש והיסטוריה או פעולות אסינכרוניות.

התיעוד הרשמי הוא המקור האולטימטיבי למידע על הספרייה ועל כל תכונותיה.

8. מסקנה

במדריך זה ראינו כיצד לבצע בקשות HTTP בקוטלין באמצעות הספרייה האידיומטית khttp.

היישום של כל הדוגמאות הללו ניתן למצוא בפרויקט GitHub.