Introduktion til RESTX

1. Oversigt

I denne vejledning tager vi en rundvisning i den lette Java REST-ramme RESTX.

2. Funktioner

Opbygning af en RESTful API er ret let med RESTX-rammen. Det har alle de standardindstillinger, som vi kan forvente fra en REST-ramme som at betjene og forbruge JSON, forespørgsel og styparametre, routing- og filtreringsmekanismer, brugsstatistikker og overvågning.

RESTX leveres også med en intuitiv administratorwebkonsol og kommandolinjeanlæg til nem bootstrapping.

Det er også licenseret under Apache License 2 og vedligeholdt af et community af udviklere. Det mindste Java-krav til RESTX er JDK 7.

3. Konfiguration

RESTX leveres med en praktisk shell / kommando-app, som er nyttig til hurtig bootstrap af et Java-projekt.

Vi skal først installere appen, før vi kan fortsætte. Den detaljerede installationsvejledning er tilgængelig her.

4. Installation af Core Plugins

Nu er det tid til at installere kerne-plugins for at kunne oprette en app fra selve skallen.

Lad os køre følgende kommando i RESTX-skalen:

skal installere

Det vil derefter bede os om at vælge plugins til installation. Vi skal vælge det nummer, der peger på io.restx: restx-core-shell. Skallen genstarter automatisk, når installationen er afsluttet.

5. Shell App Bootstrap

Ved hjælp af RESTX-skallen er det meget praktisk at starte en ny app. Det giver en guide-baseret guide.

Vi starter med at udføre følgende kommando på skallen:

app ny

Denne kommando udløser guiden. Derefter kan vi enten gå med standardindstillingerne eller ændre dem i henhold til vores krav:

Da vi har valgt at generere en pom.xml, projektet kan let importeres til enhver standard Java IDE.

I nogle få tilfælde kan det være nødvendigt at tilpasse IDE-indstillingerne.

Vores næste skridt vil være at opbygge projektet:

mvn ren installation -DskipTests

Når build er vellykket, kan vi køre AppServer klasse som et Java-program fra IDE. Dette starter serveren med administrationskonsollen og lytter på port 8080.

Vi kan søge på //127.0.0.1:8080/api/@/ui og se den grundlæggende brugergrænseflade.

Ruterne starter med /@/ bruges til administrationskonsollen, som er en reserveret sti i RESTX.

For at logge ind på admin konsollen kan vi bruge standard brugernavnet “admin og den adgangskode, vi har angivet under oprettelsen af ​​appen.

Før vi leger med konsollen, lad os udforske koden og forstå, hvad guiden genererede.

6. En RESTX-ressource

Ruterne er defineret i <main_package> .rest.HelloResource klasse:

@Komponent @RestxResource offentlig klasse HelloResource {@GET ("/ meddelelse") @RolesAllowed (Roles.HELLO_ROLE) offentlig besked sayHello () {returner ny besked (). SetMessage (String.format ("hej% s, det er% s") , RestxSession.current (). GetPrincipal (). Get (). GetName (), DateTime.now (). ToString ("HH: mm: ss"))); }}

Det er umiddelbart tydeligt, at RESTX bruger standard J2EE-annoteringer til sikkerhed og REST-bindinger. For det meste bruger den sine egne kommentarer til afhængighedsinjektion.

RESTX understøtter også mange rimelige standarder for tilknytning af metodeparametre til anmodningen.

Og ud over disse standardkommentarer er @RestxResource, der erklærer det som en ressource, som RESTX genkender.

Basisstien tilføjes i src / main / webapp / WEB-INF / web.xml. I vores tilfælde er det / api, så vi kan sende en GET-anmodning til // localhost: 8080 / api / meddelelse, forudsat korrekt godkendelse.

Det Besked klasse er bare en Java-bønne, som RESTX serielt til JSON.

Vi kontrollerer brugeradgangen ved at specificere Roller Tilladt kommentar ved hjælp af HELLO_ROLE som blev genereret af bootstrapper.

7. Modulklassen

