streamalism.org

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

במדריך זה נתאר את Spring Cloud OpenFeign - לקוח REST הצהרתי לאפליקציות Spring Boot.

Feign מקל על כתיבת לקוחות שירות אינטרנט באמצעות תמיכה בהערות ניתנות לחיבור, הכוללות הערות Feign והערות JAX-RS.

כמו כן, Spring Cloud מוסיף תמיכה בהערות Spring MVC ובשימוש באותן HttpMessageConverters כפי ששימש באינטרנט באביב.

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

2. תלות

ראשית, נתחיל ביצירת פרויקט אינטרנט של אתחול Spring והוספת ה- אביב-ענן-starter-openfeign תלות שלנו pom.xml קוֹבֶץ:

 org.springframework.cloud spring-cloud-starter-openfeign 

כמו כן, נצטרך להוסיף את ה- תלות באביב-ענן:

    org.springframework.cloud אביב-ענן-תלות $ {spring-cloud.version} יבוא pom 

אנו יכולים למצוא את הגרסאות העדכניות ביותר של אביב-ענן-starter-openfeign ו תלות באביב-ענן במרכז מייבן.

3. לקוח פיין

לאחר מכן, עלינו להוסיף @EnableFeignClients למעמד הראשי שלנו:

@SpringBootApplication @EnableFeignClients class public דוגמהApplication {public static void main (String [] args) {SpringApplication.run (ExampleApplication.class, args); }}

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

לאחר מכן, אנו מצהירים שלקוח פייגן משתמש ב- @FeignClient ביאור:

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/") ממשק ציבורי JSONPlaceHolderClient {@RequestMapping (method = RequestMethod.GET, value = "/ posts") רשימת getPosts (); @RequestMapping (method = RequestMethod.GET, value = "/ posts / {postId}", מייצר = "application / json") Post getPostById (@PathVariable ("postId") PostId ארוך); }

בדוגמה זו הגדרנו לקוח לקרוא מממשקי ה- API של JSONPlaceHolder.

ה ערך הוויכוח שהועבר ב @FeignClient הערה היא שם לקוח חובה ושרירותי, ואילו עם url אנו מגדירים את כתובת ה- URL הבסיסית של ה- API.

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

4. תצורה

עכשיו, חשוב מאוד להבין זאת כל לקוח של Feign מורכב ממכלול של רכיבים הניתנים להתאמה אישית.

Spring Cloud יוצר הגדרת ברירת מחדל חדשה לפי דרישה עבור כל לקוח עם שם FeignClientsConfiguration בכיתה שנוכל להתאים אישית כמוסבר בסעיף הבא.

המחלקה לעיל מכילה שעועית זו:

• מפענח - ResponseEntityDecoder, שעוטף SpringDecoder, נהג לפענח את תְגוּבָה
• מקודד - SpringEncoder, משמש לקידוד ה- RequestBody
• לוגר - Slf4jLogger הוא לוגר ברירת המחדל המשמש את Feign
• חוזה - SpringMvcContract, המספק עיבוד הערות
• Feign-Builder - HystrixFeign.Builder משמש לבניית הרכיבים
• לקוח - LoadBalancerFeignClient או לקוח Feign המוגדר כברירת מחדל

4.1. תצורת שעועית מותאמת אישית

אם אנו רוצים להתאים אישית אחת או יותר מהשעועית הזו, אנו יכולים לעקוף אותם באמצעות a @תְצוּרָה בכיתה, אותה אנו מוסיפים לאחר מכן ל- FeignClient ביאור:

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/", תצורה = MyClientConfiguration.class)

@Configuration מחלקה ציבורית MyClientConfiguration {@Bean לקוח OkHttpClient ציבורי () {להחזיר OkHttpClient חדש (); }}

בדוגמה זו אנו אומרים לפיין להשתמש OkHttpClient במקום ברירת המחדל שתומכת ב- HTTP / 2.

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

כדי להשתמש בלקוחות אלה, אל נשכח להוסיף את התלות הנדרשת ללקוחותינו pom.xml קובץ, למשל:

 io.github.openfeign feign-okhttp io.github.openfeign feign-httpclient 

אנו יכולים למצוא את הגרסאות העדכניות ביותר של feign-okhttp ו feign-httpclient במרכז מייבן.

4.2. תצורה באמצעות מאפיינים

במקום להשתמש ב- @תְצוּרָה מעמד, אנו יכולים להשתמש במאפייני יישומים להגדרת תצורת לקוחות Feign, כפי שמוצג בזה application.yaml דוגמא:

feign: client: config: default: connectTimeout: 5000 readTimeout: 5000 loggerLevel: basic

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

