streamalism.org

1. Prehľad

V tomto výučbe sa pozrieme na ľahký rámec Java REST RESTX.

2. Funkcie

Vytvorenie rozhrania RESTful API je s rámcom RESTX celkom jednoduché. Má všetky predvolené hodnoty, ktoré môžeme od rámca REST očakávať, ako je poskytovanie a konzumácia JSON, parametre dotazu a cesty, mechanizmy smerovania a filtrovania, štatistika používania a monitorovanie.

RESTX tiež prichádza s intuitívnou administrátorskou webovou konzolou a inštalátorom príkazového riadku pre ľahké bootstrapovanie.

Je tiež licencovaný pod licenciou Apache License 2 a udržiavaný komunitou vývojárov. Minimálna požiadavka na Javu pre RESTX je JDK 7.

3. Konfigurácia

RESTX je dodávaný s praktickou aplikáciou shell / command, ktorá je užitočná na rýchle zavedenie Java projektu.

Najskôr si musíme nainštalovať aplikáciu, aby sme mohli pokračovať. Podrobný návod na inštaláciu je k dispozícii tu.

4. Inštalácia základných doplnkov

Teraz je čas nainštalovať základné doplnky, aby ste mohli vytvoriť aplikáciu zo samotného shellu.

V prostredí RESTX spustime nasledujúci príkaz:

nainštalovať shell

Potom nás vyzve, aby sme vybrali doplnky pre inštaláciu. Musíme zvoliť číslo, na ktoré ukazuje io.restx: restx-core-shell. Po dokončení inštalácie sa shell automaticky reštartuje.

5. Shell App Bootstrap

Pomocou shellu RESTX je veľmi pohodlné zaviesť novú aplikáciu. Poskytuje sprievodcu založeného na čarodejníkovi.

Začneme vykonaním nasledujúceho príkazu na shell:

aplikácia nová

Tento príkaz spustí sprievodcu. Potom môžeme ísť s predvolenými možnosťami alebo ich zmeniť podľa našich požiadaviek:

Keďže sme sa rozhodli generovať a pom.xml, projekt je možné ľahko importovať do ľubovoľného štandardného Java IDE.

V niekoľkých prípadoch bude možno potrebné upraviť nastavenia IDE.

Naším ďalším krokom bude vybudovanie projektu:

mvn clean install -DskipTests

Akonáhle je zostavenie úspešné, môžeme spustiť AppServer triedy ako Java aplikácia z IDE. Spustí sa to server s administračnou konzolou, ktorá bude počúvať na porte 8080.

Môžeme prechádzať do //127.0.0.1:8080/api/@/ui a zobraziť základné používateľské rozhranie.

Trasy začínajúce sa /@/ sa používajú pre administrátorskú konzolu, ktorá je rezervovanou cestou v RESTX.

Na prihlásenie do administrátorskej konzoly môžeme použiť predvolené užívateľské meno „admin“ a heslo, ktoré sme poskytli pri vytváraní aplikácie.

Predtým, ako sa pohráme s konzolou, preskúmajme kód a pochopme, čo sprievodca vygeneroval.

6. Zdroj RESTX

Trasy sú definované v <main_package> .rest.HelloResource trieda:

@Component @RestxResource verejná trieda HelloResource {@GET ("/ message") @RolesAllowed (Roles.HELLO_ROLE) verejná správa sayHello () {vrátiť novú správu (). SetMessage (String.format ("ahoj% s, je to% s") , RestxSession.current (). GetPrincipal (). Get (). GetName (), DateTime.now (). ToString ("HH: mm: ss"))); }}

Okamžite je zrejmé, že RESTX používa predvolené anotácie J2EE pre zabezpečenie a väzby REST. Väčšinou používa vlastné anotácie na vkladanie závislostí.

RESTX tiež podporuje mnoho rozumných predvolených hodnôt pre parametre metódy mapovania na požiadavku.

A okrem týchto štandardných anotácií je @RestxResource, ktorý ho deklaruje ako prostriedok, ktorý RESTX rozpoznáva.

Základná cesta je pridaná v src / main / webapp / WEB-INF / web.xml. V našom prípade to tak je / api, takže môžeme poslať požiadavku GET na adresu // localhost: 8080 / api / správa, za predpokladu správneho overenia totožnosti.

The Správa class je len Java bean, ktorý RESTX serializuje na JSON.

