streamalism.org

1. Pregled

U ovom uputstvu vodit ćemo obilazak laganog Java REST okvira RESTX.

2. Značajke

Izgradnja RESTful API-a vrlo je jednostavna s RESTX okvirom. Ima sve zadane vrijednosti koje možemo očekivati ​​od REST okvira poput posluživanja i konzumiranja JSON-a, parametara upita i puta, mehanizama usmjeravanja i filtriranja, statistike upotrebe i praćenja.

RESTX također dolazi s intuitivnom administratorskom web konzolom i programom za instalaciju naredbenog retka za jednostavno pokretanje sustava.

Također je licenciran pod Apache License 2, a održava ga zajednica programera. Minimalni Java zahtjev za RESTX je JDK 7.

3. Konfiguracija

RESTX dolazi s praktičnom aplikacijom ljuske / naredbe koja je korisna za brzo pokretanje Java projekta.

Prvo moramo instalirati aplikaciju prije nego što nastavimo. Detaljne upute za instalaciju dostupne su ovdje.

4. Instaliranje osnovnih dodataka

Sada je vrijeme da instalirate osnovne dodatke kako biste mogli stvoriti aplikaciju iz same ljuske.

U ljusci RESTX pokrenimo sljedeću naredbu:

instalirati ljusku

Tada će se zatražiti odabir dodataka za instalaciju. Moramo odabrati broj na koji upućuje io.restx: restx-core-shell. Ljuska će se automatski ponovo pokrenuti nakon dovršetka instalacije.

5. Shell App Bootstrap

Korištenjem ljuske RESTX vrlo je prikladno pokrenuti novu aplikaciju. Pruža vodič zasnovan na čarobnjaku.

Započinjemo izvršavanjem sljedeće naredbe na ljusci:

aplikacija nova

Ova će naredba pokrenuti čarobnjaka. Tada možemo ili izabrati zadane opcije ili ih promijeniti prema našim zahtjevima:

Budući da smo odlučili generirati pom.xml, projekt se može lako uvesti u bilo koji standardni Java IDE.

U nekoliko slučajeva možda ćemo trebati prilagoditi IDE postavke.

Naš sljedeći korak bit će izgradnja projekta:

mvn čista instalacija -DskipTests

Jednom kada je gradnja uspješna, možemo pokrenuti AppServer klasa kao Java aplikacija iz IDE-a. Ovo će pokrenuti poslužitelj s administratorskom konzolom, preslušavajući na portu 8080.

Možemo pregledavati //127.0.0.1:8080/api/@/ui i pogledajte osnovno korisničko sučelje.

Rute koje počinju sa /@/ koriste se za administratorsku konzolu koja je rezervirana staza u RESTX-u.

Za prijavu na administratorsku konzolu možemo koristiti zadano korisničko ime „admin“ i lozinku koju smo naveli prilikom izrade aplikacije.

Prije nego što se poigramo s konzolom, istražimo kod i shvatimo što je čarobnjak generirao.

6. RESTX resurs

Rute su definirane u <glavni_paket> .rest.HelloResource razred:

@Component @RestxResource javna klasa HelloResource {@GET ("/ message") @RolesAllowed (Roles.HELLO_ROLE) javna poruka sayHello () {return new Message (). SetMessage (String.format ("bok% s, to je% s" , RestxSession.current (). GetPrincipal (). Get (). GetName (), DateTime.now (). ToString ("HH: mm: ss")))); }}

Odmah je očito da RESTX koristi zadane J2EE bilješke za sigurnost i REST vezivanja. Uglavnom koristi vlastite bilješke za ubrizgavanje ovisnosti.

RESTX također podržava mnoge razumne zadane vrijednosti za mapiranje parametara metode u zahtjev.

I, uz ove standardne napomene je @RestxResource, koja ga proglašava resursom koji RESTX prepoznaje.

Osnovni put dodaje se u src / main / webapp / WEB-INF / web.xml. U našem slučaju jest / api, tako da možemo poslati GET zahtjev na // localhost: 8080 / api / message, pod pretpostavkom pravilne provjere autentičnosti.

The Poruka class je samo Java zrno koje se RESTX serializira u JSON.

