דפדפן REST ו- HAL באביב

REST למעלה

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2:

>> בדוק את הקורס

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

במדריך זה נדון מה זה HAL ולמה זה שימושי לפני הצגת דפדפן HAL.

לאחר מכן נשתמש באביב כדי לבנות REST API פשוט עם כמה נקודות קצה מעניינות ולאכלס את מסד הנתונים שלנו בכמה נתוני בדיקה.

לבסוף, באמצעות דפדפן HAL, נחקור את ה- REST API שלנו ונגלה כיצד לחצות את הנתונים הכלולים בתוכו.

2. HAL ודפדפן HAL

שפת היישום JSON Hypertext, או HAL, היא פורמט פשוט נותן דרך עקבית וקלה לקישור בין משאבים ב- API שלנו. הכללת HAL בתוך ה- REST API שלנו הופכת את זה לחקר הרבה יותר למשתמשים, כמו גם בעצם תיעוד עצמי.

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

ה מודל HAL סובב סביב שני מושגים פשוטים.

אֶמְצָעִי, המכילים:

  • קישורים ל- URI רלוונטיים
  • משאבים משובצים
  • מדינה

קישורים:

  • URI יעד
  • קשר, או התייחסות לקישור
  • כמה מאפיינים אופציונליים אחרים שיעזרו בפחת, במשא ומתן על תוכן וכו '

דפדפן HAL נוצר על ידי אותו אדם שפיתח HAL ו- מספק ממשק משתמש ממשק בדפדפן כדי לחצות את ה- REST API שלך.

כעת נבנה ממשק API פשוט של REST, נחבר לדפדפן HAL ונחקור את התכונות.

3. תלות

להלן התלות היחידה הדרושה לשילוב דפדפן HAL ב- API של REST שלנו. אתה יכול למצוא את שאר התלות עבור ה- API בקוד GitHub.

ראשית, התלות בפרויקטים מבוססי Maven:

 org.springframework.data spring-data-rest-hal-browser 3.2.6.RELEASE 

אם אתה בונה עם Gradle, אתה יכול להוסיף שורה זו ל- שלך build.gradle קוֹבֶץ:

קבוצת הידור: 'org.springframework.data', שם: 'דפדפן קפיץ-נתונים-מנוחה-חל', גרסה: '3.0.8.RELEASE'

4. בניית ממשק API פשוט של REST

4.1. מודל נתונים פשוט

בדוגמה שלנו, אנו נקבע API פשוט של REST לדפדוף בספרים שונים בספרייה שלנו.

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

@Entity class class ספר {@Id @GeneratedValue (אסטרטגיה = GenerationType.IDENTITY) מזהה ארוך פרטי; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) כותרת מחרוזת פרטית; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) מחבר מחרוזת פרטי; @Column (columnDefinition = "VARCHAR", אורך = 1000) טשטוש פרטי מחרוזת; דפי אינטר פרטי; // רגילים, סטרים ובונים רגילים}

4.2. הכנסת מאגר CRUD

לאחר מכן, נצטרך כמה נקודות קצה. לשם כך אנו יכולים למנף את PagingAndSortingRepositoryולציין שאנחנו רוצים לקבל נתונים מה- סֵפֶר יֵשׁוּת.

הכיתה הזאת מספק פקודות CRUD פשוטות, כמו גם יכולות החלפה ומיון מיד מהקופסה:

ממשק ציבורי @ מאגר BookRepository מרחיב את PagingAndSortingRepository {@RestResource (rel = "title-contains", path = "title-contains") דף findByTitleContaining (@Param ("שאילתה") שאילתת מחרוזת, דף מתוצג); @RestResource (rel = "author-contains", path = "author-contains", exported = false) עמוד findByAuthorContaining (@Param ("שאילתה") שאילתת מחרוזת, דף מתוצג); }

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

הרחבנו את המאגר על ידי הוספת שתי נקודות קצה חדשות:

  • findByTitleContaining - מחזירה ספרים המכילים את השאילתה הכלולה בכותרת
  • findByAuthorContaining - מחזירה ספרים ממסד הנתונים שבו מחבר הספר מכיל את השאילתה