Prístup používateľa kontrolujeme zadaním Roly Povolené anotácia pomocou HELLO_ROLE ktorý vygeneroval bootstrapper.

7. Trieda modulu

Ako už bolo spomenuté, RESTX používa anotácie na vkladanie závislostí štandardu J2EE, ako @ Menovaný, a kde je to potrebné, vymyslí svoje vlastné, pravdepodobne si poradí z rámca Dagger pre @ Modul a @ Poskytuje.

Používa ich na vytvorenie hlavného modulu aplikácií, ktorý okrem iného definuje heslo správcu:

@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"; } @Provides public ConfigSupplier appConfigSupplier (ConfigLoader configLoader) {return configLoader.fromResource ("restx / demo / settings"); } // ďalšie metódy poskytovateľa na vytváranie komponentov}

@ Modul definuje triedu, ktorá môže definovať ďalšie komponenty, podobné ako @ Modul v Dagger, príp @ Konfigurácia na jar.

@ Poskytuje programovo vystavuje komponent, ako @ Poskytuje v Dagger, príp @Bean na jar.

A nakoniec @ Menovaný anotácia sa používa na označenie názvu vyrobeného komponentu.

AppModule tiež poskytuje a SignatureKey slúži na podpisovanie obsahu odosielaného klientom. Napríklad pri vytváraní relácie pre vzorovú aplikáciu sa nastaví súbor cookie podpísaný nakonfigurovaným kľúčom:

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

A ďalšie informácie nájdete v dokumentácii RESTX pre komponenty / továrne na vkladanie závislostí.

8. Trieda spúšťača

A nakoniec, AppServer trieda sa používa na spustenie aplikácie ako štandardnej aplikácie Java na zabudovanom serveri Jetty:

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) hodí Exception {int port = Integer.valueOf (Optional.fromNullable (System.getenv ("PORT")). alebo ("8080")); Server WebServer = nový 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 (); }}

Tu je dev režim sa používa počas fázy vývoja na povolenie funkcií, ako je automatické kompilácia, ktorá skracuje vývojovú spätnú väzbu.

Aplikáciu môžeme zabaliť ako vojna (webový archív) súbor, ktorý sa má nasadiť do samostatného webového kontajnera J2EE.

V nasledujúcej časti sa dozvieme, ako otestovať aplikáciu.

9. Testovanie integrácie pomocou špecifikácií

Jednou zo silných stránok systému RESTX je jeho koncept „špecifikácií“. Vzorka špec bude vyzerať takto:

title: mal by admin pozdraviť daný čas: - čas: 2013-08-28T01: 18: 00.822 + 02: 00 wts: - kedy: | ZÍSKAJTE? Kto = xavier potom: | {"message": "ahoj xavier, je 01:18:00"}

Test je napísaný v štruktúre Given-When-Then v súbore YAML, ktorá v zásade definuje, ako by malo API reagovať (potom) na konkrétnu žiadosť (kedy) vzhľadom na súčasný stav systému (daný).

The HelloResourceSpecTest trieda v src / test / zdroje spustí testy napísané vo vyššie uvedených špecifikáciách:

@RunWith (RestxSpecTestsRunner.class) @FindSpecsIn ("specs / hello") verejná trieda HelloResourceSpecTest {}

The RestxSpecTestsRunner class je vlastný bežec JUnit. Obsahuje vlastné pravidlá JUnit na:

• nastaviť vstavaný server
• pripraviť stav systému (podľa daný časť v špecifikácii)
• - vydať špecifikované žiadosti a -
• overte očakávané odpovede

The @FindSpecsIn anotácia ukazuje na cestu k súborom spec, proti ktorým by sa mali testy spustiť.

Táto špecifikácia pomáha písať integračné testy a poskytovať príklady v dokumentoch API. Špecifikácie sú tiež užitočné pri simulovaní požiadaviek HTTP a zaznamenávaní párov požiadavka / odpoveď.

10. Ručné testovanie

Môžeme tiež testovať manuálne cez HTTP. Najprv sa musíme prihlásiť a aby sme to mohli urobiť, je potrebné zahašovať heslo administrátora v konzole RESTX:

hash md5 

A potom to môžeme odovzdať / relácie koncový bod:

curl -b u1 -c u1 -X POST -H "Content-Type: application / json" -d '{"principal": {"name": "admin", "passwordHash": "1d528266b85cf052803a57288"}}' // localhost: 8080 / api / relácie