Pristup korisnika kontroliramo određivanjem UlogeDopušteno napomena pomoću POZDRAV_ROLE koji je generirao bootstrapper.

7. Razred modula

Kao što je ranije spomenuto, RESTX koristi J2EE standardne napomene o ubrizgavanju ovisnosti, poput @Name, i izmišlja vlastiti gdje je potrebno, vjerojatno uzimajući nagovještaj iz Dagger okvira za @Modul i @Provides.

Koristi ih za stvaranje glavnog modula aplikacija, koji između ostalog definira administratorsku lozinku:

@Module javna klasa 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") javni niz restxAdminPassword () {return "1234"; } @Provides public ConfigSupplier appConfigSupplier (ConfigLoader configLoader) {return configLoader.fromResource ("restx / demo / settings"); } // druge metode davatelja za stvaranje komponenata}

@Modul definira klasu koja može definirati druge komponente, slično kao @Modul u Bodež, ili @Konfiguracija u proljeće.

@Provides izlaže komponentu programski, poput @Provides u Bodež, ili @Grah u proljeće.

I, konačno, @Name napomena se koristi za označavanje naziva proizvedene komponente.

AppModule također pruža a PotpisKljuč koristi se za potpisivanje sadržaja poslanog klijentima. Tijekom stvaranja sesije za primjer aplikacije, ovo će postaviti kolačić, potpisan konfiguriranim ključem:

HTTP / 1.1 200 OK ... Postavi kolačić: RestxSessionSignature-restx-demo = "ySfv8FejvizMMvruGlK3K2hwdb8 ="; RestxSession-restx-demo = "..." ...

I pogledajte RESTX-ovu tvornicu komponenata / dokumentaciju za ubrizgavanje ovisnosti za više informacija.

8. Razred za lansiranje

I na kraju, AppServer class koristi se za pokretanje aplikacije kao standardne Java aplikacije na ugrađenom Jetty poslužitelju:

javna klasa AppServer {javni statički završni niz WEB_INF_LOCATION = "src / main / webapp / WEB-INF / web.xml"; javni statički završni niz WEB_APP_LOCATION = "src / main / webapp"; javna statička void glavna (String [] args) baca izuzetak {int port = Integer.valueOf (Izborno.fromNullable (System.getenv ("PORT")). ili ("8080")); WebServer poslužitelj = novi Jetty8WebServer (WEB_INF_LOCATION, WEB_APP_LOCATION, priključak, "0.0.0.0"); System.setProperty ("restx.mode", System.getProperty ("restx.mode", "dev")); System.setProperty ("restx.app.package", "restx.demo"); server.startAndAwait (); }}

Evo, razv način rada koristi se tijekom razvojne faze kako bi se omogućile značajke poput automatskog sastavljanja što skraćuje petlju povratnih informacija o razvoju.

Aplikaciju možemo pakirati kao rat Datoteka (web arhiva) za postavljanje u samostalni J2EE web spremnik.

U sljedećem odjeljku saznajmo kako testirati aplikaciju.

9. Integracijsko testiranje pomoću specifikacija

Jedna od jakih karakteristika RESTX-a je njegov koncept "specifikacija". Primjerak spec bi izgledalo ovako:

naslov: treba admin pozdraviti dato: - vrijeme: 2013-08-28T01: 18: 00.822 + 02: 00 wts: - kada: | DOBITE zdravo? Who = xavier then: | {"message": "bok xavier, sad je 01:18:00"}

Test je napisan u strukturi Dato-kada-onda unutar YAML datoteke koja u osnovi definira kako API treba reagirati (zatim) na određeni zahtjev (kada) s obzirom na trenutno stanje sustava (dato).

The HelloResourceSpecTest razred u src / test / resources pokrenut će testove napisane u gornjim specifikacijama:

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

The RestxSpecTestsRunner class je prilagođeni JUnit pokretač. Sadrži prilagođena JUnit pravila za:

• postaviti ugrađeni poslužitelj
• pripremiti stanje sustava (prema dato odjeljak u specifikacijama)
• izdati navedene zahtjeve i
• provjeriti očekivane odgovore

The @FindSpecsIn napomena upućuje na put spec datoteka prema kojima bi trebalo pokrenuti testove.