לבסוף, אנו יכולים ליצור את התצורה עם בְּרִירַת מֶחדָל כשם הלקוח להגדרת הכל @FeignClient אובייקטים, או שנוכל להכריז על שם הלקוח הקבוע לתצורה:

feign: client: config: jplaceholder:

אם יש לנו את שניהם @תְצוּרָה מאפייני שעועית ותצורה, מאפייני התצורה יעקפו @תְצוּרָה ערכים.

5. מיירטים

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

המיירטים יכולים לבצע מגוון משימות מרומזות, החל מאימות וכלה ברישום, לכל בקשת / תגובת HTTP.

בחלק זה נבצע יירוט משלנו ונשתמש בזה שמספק Spring Cloud OpenFeign מחוץ לקופסה. שניהם ירצו הוסף כותרת אימות בסיסית לכל בקשה.

5.1. יישום RequestInterceptor

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

@Bean RequestInterceptor הציבורInterceptor () {return requestTemplate -> {requestTemplate.header ("משתמש", שם משתמש); requestTemplate.header ("סיסמה", סיסמה); requestTemplate.header ("קבל", ContentType.APPLICATION_JSON.getMimeType ()); }; }

כמו כן, כדי להוסיף את המיירט לשרשרת הבקשות, עלינו רק להוסיף את השעועית הזו שלנו @תְצוּרָה class, או כפי שראינו קודם, הכריז על כך בקובץ המאפיינים:

feign: client: config: default: requestInterceptors: com.baeldung.cloud.openfeign.JSONPlaceHolderInterceptor

5.2. באמצעות BasicAuthRequestInterceptor

לחלופין, אנו יכולים להשתמש ב- BasicAuthRequestInterceptor הכיתה שמציעה ענן האביב OpenFeign:

@Bean ציבורי BasicAuthRequestInterceptor basicAuthRequestInterceptor () {להחזיר BasicAuthRequestInterceptor חדש ("שם משתמש", "סיסמה"); }

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

6. תמיכה בהיסטריקס

Feign תומך ב- Hystrix, אז אם הפעלנו את זה, אנו יכולים ליישם את דפוס החזרת.

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

כדי להשיג את המטרה, עלינו לאפשר הוספה של Hystrix feign.hystrix.enabled = נכון בקובץ המאפיינים.

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

מחלקה ציבורית @Component JSONPlaceHolderFallback מיישמת JSONPlaceHolderClient {@Override public List getPosts () {return Collections.emptyList (); } @Override הודעה ציבורית getPostById (Long postId) {return null; }}

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

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/", fallback = JSONPlaceHolderFallback.class) ממשק ציבורי JSONPlaceHolderClient {// APIs}

7. כניסה

עבור כל לקוח של Feign, יוצר לוגר כברירת מחדל.

כדי לאפשר רישום, עלינו להכריז על כך ב application.propertieקובץ s באמצעות שם החבילה של ממשקי הלקוח:

logging.level.com.baeldung.cloud.openfeign.client: DEBUG

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

logging.level.com.baeldung.cloud.openfeign.client.JSONPlaceHolderClient: DEBUG

שים לב כי רישום Feign מגיב רק ל- לנפות רָמָה.

ה לוגר. רמה שנוכל להגדיר לכל לקוח מציין כמה לרשום:

@Configuration מחלקה ציבורית ClientConfiguration {@Bean Logger.Level feignLoggerLevel () {return Logger.Level.BASIC; }}

ישנן ארבע רמות רישום לבחירה:

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

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

מטפל השגיאות המוגדר כברירת מחדל של פייגן, ErrorDecoder.default, תמיד זורק א FeignException.

כעת, התנהגות זו אינה תמיד השימושית ביותר. כך, כדי להתאים אישית את החריג שנזרק, נוכל להשתמש ב- CustomErrorDecoder:

מחלקה ציבורית CustomErrorDecoder מיישם את ErrorDecoder {@ Override public Exception decode (String methodKey, Response response) {switch (response.status ()) {case 400: להחזיר BadRequestException חדש (); מקרה 404: להחזיר NotFoundException חדש (); ברירת מחדל: להחזיר חריג חדש ("שגיאה כללית"); }}}

ואז, כפי שעשינו בעבר, עלינו להחליף את ברירת המחדל מפענח שגיאה על ידי הוספת שעועית ל @תְצוּרָה מעמד:

מחלקה ציבורית @Configuration ClientConfiguration {@Bean ErrorDecoder הציבורי errorDecoder () {להחזיר CustomErrorDecoder חדש (); }}

9. מסקנה

במאמר זה עמדנו על Spring Cloud OpenFeign ועל יישומו ביישום מדגם פשוט.

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

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