streamalism.org

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

במדריך זה נסייר בסביבת RESTX קלה של Java REST.

2. תכונות

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

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

זה מורשה גם תחת רישיון Apache 2 ומתוחזק על ידי קהילת מפתחים. הדרישה המינימלית של Java עבור RESTX היא JDK 7.

3. תצורה

RESTX מגיע עם אפליקציית מעטפת / פקודה שימושית, אשר שימושית לאתחול מהיר של פרויקט Java.

עלינו להתקין את האפליקציה תחילה לפני שנוכל להמשיך. הוראות ההתקנה המפורטות זמינות כאן.

4. התקנת תוספי ליבה

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

במעטפת RESTX, בוא נפעיל את הפקודה הבאה:

התקנת מעטפת

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

5. מעטפת אפליקציית מעטפת

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

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

אפליקציה חדשה

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

מאז בחרנו לייצר pom.xml, ניתן לייבא את הפרויקט בקלות לכל Java IDE רגיל.

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

הצעד הבא שלנו יהיה לבנות את הפרויקט:

התקנה נקייה mvn -DskipTests

ברגע שהבנייה תצליח נוכל להריץ את AppServer בכיתה כ- Java Application מה- IDE. פעולה זו תפעיל את השרת עם מסוף הניהול, ויאזין ביציאה 8080.

אנחנו יכולים לדפדף אל //127.0.0.1:8080/api/@/ui וראה את ממשק המשתמש הבסיסי.

המסלולים המתחילים ב- /@/ משמשים למסוף הניהול שהוא נתיב שמור ב- RESTX.

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

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

6. משאב RESTX

המסלולים מוגדרים ב <main_package> .rest.HelloResource מעמד:

@Component @RestxResource מחלקה ציבורית HelloResource {@GET ("/ message") @RolesAllowed (Roles.HELLO_ROLE) הודעה ציבורית sayHello () {להחזיר הודעה חדשה (). SetMessage (String.format ("שלום% s, זה% s") , RestxSession.current (). GetPrincipal (). Get (). GetName (), DateTime.now (). ToString ("HH: mm: ss"))); }}

מיד ניכר כי RESTX משתמש בהערות ברירת מחדל של J2EE לצורך קשירת אבטחה ו- REST. לרוב, הוא משתמש בהערות משלו לצורך הזרקת תלות.

RESTX תומך גם ברירות מחדל סבירות רבות למיפוי פרמטרים של שיטות מיפוי לבקשה.

בנוסף, ההערות הסטנדרטיות הללו הן @ RestxResource, שמצהיר על כך כמשאב ש- RESTX מכיר בו.

נתיב הבסיס מתווסף ב src / main / webapp / WEB-INF / web.xml. במקרה שלנו, זה / api, כדי שנוכל לשלוח בקשת GET אל // localhost: 8080 / api / message, בהנחה על אימות נכון.

ה הוֹדָעָה class הוא רק שעועית ג'אווה ש- RESTX מסדרת ל- JSON.

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

7. כיתת המודולים

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

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