Specifikacija pomaže u pisanju integracijskih testova i daje primjere u API dokumentima. Specifikacije su također korisne za ismijavanje HTTP zahtjeva i bilježenje parova zahtjeva / odgovora.

10. Ručno ispitivanje

Također možemo ručno testirati putem HTTP-a. Prvo se moramo prijaviti, a da bismo to učinili, moramo heširati administratorsku lozinku u RESTX konzoli:

hash md5 

A onda to možemo proslijediti / sjednice krajnja točka:

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

(Imajte na umu da korisnici sustava Windows prvo trebaju skinuti curl.)

A sada, ako koristimo sesiju kao dio našeg /poruka zahtjev:

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

Tada ćemo dobiti nešto poput ovoga:

{"message": "pozdrav admin, to je 09:56:51"}

11. Istraživanje administratorske konzole

Administratorska konzola nudi korisne resurse za upravljanje aplikacijom.

Pogledajmo ključne značajke pregledavanjem //127.0.0.1:8080/admin/@/ui.

11.1. API dokumenti

Odjeljak API dokumenata navodi sve dostupne rute, uključujući sve opcije:

A možemo kliknuti na pojedine rute i isprobati ih na samoj konzoli:

11.2. Praćenje

The JVM metrika odjeljak prikazuje mjerne podatke aplikacije s aktivnim sesijama, korištenjem memorije i dumpom niti:

Pod, ispod Metrika primjene imamo uglavnom dvije kategorije elemenata koji se prema zadanim postavkama nadgledaju:

• IZGRADITI odgovara instanciranju komponenata aplikacije
• HTTP odgovara HTTP zahtjevima kojima upravlja RESTX

11.3. Statistika

RESTX omogućuje korisniku odabir prikupljanja i dijeljenja anonimnih statističkih podataka o aplikaciji radi davanja informacija zajednici RESTX. Jednostavno se možemo isključiti isključivanjem restx-stats-admin modul.

Statistika izvještava o stvarima poput osnovnog OS-a i JVM verzije:

Budući da ova stranica prikazuje osjetljive podatke,svakako pregledajte njegove mogućnosti konfiguracije.

Osim ovih, administratorska konzola također nam može pomoći:

• provjeriti zapisnike poslužitelja (Dnevnici)
• pregledajte pogreške (Greške)
• provjeriti varijable okoline (Config)

12. Ovlaštenje

Krajnje točke RESTX osigurane su prema zadanim postavkama. To znači ako za bilo koju krajnju točku:

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

Kada se pozove bez provjere autentičnosti, vratit će se 401 prema zadanim postavkama.

Da bismo krajnju točku učinili javnim, moramo koristiti @ Dopusti sve napomena na razini metode ili klase:

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

Imajte na umu da su na razini razreda sve metode javne.

Nadalje, okvir također omogućuje specificiranje korisničkih uloga pomoću @RolesAllowed napomena:

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

Ovom bilješkom RESTX će provjeriti ima li ovjereni korisnik i dodijeljenu administratorsku ulogu. U slučaju da autentificirani korisnik bez administratorskih uloga pokuša pristupiti krajnjoj točki, aplikacija će vratiti a 403 umjesto a 401.

Prema zadanim postavkama, korisničke uloge i vjerodajnice pohranjuju se u datotečni sustav, u zasebne datoteke.

Dakle, korisnički ID s šifriranom lozinkom pohranjen je pod /data/credentials.json datoteka:

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

Korisničke uloge definirane su u /data/users.json datoteka:

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

U uzorku aplikacije datoteke se učitavaju u AppModule putem FileBasedUserRepository razred:

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

The StdUser klasa sadrži korisničke objekte. To može biti prilagođena korisnička klasa, ali mora biti serializirana u JSON.

Možemo, naravno, koristiti drugačije UserRepository implementacija, poput one koja pogađa bazu podataka.

13. Zaključak

Ovaj je vodič dao pregled laganog RESTX okvira temeljenog na Javi.

Okvir je još uvijek u fazi izrade i mogu se koristiti neki grubi rubovi. Više pojedinosti potražite u službenoj dokumentaciji.

Uzorak pokrenute aplikacije dostupan je u našem GitHub spremištu.