streamalism.org

1. Áttekintés

Ebben az oktatóanyagban bemutatjuk a könnyű Java REST RESTX keretrendszert.

2. Jellemzők

A RESTful API létrehozása meglehetősen egyszerű a RESTX keretrendszerrel. Minden olyan alapértelmezett értékkel rendelkezik, amelyet elvárhatunk egy REST keretrendszertől, például a JSON kiszolgálása és elfogyasztása, a lekérdezési és útvonal-paraméterek, az útválasztási és szűrési mechanizmusok, a használati statisztikák és a figyelés.

A RESTX egy intuitív rendszergazdai webkonzolt és parancssori telepítőt is tartalmaz a könnyű indításhoz.

Ezenkívül az Apache License 2 alatt licencelt és egy fejlesztői közösség fenntartja. A RESTX minimális Java-követelménye a JDK 7.

3. Konfiguráció

A RESTX egy praktikus shell / parancs alkalmazással rendelkezik, amely hasznos egy Java projekt gyors indításához.

A folytatáshoz először telepítenünk kell az alkalmazást. A részletes telepítési útmutató itt érhető el.

4. Az alapvető beépülő modulok telepítése

Itt az ideje, hogy telepítse az alapvető beépülő modulokat, hogy a héjból létrehozhasson egy alkalmazást.

Futtassuk a következő parancsot a RESTX héjban:

shell telepítése

Ezután felszólít minket a beépülő modulok kiválasztására a telepítéshez. Ki kell választanunk a számot, amelyre mutat io.restx: restx-core-shell. A telepítés befejezése után a shell automatikusan újraindul.

5. Shell App Bootstrap

A RESTX shell használatával nagyon kényelmes egy új alkalmazást indítani. Varázsló alapú útmutatót nyújt.

Kezdjük azzal, hogy a következő parancsot hajtjuk végre a shellen:

alkalmazás új

Ez a parancs elindítja a varázslót. Ezután választhatunk az alapértelmezett beállításokkal, vagy megváltoztathatjuk őket a követelményeinknek megfelelően:

Mivel úgy döntöttünk, hogy létrehozunk egy pom.xml, a projekt könnyen importálható bármilyen szabványos Java IDE-be.

Néhány esetben szükség lehet az IDE-beállítások módosítására.

A következő lépés a projekt megépítése lesz:

mvn clean install -DskipTests

Miután az összeállítás sikeres volt, futtathatjuk a AppServer osztály Java alkalmazásként az IDE-től. Ez elindítja a szervert az adminisztrációs konzollal, és hallgatja a 8080-as portot.

Böngészhetünk //127.0.0.1:8080/api/@/ui és nézze meg az alapvető felhasználói felületet.

A következővel kezdődő útvonalak: /@/ a rendszergazdai konzolhoz használják, amely a RESTX-ben lefoglalt útvonal.

Az adminisztrációs konzolba történő bejelentkezéshez használhatjuk az alapértelmezett „admin“ és az alkalmazás létrehozása során megadott jelszót.

Mielőtt a konzollal játszanánk, fedezzük fel a kódot, és értsük meg, mit generált a varázsló.

6. A RESTX erőforrás

Az útvonalakat a <main_package> .rest.HelloResource osztály:

@Component @RestxResource public class HelloResource {@GET ("/ message") @RolesAllowed (Roles.HELLO_ROLE) public Message sayHello () {return new Message (). SetMessage (String.format ("hello% s, ez% s") , RestxSession.current (). GetPrincipal (). Get (). GetName (), DateTime.now (). ToString ("HH: mm: ss"))); }}

Rögtön nyilvánvaló, hogy a RESTX az alapértelmezett J2EE kommentárokat használja a biztonsághoz és a REST összerendelésekhez. A függőség-injektáláshoz javarészt saját annotációit használja.

A RESTX sok ésszerű alapértelmezést is támogat a metódus paramétereinek leképezéséhez.

És ezen standard feljegyzések mellett @RestxResource, amely a RESTX által felismert erőforrásként deklarálja.

Az alapút hozzáadódik a src / main / webapp / WEB-INF / web.xml. Esetünkben az / api, így elküldhetünk egy GET kérést a következő címre: // localhost: 8080 / api / message, feltételezve a megfelelő hitelesítést.

A Üzenet class csak egy Java bab, amelyet a RESTX JSON-ba sorosít.

A felhasználói hozzáférést a Szerepek engedélyezve annotáció a HELLO_ROLE amelyet a bootstrapper generált.

7. A modul osztály

Amint azt korábban megjegyeztük, a RESTX a J2EE szabványú függőség-injektálási jelöléseket használja @Nevezett, és feltalálja a sajátját, ahol szükséges, valószínűleg a Dagger keretrendszerhez veszi a célt @ Modul és @ Biztosítja.

