שימוש בתיקון JSON ב- REST API של Spring

1. הקדמה

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

במדריך זה נבדוק כיצד להשתמש בשיטת HTTP PATCH יחד עם פורמט מסמך ה- JSON Patch כדי להחיל עדכונים חלקיים על משאבי RESTful שלנו.

2. מקרה השימוש

נתחיל בבחינת דוגמה ל- HTTP צרכן משאב המיוצג על ידי מסמך JSON:

{"id": "1", "telephone": "001-555-1234", "favourites": ["Milk", "Eggs"], "communicationPreferences": {"post": true, "email": נכון}}

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

איך היינו עושים את זה?

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

זה המקום שבו שיטת HTTP PATCH שימושית.

בואו נבין את שיטת ה- HTTP PATCH ואת הפורמטים של JSON Patch.

3. שיטת ה- HTTP PATCH ותבנית התיקון JSON

שיטת HTTP PATCH מציעה דרך נחמדה ליישם עדכונים חלקיים על המשאבים. כתוצאה מכך, הלקוחות צריכים לשלוח רק את ההבדלים בבקשות שלהם.

בואו נסתכל על דוגמה פשוטה לבקשת HTTP PATCH:

PATCH / לקוחות / 1234 HTTP / 1.1 מארח: www.example.com סוג תוכן: יישום / דוגמה If-Match: "e0023aa4e" אורך תוכן: 100 [תיאור שינויים]

גוף בקשת ה- HTTP PATCH מתאר כיצד יש לשנות את משאב היעד כדי לייצר גרסה חדשה. יתר על כן, הפורמט המשמש לייצוג ה- [תיאור השינויים] משתנה בהתאם לסוג המשאב. עבור סוגי משאבים של JSON, הפורמט המשמש לתיאור השינויים הוא תיקון JSON.

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

בואו נסתכל כעת על פעולות תיקון JSON יחד עם כמה דוגמאות.

4. פעולות תיקון JSON

פעולת תיקון JSON מיוצגת על ידי יחיד אופ לְהִתְנַגֵד.

לדוגמה, כאן אנו מגדירים פעולת תיקון JSON לעדכון מספר הטלפון של הלקוח:

{"op": "להחליף", "path": "/ טלפון", "value": "001-555-5678"}

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

בואו נסתכל בקצרה על פעולות ה- JSON Patch הזמינות.

4.1. ה לְהוֹסִיף מבצע

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

לדוגמא, בואו נוסיף "לחם" ללקוח מועדפים רשימה באינדקס 0:

{"op": "add", "path": "/ favourites / 0", "value": "לחם"}

פרטי הלקוח ששונו לאחר לְהוֹסִיף הפעולה תהיה:

