streamalism.org

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

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

מאמר זה מסביר את התהליך של יצירת שירות רשת REST מונע היפר-מדיה באמצעות פרויקט Spring HATEOAS.

2. אביב-HATEOAS

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

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

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

3. הכנה

ראשית, בואו נוסיף את תלות האביב של HATEOAS:

 org.springframework.boot spring-boot-starter-hateoas 2.1.4.RELEASE 

אם איננו משתמשים באביב אתחול נוכל להוסיף את הספריות הבאות לפרויקט שלנו:

 org.springframework.hateoas spring-hateoas 0.25.1.RELEASE org.springframework.plugin spring-plugin-core 1.2.0.RELEASE 

כמו תמיד, אנו יכולים לחפש בגרסאות העדכניות ביותר של המתחיל HATEOAS, האביב-שנאתיים ותלות הליבה של האביב-תוסף במרכז Maven.

לאחר מכן, יש לנו את צרכן משאב ללא תמיכת Spring HATEOAS:

לקוח ממעמד ציבורי {private String customerId; פרטי מחרוזת customerName; חברת מחרוזת פרטית שם; // סטרים וקובעים סטנדרטיים} 

ויש לנו כיתת בקר ללא תמיכת Spring HATEOAS:

@RestController @RequestMapping (value = "/ customers") CustomerController בכיתה ציבורית {@ CustomerService פרטי CustomerService פרטי; @GetMapping ("/ {customerId}") לקוח ציבורי getCustomerById (@PathVariable String customerId) {return customerService.getCustomerDetail (customerId); }} 

סוף - סוף, ה צרכן ייצוג משאבים:

{"customerId": "10A", "customerName": "Jane", "customerCompany": "ABC Company"} 

4. הוספת תמיכת HATEOAS

בפרויקט HATEOAS של אביב, איננו צריכים לחפש את הקשר Servlet ולא לשרשר את משתנה הנתיב ל- URI הבסיסי.

במקום זאת, אביב HATEOAS מציע שלוש הפשטות ליצירת ה- URI - RepresentationModel, Link ו- WebMvcLinkBuilder. אנו יכולים להשתמש בהם כדי ליצור את המטא נתונים ולשייך אותם לייצוג המשאבים.

4.1. הוספת תמיכת Hypermedia למשאב

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

לקוח ממעמד ציבורי מרחיב את RepresentationalModel {customer String customerId; פרטי מחרוזת customerName; חברת מחרוזת פרטית שם; // סטרים וקובעים סטנדרטיים} 

ה צרכן משאב משתרע על ידי ייצוג מודל כיתה לרשת את לְהוֹסִיף() שיטה. אז ברגע שניצור קישור, אנו יכולים בקלות להגדיר את הערך לייצוג המשאבים מבלי להוסיף לו שדות חדשים.

4.2. יצירת קישורים

אביב HATEOAS מספק א קישור התנגד לאחסון המטא נתונים (מיקום או URI של המשאב).

ראשית, ניצור קישור פשוט באופן ידני:

קישור קישור = קישור חדש ("// localhost: 8080 / spring-security-rest / api / clients / 10A"); 

ה קישור אובייקט עוקב אחר אָטוֹם תחביר קישור ומורכב מ- rel שמזהה קשר למשאב ו- href המאפיין שהוא הקישור עצמו.

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

{"customerId": "10A", "customerName": "Jane", "customerCompany": "ABC Company", "_links": {"self": {"href": "// localhost: 8080 / spring-security -rest / api / clients / 10A "}}} 

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

4.3. יצירת קישורים טובים יותר

מופשט נוסף וחשוב מאוד שמציעה הספרייה הוא ה WebMvcLinkBuilder - מה שמפשט את בניית ה- URI על ידי הימנעות מקישורים מקודדים.

הקטע הבא מציג בנייה של הקישור העצמי של הלקוח באמצעות ה- WebMvcLinkBuilder מעמד:

linkTo (CustomerController.class). סלאש (customer.getCustomerId ()). withSelfRel (); 

בוא נראה:

• ה קישור ל() השיטה בודקת את מחלקת הבקר ומשיגה את מיפוי השורשים שלה
• ה קו נטוי() השיטה מוסיפה את מספר לקוח ערך כמשתנה הנתיב של הקישור
• סוף - סוף, ה withSelfMethod () מסייג את הקשר כקישור עצמי

5. יחסים

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

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

סדר בכיתה ציבורית מרחיב את RepresentationalModel {private String orderId; מחיר כפול פרטי; כמות אינטנס פרטית; // סטרים וקובעים סטנדרטיים} 

בשלב זה, אנו יכולים להרחיב את CustomerController בשיטה שמחזירה את כל ההזמנות של לקוח מסוים:

@GetMapping (value = "/ {customerId} / orders", מייצר = {"application / hal + json"}) אוסף ציבורי של ModelModel getOrdersForCustomer (@PathVariable final String customerId) {List orders = orderService.getAllOrdersForCustomer (customerId); עבור (סדר הזמנה סופי: הזמנות) {Link selfLink = linkTo (methodOn (CustomerController.class) .getOrderById (customerId, order.getOrderId ())). withSelfRel (); order.add (קישור עצמי); } קישור קישור = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithSelfRel (); תוצאת CollectionModel = CollectionModel חדש (הזמנות, קישור); תוצאת החזרה; } 

השיטה שלנו מחזירה א CollectionModel מתנגד לציית לסוג ההחזר של HAL, כמו גם "_עצמי" קישור לכל אחת מההזמנות והרשימה המלאה.

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

6. קישורים לשיטות בקר

ה WebMvcLinkBuilder מציע תמיכה עשירה לבקרי MVC באביב. הדוגמה הבאה מראה כיצד לבנות קישורי HATEOAS בהתבסס על getOrdersForCustomer () שיטת ה- CustomerController מעמד:

קישור קישורים Link = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithRel ("allOrders"); 

ה methodOn () משיג את מיפוי השיטה על ידי הפעלת דמה של שיטת היעד בבקר ה- proxy וקובע את ה- מספר לקוח כמשתנה הנתיב של ה- URI.

7. אביב HATEOAS בפעולה

בואו נקביד את יצירת הקישור העצמי וקישור השיטה getAllCustomers () שיטה:

@GetMapping (מפיק = {"application / hal + json"}) אוסף ציבורי מודל getAllCustomers () {רשימה allCustomers = customerService.allCustomers (); עבור (לקוח לקוח: allCustomers) {String customerId = customer.getCustomerId (); קישור selfLink = linkTo (CustomerController.class) .slash (customerId) .withSelfRel (); customer.add (קישור עצמי); if (orderService.getAllOrdersForCustomer (customerId) .size ()> 0) {Link ordersLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). withRel ("allOrders"); customer.add (ordersLink); }} קישור קישור = linkTo (CustomerController.class) .withSelfRel (); תוצאת CollectionModel = CollectionModel חדש (allCustomers, קישור); תוצאת החזרה; }

לאחר מכן, בוא נפעיל את getAllCustomers () שיטה:

תלתל // localhost: 8080 / אביב-אבטחה-מנוחה / API / לקוחות 

ובחנו את התוצאה:

{"_embedded": {"customerList": [{"customerId": "10A", "customerName": "Jane", "companyName": "ABC Company", "_links": {"self": {"href" : "// localhost: 8080 / spring-security-rest / api / clients / 10A"}, "allOrders": {"href": "// localhost: 8080 / spring-security-rest / api / clients / 10A / הזמנות "}}}, {" customerId ":" 20B "," customerName ":" Bob "," companyName ":" XYZ Company "," _links ": {" self ": {" href ":" // localhost : 8080 / spring-security-rest / api / clients / 20B "}," allOrders ": {" href ":" // localhost: 8080 / spring-security-rest / api / clients / 20B / orders "}}} , {"customerId": "30C", "customerName": "Tim", "companyName": "CKV Company", "_links": {"self": {"href": "// localhost: 8080 / spring- security-rest / api / clients / 30C "}}}}}," _links ": {" self ": {" href ":" // localhost: 8080 / spring-security-rest / api / clients "}}}

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

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

תלתל // localhost: 8080 / אביב-אבטחה-מנוחה / API / לקוחות / 10A / הזמנות 

{"_embedded": {"orderList": [{"orderId": "001A", "price": 150, "amount": 25, "_links": {"self": {"href": "// localhost : 8080 / spring-security-rest / api / clients / 10A / 001A "}}}, {" orderId ":" 002A "," price ": 250," כמות ": 15," _links ": {" self " : {"href": "// localhost: 8080 / spring-security-rest / api / clients / 10A / 002A"}}}]}, "_links": {"self": {"href": "// localhost: 8080 / spring-security-rest / api / clients / 10A / orders "}}}

8. מסקנה

במדריך זה דנו כיצד לבנות שירות רשת Spring REST מונע היפר-מדיה באמצעות פרויקט Spring HATEOAS.

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

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

לבסוף, ניתן למצוא את היישום המלא של מאמר זה בפרויקט GitHub.

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