Ezekkel hozza létre az alkalmazások fő modulját, amely többek között meghatározza az adminisztrátor jelszavát:

@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") public String restxAdminPassword () {return "1234"; } @ Nyilvános ConfigSupplier alkalmazást biztosítConfigSupplier (ConfigLoader configLoader) {return configLoader.fromResource ("restx / demo / settings"); } // egyéb szolgáltatói módszerek az összetevők létrehozásához}

@ Modul meghatároz egy osztályt, amely meghatározhat más, a @ Modul a Tőrben, vagy @ Konfiguráció tavasszal.

@ Biztosítja programozottan tesz ki egy komponenst, mint a @ Biztosítja a Tőrben, vagy @Bab tavasszal.

És végül a @Nevezett annotációval jelzik a gyártott alkatrész nevét.

AppModule biztosítja a SignatureKey az ügyfeleknek küldött tartalom aláírására szolgál. A munkamenet létrehozása során a példaalkalmazáshoz például beállít egy cookie-t, amelyet a konfigurált kulccsal írnak alá:

HTTP / 1.1 200 OK ... Set-Cookie: RestxSessionSignature-restx-demo = "ySfv8FejvizMMvruGlK3K2hwdb8 ="; RestxSession-restx-demo = "..." ...

További információkért tekintse meg a RESTX alkatrészgyárának / függőségi befecskendezési dokumentációját.

8. A Launcher osztály

És végül: AppServer osztály az alkalmazás futtatására szokásos Java alkalmazásként egy beágyazott Jetty kiszolgálón:

public class AppServer {public static final String WEB_INF_LOCATION = "src / main / webapp / WEB-INF / web.xml"; public static final String WEB_APP_LOCATION = "src / main / webapp"; public static void main (String [] args) dobja a (z) {int port = Integer.valueOf (Opcionális.fromNullable (System.getenv ("PORT"))). vagy ("8080") kivételt; WebServer szerver = új Jetty8WebServer (WEB_INF_LOCATION, WEB_APP_LOCATION, port, "0.0.0.0"); System.setProperty ("restx.mode", System.getProperty ("restx.mode", "dev")); System.setProperty ("restx.app.package", "restx.demo"); server.startAndAwait (); }}

Itt a dev módot a fejlesztési szakaszban használják olyan funkciók engedélyezésére, mint az automatikus fordítás, amely lerövidíti a fejlesztési visszacsatolási ciklust.

Csomagolhatjuk az alkalmazást a-ként háború (webarchívum) fájl önálló J2EE webtárolóba telepítésre.

A következő szakaszban megtudhatjuk, hogyan kell tesztelni az alkalmazást.

9. Integráció tesztelése specifikációk segítségével

A RESTX egyik erős tulajdonsága a "specifikációk" fogalma. Egy minta spec így nézne ki:

cím: az adminnak köszönni kell: - időpont: 2013-08-28T01: 18: 00.822 + 02: 00 wts: - mikor: | Üdvözlet? Ki = xavier akkor: | {"message": "szia xavier, 01:18:00 van"}

A teszt egy YAML fájl adott-mikor-akkor struktúrájába van írva, amely alapvetően meghatározza, hogy az API hogyan válaszoljon (azután) külön kérésre (mikor) a rendszer aktuális állapotát figyelembe véve (adott).

A HelloResourceSpecTest osztályban src / test / resources elindítja a fenti specifikációkban írt teszteket:

@RunWith (RestxSpecTestsRunner.class) @FindSpecsIn ("specs / hello") public class HelloResourceSpecTest {}

A RestxSpecTestsRunner osztály egy egyedi JUnit futó. Egyedi JUnit-szabályokat tartalmaz:

• beágyazott szerver beállítása
• előkészíti a rendszer állapotát (a adott szakasz a specifikációkban)
• kiadja a megadott kéréseket, és
• ellenőrizze a várható válaszokat

A @FindSpecsIn az annotáció a specifikációs fájlok elérési útjára mutat, amelyek ellen a teszteket futtatni kell.

A specifikáció segít az integrációs tesztek megírásában, és példákat ad az API dokumentumokba. A specifikációk szintén hasznosak a HTTP kérések kigúnyolásához és a kérelem / válasz párok rögzítéséhez.

10. Manuális tesztelés

Manuálisan is tesztelhetünk HTTP-n keresztül. Először be kell jelentkeznünk, ehhez pedig kivonatoljuk az adminisztrátori jelszót a RESTX konzolban:

hash md5 

És akkor ezt átadhatjuk a / munkamenetek végpont:

curl -b u1 -c u1 -X POST -H "Tartalom-típus: alkalmazás / json" -d '{"fő": {"név": "admin", "passwordHash": "1d528266b85cf052803a57288"}}' // localhost: 8080 / api / session