שימו לב שלנו נקודת הקצה השנייה מכילה את ייצוא = שקר תְכוּנָה. תכונה זו מפסיק את יצירת קישורי HAL לנקודת קצה זו, ולא יהיה זמין דרך דפדפן HAL.

לבסוף, נטען את הנתונים שלנו כאשר האביב יתחיל על ידי הגדרת מחלקה שמיישמת את ApplicationRunner מִמְשָׁק. אתה יכול למצוא את הקוד ב- GitHub.

5. התקנת דפדפן HAL

ההתקנה של דפדפן HAL קלה להפליא בעת בניית REST API עם Spring. כל עוד יש לנו את התלות, אביב יגדיר את הדפדפן באופן אוטומטי ויהפוך אותו לזמין דרך נקודת הקצה המוגדרת כברירת מחדל.

כל שעלינו לעשות עכשיו זה ללחוץ על הפעלה ולעבור לדפדפן. דפדפן HAL יהיה זמין ב- // localhost: 8080 /

6. חקר ה- API של REST שלנו באמצעות דפדפן HAL

ה דפדפן HAL מפורק לשני חלקים - הסייר והמפקח. אנו נשבר ונחקור כל קטע בנפרד.

6.1. סייר ה- HAL

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

מתחת לאלה יש לנו את קטע הקישורים ורשימה הניתנת ללחיצה על משאבים משובצים.

6.2. שימוש בקישורים

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

אלה קישורים נוצרים מה- HAL בקטע הסמוך:

"_links": {"first": {"href": "// localhost: 8080 / books? page = 0 & size = 20"}, "self": {"href": "// localhost: 8080 / books {? דף, גודל, מיון} "," תבנית ": נכון}," הבא ": {" href ":" // localhost: 8080 / books? page = 1 & size = 20 "}," last ": {" href ": "// localhost: 8080 / books? page = 4 & size = 20"}, "profile": {"href": "// localhost: 8080 / profile / books"}, "search": {"href": "/ / localhost: 8080 / books / search "}},

אם נעבור לנקודת הקצה של החיפוש, נוכל גם להציג את נקודות הקצה המותאמות אישית שיצרנו באמצעות ה- PagingAndSortingRepository:

{"_links": {"title-contains": {"href": "// localhost: 8080 / books / search / title-contains {? query, page, size, sort}", "templated": true}, "self": {"href": "// localhost: 8080 / books / search"}}} 

ה- HAL לעיל מראה את שלנו כותרת מכילה נקודת קצה המציגה קריטריונים מתאימים לחיפוש. שים לב כיצד מחבר מכיל נקודת קצה חסרה מכיוון שהגדרנו שאסור לייצא אותה.

6.3. הצגת משאבים משובצים

משאבים משובצים מראים את פירוט רשומות הספרים על שלנו / ספרים נקודת סיום. כל משאב מכיל גם משלו נכסים ו קישורים סָעִיף:

6.4. שימוש בטפסים

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

הנה הטופס שלנו הכותרת מכילה נקודת סיום:

ה- URI המותאם אישית שלנו מחזיר את ה- עמוד ראשון מתוך 20 ספרים שהכותרת מכילה את המילה 'Java'.

6.5. מפקח האל

המפקח מרכיב את הצד הימני של הדפדפן ומכיל את ה- כותרות התגובה וגוף התגובה. זֶה נתוני HAL משמשים לעיבוד הקישורים והמשאבים המשובצים שראינו קודם בהדרכה.

7. מסקנה

במאמר זה סיכמנו מה זה HAL, למה זה שימושי ומדוע זה יכול לעזור לנו ליצור ממשקי API של REST מעולים עצמיים.

בנינו REST API פשוט עם Spring אשר מיישם את ה- PagingAndSortingRepository, כמו גם הגדרת נקודות הקצה שלנו. ראינו גם איך אל תכלול נקודות קצה מסוימות מדפדפן HAL.

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

כמו תמיד, הקוד זמין ב- GitHub.

REST תחתון

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2:

>> בדוק את הקורס

$config[zx-auto] not found$config[zx-overlay] not found