{"id": "1", "telephone": "001-555-1234", "favourites": ["Bread", "Milk", "Eggs"], "communicationPreferences": {"post": true, "דוא"ל": נכון}}

4.2. ה לְהַסִיר מבצע

ה לְהַסִיר פעולה מסירה ערך במיקום היעד. חוץ מזה, הוא יכול להסיר אלמנט ממערך באינדקס שצוין.

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

{"op": "remove", "path": "/ communicationPreferences"}

פרטי הלקוח ששונו לאחר לְהַסִיר הפעולה תהיה:

{"id": "1", "telephone": "001-555-1234", "favourites": ["לחם", "חלב", "ביצים"], "communicationPreferences": null}

4.3. ה החלף מבצע

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

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

{"op": "להחליף", "path": "/ טלפון", "value": "001-555-5678"}

פרטי הלקוח ששונו לאחר החלף הפעולה תהיה:

{"id": "1", "telephone": "001-555-5678", "favourites": ["Bread", "Milk", "Eggs"], "communicationPreferences": null}

4.4. ה מהלך \ לזוז \ לעבור מבצע

ה מהלך \ לזוז \ לעבור פעולה מסירה את הערך במיקום שצוין ומוסיפה אותו למיקום היעד.

למשל, בואו נעביר את "לחם" מהחלק העליון של הלקוח מועדפים רשימה לתחתית הרשימה:

{"op": "move", "from": "/ favorites / 0", "path": "/ favorites / -"}

פרטי הלקוח ששונו לאחר מהלך \ לזוז \ לעבור הפעולה תהיה:

{"id": "1", "telephone": "001-555-5678", "favourites": ["חלב", "ביצים", "לחם"], "communicationPreferences": null} 

ה / מועדפים / 0 ו / מועדפים / - בדוגמה שלעיל מצביעים על JSON על מדדי ההתחלה והסיום של מועדפים מַעֲרָך.

4.5. ה עותק מבצע

ה עותק פעולה מעתיקה את הערך במיקום שצוין למיקום היעד.

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

{"op": "copy", "from": "/ favorites / 0", "path": "/ favorites / -"}

פרטי הלקוח ששונו לאחר עותק הפעולה תהיה:

{"id": "1", "טלפון": "001-555-5678", "favourites": ["חלב", "ביצים", "לחם", "חלב"], "תקשורת העדפות": null}

4.6. ה מִבְחָן מבצע

ה מִבְחָן הפעולה בודקת שהערך ב"נתיב "שווה ל"ערך". מכיוון שפעולת ה- PATCH היא אטומית, יש להשליך את ה- PATCH אם כל אחת מפעולותיה נכשלת. ה מִבְחָן ניתן להשתמש בפעולה על מנת לאמת כי התקיימו התנאים המוקדמים והתנאים שלאחר מכן.

לדוגמה, בואו נבדוק את העדכון ללקוח טֵלֵפוֹן התחום הצליח:

{"op": "test", "path": "/ telephone", "value": "001-555-5678"} 

בואו נראה כעת כיצד נוכל ליישם את המושגים הנ"ל על הדוגמה שלנו.

5. בקשת תיקון HTTP באמצעות תבנית תיקון JSON

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

הנה בקשת ה- HTTP PATCH לבצע עדכון חלקי ללקוח טֵלֵפוֹן ו מועדפים רשימה באמצעות פורמט התיקון JSON:

תלתל -i -X ​​PATCH // localhost: 8080 / לקוחות / 1 -H "סוג תוכן: יישום / json-patch + json" -d '[{"op": "להחליף", "path": "/ טלפון "," value ":" + 1-555-56 "}, {" op ":" add "," path ":" / favourites / 0 "," value ":" Bread "}] ' 

והכי חשוב, ה סוג תוכן עבור בקשות תיקון JSON הוא יישום / json-patch + json. כמו כן, גוף הבקשה הוא מערך אובייקטים של פעולת תיקון JSON:

[{"op": "להחליף", "נתיב": "/ טלפון", "value": "+ 1-555-56"}, {"op": "הוסף", "נתיב": "/ favorites / 0 "," value ":" לחם "}]

כיצד נעבד בקשה כזו בצד השרת?

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

למרבה המזל, איננו נדרשים לעבד באופן ידני את העיבוד של בקשות תיקון JSON.

ה- API של Java לעיבוד JSON 1.0, או JSON-P 1.0, שהוגדר במקור ב- JSR 353, הציג תמיכה בתיקון JSON ב- JSR 374. ה- API של JSON-P מספק את JsonPatch הקלד כדי לייצג את יישום תיקון JSON.

עם זאת, JSON-P הוא רק API. כדי לעבוד עם ה- JSON-P API, עלינו להשתמש בספרייה המיישמת אותו. נשתמש בספרייה כזו בשם json-patch עבור הדוגמאות במאמר זה.

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

6. יישום תיקון JSON ביישום אתחול האביב

6.1. תלות

הגרסה האחרונה של json-patch נמצאת במאגר Maven Central.

ראשית, בואו נוסיף את התלות ל- pom.xml:

 com.github.java-json-tools json-patch 1.12 

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

לקוח ממעמד ציבורי {מזהה מחרוזת פרטי; טלפון מחרוזת פרטי; מועדפים רשימה פרטית; תקשורת מפות פרטית העדפות; // סטרים וקובעים סטנדרטיים}

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

6.2. שיטת בקר ה- REST

לאחר מכן, אנו יכולים ליישם HTTP PATCH למקרה לשימוש הלקוחות שלנו:

@PatchMapping (path = "/ {id}", consumes = "application / json-patch + json") עדכוני תגובה ResponseEntityCustomer (@PathVariable מזהה מחרוזת, @RequestBody JsonPatch תיקון) {נסה {Customer customer = customerService.findCustomer (id) .orElseThrow (CustomerNotFoundException :: חדש); לקוח customerPatched = להחיל תיקון לקוח (תיקון, לקוח); customerService.updateCustomer (customerPatched); החזר ResponseEntity.ok (customerPatched); } לתפוס (JsonPatchException | JsonProcessingException e) {return ResponseEntity.status (HttpStatus.INTERNAL_SERVER_ERROR) .build (); } לתפוס (CustomerNotFoundException e) {return ResponseEntity.status (HttpStatus.NOT_FOUND) .build (); }} 

בואו נבין כעת מה קורה בשיטה זו:

  • ראשית, אנו משתמשים ב- @ תיקון מיפוי ביאור לסימון השיטה כשיטת מטפל PATCH
  • כאשר בקשת תיקון עם יישום / json-patch + json "סוג תוכן" מגיע, Spring Boot משתמש בברירת המחדל MappingJackson2HttpMessageConverter להמיר את מטען המטען לבקשה ל- JsonPatch למשל. כתוצאה מכך, שיטת הבקר שלנו תקבל את גוף הבקשה כ- JsonPatch למשל

במסגרת השיטה:

  1. ראשית, אנו קוראים customerService.findCustomer (מזהה) שיטה למצוא את שיא הלקוח
  2. לאחר מכן, אם נמצא רישום הלקוח, אנו קוראים את ApplyPatchToCustomer (תיקון, לקוח) שיטה. זה חל על JsonPatch ללקוח (עוד על כך בהמשך)
  3. לאחר מכן אנו קוראים את customerService.updateCustomer (customerPatched) כדי לשמור את שיא הלקוחות
  4. לבסוף, אנו מחזירים א 200 בסדר תגובה ללקוח באמצעות התיקון צרכן פרטים בתגובה

והכי חשוב, הקסם האמיתי קורה ב ApplyPatchToCustomer (תיקון, לקוח) שיטה:

לקוח פרטי applyPatchToCustomer (תיקון JsonPatch, Customer targetCustomer) זורק את JsonPatchException, JsonProcessingException {JsonNode patched = patch.apply (objectMapper.convertValue (targetCustomer, JsonNode.class)); להחזיר objectMapper.treeToValue (טלאי, Customer.class); } 
  1. ראשית, יש לנו את שלנו JsonPatch מופע המכיל את רשימת הפעולות המיושמות על היעד צרכן
  2. לאחר מכן אנו ממירים את היעד צרכן למופע של com.fasterxml.jackson.databind.JsonNode ולהעביר אותו ל JsonPatch. החל שיטה ליישום התיקון. מאחורי הקלעים, JsonPatch. החל עוסק ביישום הפעולות על היעד. התוצאה של התיקון היא גם א com.fasterxml.jackson.databind.JsonNode למשל
  3. לאחר מכן אנו קוראים objectMapper.treeToValue שיטה, המחברת את הנתונים בתיקון com.fasterxml.jackson.databind.JsonNode אל ה צרכן סוּג. זה התיקון שלנו צרכן למשל
  4. לבסוף, אנו מחזירים את הטלאים צרכן למשל

בואו נערוך כעת כמה בדיקות מול ה- API שלנו.

6.3. בדיקה

ראשית, בואו ניצור לקוח באמצעות בקשת POST לממשק ה- API שלנו:

תלתל -אי -X POST // localhost: 8080 / לקוחות -H "סוג תוכן: יישום / json" -d '{"טלפון": "+ 1-555-12", "מועדפים": ["חלב", "ביצים"], "communicationPreferences": {"post": true, "email": true}} ' 

אנו מקבלים א 201 נוצר תְגוּבָה:

HTTP / 1.1 201 מיקום: // localhost: 8080 / לקוחות / 1 

ה מקום כותרת התגובה מוגדרת למיקום המשאב החדש. זה מצביע על כך שה- תְעוּדַת זֶהוּת של החדש צרכן הוא 1.

בשלב הבא, נבקש עדכון חלקי ללקוח זה באמצעות בקשת PATCH:

תלתל -i -X ​​PATCH // localhost: 8080 / לקוחות / 1 -H "סוג תוכן: יישום / json-patch + json" -d '[{"op": "להחליף", "path": "/ טלפון "," value ":" + 1-555-56 "}, {" op ":" add "," path ":" / favourites / 0 "," value ":" Bread "}] '

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

HTTP / 1.1 200 סוג תוכן: יישום / json העברת קידוד: chunked תאריך: יום שישי, 14 בפברואר 2020 21:23:14 GMT {"id": "1", "טלפון": "+ 1-555-56" , "favourites": ["Bread", "Milk", "Eggs"], "communicationPreferences": {"post": true, "email": true}}

7. מסקנה

במאמר זה בדקנו כיצד ליישם את תיקון JSON בממשקי API של REST באביב.

ראשית, בדקנו את שיטת HTTP PATCH ואת יכולתה לבצע עדכונים חלקיים.

לאחר מכן בדקנו מהו תיקון JSON והבנו את פעולות התיקון השונות של JSON.

לבסוף, דנו כיצד לטפל בבקשת HTTP PATCH ביישום Spring Boot באמצעות ספריית json-patch.

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


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