@Module public class AppModule {@Provides public SignatureKey signatureKey () {return new SignatureKey ("restx-demo -44749418370 restx-demo 801f-4116-48f2-906b" .getBytes (Charsets.UTF_8)); } @Provides @Named ("restx.admin.password") ציבורי מחרוזת restxAdminPassword () {להחזיר "1234"; } @ מספק ConfigSupplier ציבורי appConfigSupplier (ConfigLoader configLoader) {להחזיר configLoader.fromResource ("restx / demo / settings"); } // שיטות ספק אחרות ליצירת רכיבים}

@Module מגדיר מחלקה שיכולה להגדיר רכיבים אחרים, בדומה ל- @Module בפגיון, או @תְצוּרָה באביב.

@Provides חושף רכיב באופן פרוגרמטי, כמו @Provides בפגיון, או @אפונה באביב.

ולבסוף, @ שמות הערה משמשת לציון שם הרכיב המיוצר.

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

HTTP / 1.1 200 בסדר ... Set-Cookie: RestxSessionSignature-restx-demo = "ySfv8FejvizMMvruGlK3K2hwdb8 ="; RestxSession-restx-demo = "..." ...

ועיין בתיעוד המפעל של רכיבי RESTX / הזרקת תלות לקבלת מידע נוסף.

8. מחלקת המשגר

ולבסוף, ה AppServer class משמש להפעלת היישום כאפליקציית Java רגילה בשרת Jetty מוטבע:

Class class AppServer {public static final מחרוזת WEB_INF_LOCATION = "src / main / webapp / WEB-INF / web.xml"; גמר סטטי ציבורי מחרוזת WEB_APP_LOCATION = "src / main / webapp"; main public סטטי ריק (String [] args) זורק Exception {int port = Integer.valueOf (Optional.fromNullable (System.getenv ("PORT")). או ("8080")); שרת WebServer = Jetty8WebServer חדש (WEB_INF_LOCATION, WEB_APP_LOCATION, יציאה, "0.0.0.0"); System.setProperty ("restx.mode", System.getProperty ("restx.mode", "dev")); System.setProperty ("restx.app.package", "restx.demo"); server.startAndAwait (); }}

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

אנו יכולים לארוז את האפליקציה כ- מִלחָמָה (ארכיון אינטרנט) קובץ לפרוס במיכל אינטרנט עצמאי J2EE.

בואו נגלה כיצד לבדוק את האפליקציה בחלק הבא.

9. בדיקת אינטגרציה באמצעות מפרט

אחד המאפיינים החזקים של RESTX הוא המושג "מפרט". דוגמית מפרט ייראה כך:

כותרת: צריך מנהל להגיד שלום נתון: - זמן: 2013-08-28T01: 18: 00.822 + 02: 00 wts: - מתי: | קבל שלום? מי = חאוויר אז: | {"message": "שלום xavier, השעה 01:18:00"}

הבדיקה נכתבת במבנה נתון-מתי ואז בתוך קובץ YAML שמגדיר בעצם כיצד ה- API צריך להגיב (לאחר מכן) לבקשה ספציפית (מתי) בהתחשב במצב הנוכחי של המערכת (נָתוּן).

ה HelloResourceSpecTest כיתה ב src / test / resources יפעיל את המבחנים הכתובים במפרט לעיל:

@RunWith (RestxSpecTestsRunner.class) @FindSpecsIn ("מפרט / שלום") מחלקה ציבורית HelloResourceSpecTest {}

ה RestxSpecTestsRunner class הוא רץ JUnit מותאם אישית. הוא מכיל כללי JUnit מותאמים אישית ל:

• להקים שרת משובץ
• להכין את מצב המערכת (לפי נָתוּן סעיף במפרט)
• הוציאו את הבקשות שצוינו, ו-
• לאמת את התגובות הצפויות

ה @FindSpecsIn ביאור מצביע על הנתיב של קבצי המפרט שלפיהם יש להריץ את הבדיקות.

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

10. בדיקה ידנית

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

חשיש md5 

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

סלסול -b u1 -c u1 -X POST -H "סוג תוכן: יישום / json" -d '{"principal": {"name": "admin", "passwordHash": "1d528266b85cf052803a57288"}}' // localhost: 8080 / api / session

(שים לב שמשתמשי Windows צריכים להוריד תחילה תלתל.)

ועכשיו, אם נשתמש בפגישה כחלק מהפגישה שלנו /הוֹדָעָה בַּקָשָׁה:

תלתל -b u1 "// localhost: 8080 / api / message? who = restx"

ואז נקבל משהו כזה:

{"message": "שלום מנהל, השעה 09:56:51"}

11. חקר מסוף הניהול

מסוף הניהול מספק משאבים שימושיים לשליטה באפליקציה.

בואו נסתכל על תכונות המפתח על ידי גלישה אל //127.0.0.1:8080/admin/@/ui.

11.1. מסמכי API

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

ונוכל ללחוץ על מסלולים בודדים ולנסות אותם במסוף עצמו:

11.2. ניטור

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

תַחַת מדדי יישום יש לנו בעיקר שתי קטגוריות של אלמנטים המנוטרים כברירת מחדל:

• לִבנוֹת תואם את המיידיות של רכיבי היישום
• HTTP תואם לבקשות HTTP המטופלות על ידי RESTX

11.3. סטטיסטיקה

RESTX מאפשר למשתמש לבחור לאסוף ולשתף נתונים סטטיסטיים אנונימיים על היישום כדי לתת מידע לקהילת RESTX. אנו יכולים לבטל הסכמה בקלות על ידי אי הכללה של restx-stats-admin מודול.

הנתונים הסטטיסטיים מדווחים על דברים כמו מערכת ההפעלה הבסיסית וגרסת ה- JVM:

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

מלבד אלה, מסוף הניהול יכול גם לעזור לנו:

• בדוק את יומני השרת (יומני)
• צפה בשגיאות שנתקלו בהן (שגיאות)
• לבדוק את משתני הסביבה (Config)

12. אישור

נקודות קצה של RESTX מאובטחות כברירת מחדל. זה אומר אם עבור נקודת קצה כלשהי:

@GET ("/ greetings / {who}") הודעה ציבורית sayHello (String who) {להחזיר הודעה חדשה (who); }

כאשר מתקשרים ללא אימות יחזיר א 401 כברירת מחדל.

כדי לפרסם נקודת קצה, עלינו להשתמש ב- @PermitAll ביאור ברמת השיטה או בכיתה:

@PermitAll @GET ("/ greetings / {who}") הודעה ציבורית sayHello (String who) {להחזיר הודעה חדשה (who); }

שים לב שברמת הכיתה, כל השיטות הן ציבוריות.

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

@ RollesAllowed ("admin") @GET ("/ greetings / {who}") הודעה ציבורית sayHello (String who) {להחזיר הודעה חדשה (who); }

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

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

אז מזהה המשתמש עם הסיסמה המוצפנת נשמר תחת /data/credentials.json קוֹבֶץ:

{"user1": "$ 2a $ 10 $ iZluUbCseDOvKnoe", "user2": "$ 2a $ 10 $ $ oym3Swr7pScdiCXu"}

וגם, תפקידי המשתמש מוגדרים ב /data/users.json קוֹבֶץ:

[{"name": "user1", "role": ["שלום"]}, {"name": "user2", "role": []}]

באפליקציה לדוגמה, הקבצים נטענים ב- AppModule דרך ה- FileBasedUserRepository מעמד:

FileBasedUserRepository חדש (StdUser.class, ממפה, StdUser חדש ("admin", ImmutableSet. of ("*")), Paths.get ("data / users.json"), Paths.get ("data / credentials.json" ), נכון)

ה StdUser מחלקה מחזיקה את אובייקטים המשתמש. זה יכול להיות מחלקת משתמשים מותאמת אישית, אבל צריך לסדר אותו ל- JSON.

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

13. מסקנה

הדרכה זו נתנה סקירה כללית על מסגרת ה- RESTX מבוססת Java הקלה.

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

אפליקציית ה- bootstrapped לדוגמא זמינה במאגר GitHub שלנו.