Som nævnt tidligere bruger RESTX J2EE-standardafhængighedsinjektionsnoteringer, som f.eks @Som hedder, og opfinder sin egen, hvor det er nødvendigt, sandsynligvis tager et signal fra Dagger-rammen for @Module og @Provides.

Det bruger disse til at oprette applikationshovedmodulet, som blandt andet definerer administratoradgangskoden:

@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") offentlig String restxAdminPassword () {return "1234"; } @Provides public ConfigSupplier appConfigSupplier (ConfigLoader configLoader) {return configLoader.fromResource ("restx / demo / settings"); } // andre udbydermetoder til at oprette komponenter}

@Module definerer en klasse, der kan definere andre komponenter, der ligner @Module i Dagger, eller @Konfiguration om foråret.

@Provides udsætter en komponent programmatisk, ligesom @Provides i Dagger, eller @Bønne om foråret.

Og endelig @Som hedder annotering bruges til at angive navnet på den producerede komponent.

AppModule giver også en Signaturnøgle bruges til at underskrive indhold sendt til klienterne. Under oprettelse af sessionen til eksempelappen, indstiller dette f.eks. En cookie, signeret med den konfigurerede nøgle:

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

Og tjek RESTX's fabriksdele / afhængighedsinjektionsdokumentation for mere.

8. Launcher-klassen

Og endelig, den AppServer klasse bruges til at køre applikationen som en standard Java-app i en integreret Jetty-server:

public class AppServer {public static final String WEB_INF_LOCATION = "src / main / webapp / WEB-INF / web.xml"; offentlig statisk endelig String WEB_APP_LOCATION = "src / main / webapp"; offentlig statisk ugyldig hoved (String [] args) kaster Undtagelse {int port = Integer.valueOf (Optional.fromNullable (System.getenv ("PORT")) eller ("8080")); WebServer-server = ny 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 (); }}

Her, den dev tilstand bruges under udviklingsfasen for at aktivere funktioner såsom automatisk kompilering, der forkorter udviklingsfeedback-sløjfen.

Vi kan pakke appen som en krig (webarkiv) fil til implementering i en uafhængig J2EE webcontainer.

Lad os finde ud af, hvordan du tester appen i det næste afsnit.

9. Integrationstest ved hjælp af specifikationer

Et af de stærke træk ved RESTX er konceptet "specs". En prøve spec ville se sådan ud:

titel: skal administrator sige hej givet: - tid: 2013-08-28T01: 18: 00.822 + 02: 00 wts: - hvornår: | HENT hej? Hvem = xavier så: | {"message": "hej xavier, det er 01:18:00"}

Testen er skrevet i en given-når-derefter-struktur inden for en YAML-fil, der grundlæggende definerer, hvordan API'en skal reagere (derefter) til en bestemt anmodning (hvornår) givet systemets aktuelle tilstand (givet).

Det HelloResourceSpecTest klasse i src / test / ressourcer vil udløse testene, der er skrevet i ovenstående specifikationer:

@RunWith (RestxSpecTestsRunner.class) @FindSpecsIn ("specs / hej") offentlig klasse HelloResourceSpecTest {}

Det RestxSpecTestsRunner klasse er en brugerdefineret JUnit-løber. Den indeholder tilpassede JUnit-regler til:

  • opsætte en integreret server
  • forberede systemets tilstand (i henhold til givet afsnit i specifikationerne)
  • udstede de angivne anmodninger, og
  • kontrollere de forventede svar

Det @FindSpecsIn annotation peger på stien til de spec-filer, som testene skal køres mod.

Specifikationen hjælper med at skrive integrationstests og give eksempler i API-dokumenterne. Specifikationer er også nyttige til at spotte HTTP-anmodninger og registrere anmodning / svarpar.

10. Manuel test

Vi kan også teste manuelt via HTTP. Vi skal først logge ind, og for at gøre dette skal vi hash administratoradgangskoden i RESTX-konsollen:

hash md5 

Og så kan vi videregive det til / sessioner slutpunkt:

krølle -b u1 -c u1 -X POST -H "Content-Type: application / json" -d '{"principal": {"name": "admin", "passwordHash": "1d528266b85cf052803a57288"}}' // localhost: 8080 / api / sessioner

(Bemærk, at Windows-brugere først skal downloade krøller.)

Og nu, hvis vi bruger sessionen som en del af vores /besked anmodning:

krølle -b u1 "// localhost: 8080 / api / meddelelse? hvem = restx"

Så får vi noget som dette:

{"message": "hej admin, det er 09:56:51"}

11. Udforskning af administrationskonsollen

Administratorkonsollen giver nyttige ressourcer til at kontrollere appen.

Lad os se på de vigtigste funktioner ved at bladre til //127.0.0.1:8080/admin/@/ui.

11.1. API-dokumenter

Afsnittet API docs viser alle tilgængelige ruter inklusive alle muligheder:

Og vi kan klikke på individuelle ruter og prøve dem på selve konsollen:

11.2. Overvågning

Det JVM-metrics sektion viser applikationsmålinger med aktive sessioner, hukommelsesforbrug og tråddump:

Under Applikationsmålinger vi har hovedsagelig to kategorier af elementer, der overvåges som standard:

  • BYG svarer til instantiering af applikationskomponenterne
  • HTTP svarer til HTTP-anmodninger håndteret af RESTX

11.3. Statistik

Med RESTX kan brugeren vælge at indsamle og dele anonym statistik på applikationen for at give information til RESTX-samfundet. Vi kan nemt fravælge ved at ekskludere restx-stats-admin modul.

Statistikken rapporterer ting som det underliggende operativsystem og JVM-versionen:

Fordi denne side viser følsomme oplysninger,Sørg for at gennemgå dens konfigurationsmuligheder.

Bortset fra disse kan administrationskonsollen også hjælpe os:

  • tjek serverlogfiler (logfiler)
  • se de stødte fejl (fejl)
  • kontrollere miljøvariablerne (Config)

12. Autorisation

RESTX-slutpunkter er sikret som standard. Det betyder, hvis for et hvilket som helst slutpunkt:

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

Når der ringes op uden godkendelse, returneres en 401 som standard.

For at gøre et slutpunkt offentligt skal vi bruge @PermitAll kommentar enten på metode- eller klasseniveau:

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

Bemærk, at på klasseniveau er alle metoder offentlige.

Desuden tillader rammen også at specificere brugerroller ved hjælp af @RolesAllowed kommentar:

@RolesAllowed ("admin") @GET ("/ greetings / {who}") offentlig Besked sayHello (String who) {returner ny besked (hvem); }

Med denne kommentar vil RESTX kontrollere, om den godkendte bruger også har en administratorrolle. Hvis en godkendt bruger uden administratorroller forsøger at få adgang til slutpunktet, returnerer applikationen en 403 i stedet for en 401.

Som standard gemmes brugerroller og legitimationsoplysninger på filsystemet i separate filer.

Så bruger-id'et med den krypterede adgangskode er gemt under /data/credentials.json fil:

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

Og brugerrollerne er defineret i /data/users.json fil:

[{"navn": "bruger1", "roller": ["hej"]}, {"navn": "bruger2", "roller": []}]

I prøve-appen indlæses filerne i AppModule via FileBasedUserRepository klasse:

nyt FileBasedUserRepository (StdUser.class, mapper, ny StdUser ("admin", ImmutableSet. af ("*")), Paths.get ("data / users.json"), Paths.get ("data / credentials.json" ), rigtigt)

Det StdUser klasse holder brugerobjekterne. Det kan være en brugerdefineret brugerklasse, men den skal serieres i JSON.

Vi kan selvfølgelig bruge en anden UserRepository implementering, som en, der rammer en database.

13. Konklusion

Denne vejledning gav et overblik over den lette Java-baserede RESTX-ramme.

Rammen er stadig under udvikling, og der kan være nogle ru kanter, der bruger den. Se den officielle dokumentation for flere detaljer.

Eksemplet på bootstrapped-appen er tilgængelig i vores GitHub-lager.


$config[zx-auto] not found$config[zx-overlay] not found