(Ne feledje, hogy a Windows-felhasználóknak először le kell tölteniük a göndörítést.)

És most, ha a munkamenet részeként használjuk /üzenet kérés:

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

Akkor kapunk valami ilyesmit:

{"message": "szia admin, 09:56:51 van"}

11. A Felügyeleti Konzol felfedezése

Az adminisztrációs konzol hasznos forrásokat biztosít az alkalmazás vezérléséhez.

Vessünk egy pillantást a legfontosabb jellemzőkre a böngészéssel //127.0.0.1:8080/admin/@/ui.

11.1. API-dokumentumok

Az API dokumentumok szakasz felsorolja az összes elérhető útvonalat, beleértve az összes lehetőséget:

És kattinthatunk az egyes útvonalakra, és kipróbálhatjuk őket a konzolon:

11.2. Monitoring

A JVM Metrics szakasz mutatja az alkalmazás metrikáit az aktív munkamenetekkel, a memóriahasználattal és a szálak kiíratásával:

Alatt Alkalmazásmérők főleg két kategóriát elemezünk alapértelmezés szerint:

• ÉPÍT megfelel az alkalmazás komponenseinek példányosításának
• HTTP megfelel a RESTX által kezelt HTTP kéréseknek

11.3. Statisztika

A RESTX lehetővé teszi a felhasználó számára, hogy névtelen statisztikákat gyűjtsön és osszon meg az alkalmazásról, hogy információkat nyújtson a RESTX közösségnek. Könnyen leiratkozhatunk a restx-stats-admin modul.

A statisztikák olyan dolgokról számolnak be, mint az alapul szolgáló operációs rendszer és a JVM verzió:

Mivel ez az oldal érzékeny információkat mutat,ellenőrizze a konfigurációs lehetőségeket.

Ezeken kívül az adminisztrációs konzol is segítségünkre lehet:

• ellenőrizze a szerver naplóit (Naplók)
• a felmerült hibák megtekintése (hibák)
• ellenőrizze a környezeti változókat (Config)

12. Engedélyezés

A RESTX végpontok alapértelmezés szerint vannak biztonságban. Ez azt jelenti, hogy bármely végpont esetében:

@GET ("/ greetings / {who}") public Message sayHello (String who) {return new Message (who); }

Ha hitelesítés nélkül hívják, a 401 alapértelmezés szerint.

A végpont nyilvánosságra hozatalához a @PermitAll kommentár akár módszer, akár osztály szintjén:

@PermitAll @GET ("/ greetings / {who}") public Message sayHello (String who) {return new Message (who); }

Ne feledje, hogy osztályszinten minden módszer nyilvános.

Ezenkívül a keretrendszer lehetővé teszi a felhasználói szerepkörök megadását is a @RolesAllowed kommentár:

@RolesAllowed ("admin") @GET ("/ greetings / {who}") public Message sayHello (String who) {return new Message (who); }

Ezzel a feljegyzéssel a RESTX ellenőrzi, hogy a hitelesített felhasználó rendelkezik-e adminisztrátori szerepkörrel is. Abban az esetben, ha egy adminisztrátori szerepkörök nélküli hitelesített felhasználó megpróbálja elérni a végpontot, az alkalmazás a 403 a helyett 401.

Alapértelmezés szerint a felhasználói szerepkörök és a hitelesítő adatok a fájlrendszerben, külön fájlokban vannak tárolva.

Tehát a titkosított jelszóval rendelkező felhasználói azonosító a (z) alatt található /data/credentials.json fájl:

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

A felhasználói szerepkörök pedig a következőkben vannak meghatározva /data/users.json fájl:

[{"név": "felhasználó1", "szerepkörök": ["szia"]}, {"név": "felhasználó2", "szerepkörök": []}]

A minta alkalmazásban a fájlok betöltődnek a AppModule a FileBasedUserRepository osztály:

új FileBasedUserRepository (StdUser.class, leképező, új StdUser ("admin", ImmutableSet. ("*")), Paths.get ("data / users.json"), Paths.get ("data / credentials.json" ), igaz)

A StdUser osztály tartalmazza a felhasználói objektumokat. Lehet egyedi felhasználói osztály, de sorosíthatónak kell lennie a JSON-ban.

Természetesen használhatunk mást is UserRepository megvalósítás, mint például egy adatbázis elérése.

13. Következtetés

Ez az oktatóanyag áttekintést adott a könnyű Java-alapú RESTX keretrendszerről.

A keretrendszer még fejlesztés alatt áll, és előfordulhat, hogy néhány durva él használja. További részletekért tekintse meg a hivatalos dokumentációt.

A bootstrapped minta a GitHub-tárunkban érhető el.