(Upozorňujeme, že používatelia systému Windows si musia najskôr stiahnuť zvlnenie.)

A teraz, ak reláciu použijeme ako súčasť našej / správa požiadavka:

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

Potom dostaneme niečo také:

{"message": "ahoj admin, je 09:56:51"}

11. Preskúmanie správcovskej konzoly

Správcovská konzola poskytuje užitočné zdroje na ovládanie aplikácie.

Poďme sa pozrieť na kľúčové funkcie prechodom na //127.0.0.1:8080/admin/@/ui.

11.1. Dokumenty API

V sekcii Dokumenty API sú uvedené všetky dostupné trasy vrátane všetkých možností:

A môžeme kliknúť na jednotlivé trasy a vyskúšať ich na samotnej konzole:

11.2. Monitorovanie

The Metriky JVM časť zobrazuje metriky aplikácie s aktívnymi reláciami, využitím pamäte a výpisom vlákien:

Pod Metriky aplikácie štandardne sledujeme hlavne dve kategórie prvkov:

• BUILD zodpovedá inštancii aplikačných komponentov
• HTTP zodpovedá požiadavkám HTTP vybaveným RESTX

11.3. Štatistiky

RESTX umožňuje používateľovi zvoliť si zhromažďovanie a zdieľanie anonymných štatistík aplikácie s cieľom poskytnúť informácie komunite RESTX. Môžeme sa jednoducho odhlásiť vylúčením restx-stats-admin modul.

Štatistiky obsahujú správy ako základný operačný systém a verzia JVM:

Pretože táto stránka zobrazuje citlivé informácie,nezabudnite skontrolovať jeho možnosti konfigurácie.

Okrem nich nám môže pomôcť aj správcovská konzola:

• skontrolovať protokoly servera (protokoly)
• zobraziť chyby, ktoré sa vyskytli (chyby)
• skontrolovať premenné prostredia (Config)

12. Povolenie

Koncové body RESTX sú predvolene zabezpečené. To znamená, že ak pre akýkoľvek koncový bod:

@GET ("/ greetings / {who}") public Správa sayHello (String who) {vrátiť novú správu (who); }

Pri volaní bez autentifikácie vráti a 401 predvolene.

Ak chcete koncový bod zverejniť, musíme použiť @PermitAll anotácia buď na úrovni metódy, alebo triedy:

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

Upozorňujeme, že na úrovni triedy sú všetky metódy verejné.

Rámec ďalej umožňuje špecifikovať užívateľské roly pomocou @RolesAllowed anotácia:

@RolesAllowed ("admin") @GET ("/ greetings / {who}") public Správa sayHello (String who) {vrátiť novú správu (who); }

Pomocou tejto anotácie RESTX overí, či má autentifikovaný užívateľ priradenú aj rolu správcu. V prípade, že sa autentifikovaný užívateľ bez rolí administrátora pokúsi získať prístup ku koncovému bodu, aplikácia vráti a 403 namiesto a 401.

Roly a poverenia používateľa sú predvolene uložené v súborovom systéme v samostatných súboroch.

Takže ID užívateľa so zašifrovaným heslom je uložené pod /data/credentials.json spis:

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

Roly používateľov sú definované v /data/users.json spis:

[{"name": "user1", "role": ["ahoj"]}, {"name": "user2", "role": []}]

V ukážkovej aplikácii sa súbory načítajú do súboru AppModule cez FileBasedUserRepository trieda:

new FileBasedUserRepository (StdUser.class, mapper, new StdUser ("admin", ImmutableSet. of ("*")), Paths.get ("data / users.json"), Paths.get ("data / credentials.json" ), pravda)

The StdUser trieda obsahuje objekty používateľa. Môže to byť vlastná trieda používateľov, ale musí byť serializovateľná do formátu JSON.

Môžeme samozrejme použiť inú UserRepository implementácia, napríklad taká, ktorá zasiahne databázu.

13. Záver

Tento tutoriál poskytol prehľad ľahkého rámca RESTX založeného na prostredí Java.

Rámec je stále vo vývoji a jeho použitie by mohlo mať nejaké drsné hrany. Ďalšie informácie nájdete v oficiálnej dokumentácii.

Vzorová bootstrapovaná aplikácia je k dispozícii v našom úložisku GitHub.