מבוא לפיין

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

במדריך זה נציג את Feign - לקוח HTTP הצהרתי שפותח על ידי Netflix.

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

2. דוגמא

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

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

mvn להתקין את האביב: הפעל

3. התקנה

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

 io.github.openfeign feign-okhttp 10.11 io.github.openfeign feign-gson 10.11 io.github.openfeign feign-slf4j 10.11 

מלבד התלות של ליבת הקוי (שנמשכת גם היא), נשתמש בכמה תוספים, במיוחד: feign-okhttp לשימוש פנימי בלקוח OkHttp של Square בכדי להגיש בקשות, feign-gson לשימוש ב- GSON של גוגל כמעבד JSON ו- feign- slf4j לשימוש ב- חזית רישום פשוטה לרשום בקשות.

כדי להשיג מעט פלט יומן, נצטרך הטמעת לוגר מועדפת עלינו, הנתמכת על ידי SLF4J, על מסלול הכיתה.

לפני שנמשיך ליצור ממשק הלקוח שלנו, ראשית נגדיר סֵפֶר מודל להחזקת הנתונים:

ספר בכיתה ציבורית {מחרוזת פרטית isbn; סופר מחרוזת פרטי; כותרת מחרוזת פרטית; תקציר מחרוזת פרטי; שפת מחרוזת פרטית; // קונסטרוקטור סטנדרטי, גטרים וקובעים}

הערה: לפחות מעבד JSON זקוק ל"בונה טיעונים ללא ".

למעשה, ספק ה- REST שלנו הוא ממשק API המונע על ידי היפר-מדיה, כך שנצטרך בנוסף לשיעור עטיפה פשוט:

ספר BookResource {ספר ספר פרטי פרטי; // קונסטרוקטור סטנדרטי, גטרים וקובעים}

הערה: אָנוּאני אשמור את BookResource פשוט מכיוון שלקוח ה- Feign המדגם שלנו לא נהנה מתכונות של hypermedia!

4. צד השרת

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

בואו ננסה זאת עם פקודת מעטפת תלתלים פשוטה כדי לרשום את כל הספרים. עלינו לזכור להקדים את כל השיחות / api, שהוא הקשר ה- servlet של היישום:

תלתל // localhost: 8081 / api / ספרים

כתוצאה מכך נקבל מאגר ספרים מלא המיוצג כ- JSON:

[{"book": {"isbn": "1447264533", "author": "Margaret Mitchell", "title": "נעלם עם הרוח", "תקציר": null, "language": null}, "links ": [{" rel ":" self "," href ":" // localhost: 8081 / api / books / 1447264533 "}]}, ... {" book ": {" isbn ":" 0451524934 ", "author": "George Orwell", "title": "1984", "synopsis": null, "language": null}, "links": [{"rel": "self", "href": "/ / localhost: 8081 / api / books / 0451524934 "}]}]

אנו יכולים גם לשאול אנשים סֵפֶר משאב, על ידי הוספת ה- ISBN לבקשה לקבל:

תלתל // localhost: 8081 / api / books / 1447264533

5. לקוח פיין

לסיום, בואו נגדיר את לקוח ה- Feign שלנו.

נשתמש ב- @RequestLine ביאור לציון הפועל HTTP וחלק נתיב כארגומנט. הפרמטרים יעוצבו באמצעות @ פארם ביאור:

ממשק ציבורי BookClient {@RequestLine ("GET / {isbn}") BookResource findByIsbn (@Param ("isbn") מחרוזת isbn); @RequestLine ("GET") רשימה findAll (); @RequestLine ("POST") @Headers ("סוג תוכן: יישום / json") בטל ליצור (ספר ספרים); }

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

זה הכל! עכשיו נשתמש ב- Feign.builder () להגדרת התצורה של הלקוח מבוסס הממשק שלנו. היישום בפועל יועבר בזמן הריצה:

BookClient bookClient = Feign.builder () .client (חדש OkHttpClient ()). Encoder (GsonEncoder חדש ()). מפענח (GsonDecoder חדש ()). לוגר (חדש Slf4jLogger (BookClient.class)) .logLevel (Logger.Level. FULL) .target (BookClient.class, "// localhost: 8081 / api / books");

Feign תומך בתוספים שונים כגון מקודדי JSON / XML ומפענחים או לקוח HTTP בסיסי לביצוע הבקשות.

6. מבחן יחידה

בואו ניצור שלושה מקרי מבחן כדי לבדוק את הלקוח שלנו. שים לב, אנו משתמשים בייבוא ​​סטטי עבור org.hamcrest.CoreMatchers. * ו org.junit.Assert. *:

@Test ציבורי בטל שניתןBookClient_shouldRun בהצלחה () זורק חריג {List books = bookClient.findAll (). Stream () .map (BookResource :: getBook) .collect (Collectors.toList ()); assertTrue (books.size ()> 2); } @Test הציבור בטל שניתןBookClient_shouldFindOneBook () זורק חריג {ספר ספר = bookClient.findByIsbn ("0151072558"). GetBook (); assertThat (book.getAuthor (), containString ("אורוול")); } @Test הריק ציבורי שניתןBookClient_shouldPostBook () זורק חריג {מחרוזת isbn = UUID.randomUUID (). ToString (); ספר ספרים = ספר חדש (isbn, "אני", "זה אני!", Null, null); bookClient.create (ספר); book = bookClient.findByIsbn (isbn) .getBook (); assertThat (book.getAuthor (), הוא ("אני")); } 

7. קריאה נוספת

אם אנו זקוקים לסוג של חיסרון במקרה של זמינות השירות, נוכל להוסיף את HystrixFeign למסלול הכיתה ולבנות את הלקוח שלנו עם HystrixFeign.builder ().

עיין בסדרת הדרכה ייעודית זו למידע נוסף על Hystrix.

בנוסף, אם נרצה לשלב את Spring Cloud Netflix Hystrix עם Feign, יש מאמר ייעודי כאן.

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

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

BookClient bookClient = Feign.builder () .client (RibbonClient.create ()) .target (BookClient.class, "// localhost: 8081 / api / books");

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

8. מסקנה

במאמר זה, הסברנו כיצד לבנות לקוח HTTP הצהרתי באמצעות Feign לצרוך ממשקי API מבוססי טקסט.

כרגיל, כל דגימות הקוד המוצגות במדריך זה זמינות ב- GitHub.