streamalism.org

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2:

1. Pregled

Ovaj članak objašnjava postupak stvaranja REST web usluge vođene hipermedijom pomoću proljetnog projekta HATEOAS.

2. Proljeće-HATEOAS

Proljetni projekt HATEOAS biblioteka je API-ja koje možemo koristiti za jednostavno stvaranje REST reprezentacija koje slijede princip HATEOAS-a (Hipertekst kao pokretač stanja aplikacije).

Općenito govoreći, princip podrazumijeva da API treba voditi klijenta kroz aplikaciju vraćajući relevantne informacije o sljedećim potencijalnim koracima, zajedno sa svakim odgovorom.

U ovom ćemo članku izraditi primjer pomoću Spring HATEOAS-a s ciljem razdvajanja klijenta i poslužitelja i teoretski omogućiti API-ju da promijeni svoju URI shemu bez razbijanja klijenata.

3. Priprema

Prvo, dodajmo proljetnu ovisnost HATEOAS:

 org.springframework.boot spring-boot-starter-hateoas 2.1.4.OSLOBODI 

Ako ne koristimo Spring Boot, našem projektu možemo dodati sljedeće knjižnice:

 org.springframework.hateoas spring-hateoas 0.25.1.RELEASE org.springframework.plugin spring-plugin-core 1.2.0.RELEASE 

Kao i uvijek, u Maven Central možemo pretraživati ​​najnovije verzije početnih HATEOAS-a, spring-hateoas i spring-plugin-core zavisnosti.

Dalje, imamo Kupac resurs bez proljetne podrške HATEOAS:

kupac javne klase {private String customerId; privatni niz customerName; private String companyName; // standardni geteri i postavljači} 

A mi imamo klasu kontrolera bez podrške za Spring HATEOAS:

@RestController @RequestMapping (value = "/ customers") javna klasa CustomerController {@Autowired private CustomerService customerService; @GetMapping ("/ {customerId}") javni kupac getCustomerById (@PathVariable String customerId) {return customerService.getCustomerDetail (customerId); }} 

Napokon, Kupac predstavljanje resursa:

{"customerId": "10A", "customerName": "Jane", "customerCompany": "ABC Company"} 

4. Dodavanje HATEOAS podrške

U proljetnom HATEOAS projektu ne trebamo niti tražiti kontekst Servleta, niti spajati varijablu staze s osnovnim URI-jem.

Umjesto toga, Proljetni HATEOAS nudi tri apstrakcije za stvaranje URI-ja - ReprezentacijaModel, Link i WebMvcLinkBuilder. Pomoću njih možemo stvoriti metapodatke i povezati ih s prikazom resursa.

4.1. Dodavanje hipermedijske podrške resursu

Projekt pruža osnovnu klasu tzv ReprezentacijaModel za nasljeđivanje pri stvaranju predstavljanja resursa:

javna klasa Kupac proširuje predstavništvoModel {private String customerId; privatni niz customerName; private String companyName; // standardni geteri i postavljači} 

The Kupac resurs se proteže od ReprezentacijaModel razred za nasljeđivanje dodati() metoda. Dakle, kad stvorimo vezu, tu vrijednost možemo lako postaviti na prikaz resursa bez dodavanja novih polja.

4.2. Stvaranje poveznica

Proljetni HATEOAS pruža a Veza objekt za pohranu metapodataka (mjesto ili URI resursa).

Prvo ćemo stvoriti jednostavnu vezu ručno:

Link veze = novi Link ("// localhost: 8080 / spring-security-rest / api / customers / 10A"); 

The Veza objekt slijedi Atom sintaksa veze i sastoji se od a rel koji identificira odnos prema resursu i href atribut koji je sama stvarna veza.

Evo kako Kupac Resurs izgleda sada kad sadrži novu vezu:

{"customerId": "10A", "customerName": "Jane", "customerCompany": "ABC Company", "_links": {"self": {"href": "// localhost: 8080 / spring-security -rest / api / kupci / 10A "}}} 

URI povezan s odgovorom kvalificiran je kao sebe veza. Semantika sebe Veza je jasna - to je jednostavno kanonsko mjesto na kojem se može pristupiti resursu.

4.3. Stvaranje boljih veza

Još jedna vrlo važna apstrakcija koju nudi knjižnica je the WebMvcLinkBuilder - što pojednostavljuje izgradnju URI-ja izbjegavanjem teško kodiranih veza.

Sljedeći isječak prikazuje izgradnju korisničke samoveze pomoću WebMvcLinkBuilder razred:

linkTo (CustomerController.class) .slash (customer.getCustomerId ()). withSelfRel (); 

Pogledajmo:

• the poveznica za() metoda pregledava klasu kontrolera i dobiva njezino mapiranje korijena
• the kosa crta () metoda dodaje id kupca vrijednost kao varijabla puta veze
• konačno, withSelfMethod () kvalificira odnos kao samopoveznicu

5. Odnosi

U prethodnom smo odjeljku prikazali odnos samokontrole. Međutim, složeniji sustavi mogu uključivati ​​i druge odnose.

Na primjer, a kupac može imati odnos s narudžbama. Modelirajmo Narudžba klasa kao resurs:

narudžba javne klase proširuje ReprezentacijaModel {private String orderId; privatna dvostruka cijena; privatna int količina; // standardni geteri i postavljači} 

U ovom trenutku možemo proširiti CustomerController s metodom koja vraća sve narudžbe određenog kupca:

@GetMapping (value = "/ {customerId} / orders", produce = {"application / hal + json"}) public CollectionModel getOrdersForCustomer (@PathVariable final String customerId) {List orders = orderService.getAllOrdersForCustomer (customerId); za (konačna narudžba narudžbe: narudžbe) {Link selfLink = linkTo (methodOn (CustomerController.class) .getOrderById (customerId, order.getOrderId ())). withSelfRel (); order.add (selfLink); } Link link = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithSelfRel (); Rezultat CollectionModel = novi CollectionModel (narudžbe, veza); povratni rezultat; } 

Naša metoda vraća a CollectionModel objekt koji mora biti u skladu s HAL povratnim tipom, kao i „_sam " veza za svaku narudžbu i puni popis.

Ovdje je važno primijetiti da hiperveza za narudžbe kupaca ovisi o mapiranju getOrdersForCustomer () metoda. Nazivat ćemo ove vrste veza kao poveznice metoda i pokazati kako WebMvcLinkBuilder mogu pomoći u njihovom stvaranju.

6. Veze do metoda kontrolera

The WebMvcLinkBuilder nudi bogatu podršku za proljetne MVC kontrolere. Sljedeći primjer pokazuje kako graditi hiperveze HATEOAS na temelju getOrdersForCustomer () metoda CustomerController razred:

Veza nalogaLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithRel ("allOrders"); 

The methodOn () dobiva mapiranje metode izvođenjem lažnog poziva ciljne metode na proxy kontroleru i postavlja id kupca kao varijabla puta URI-ja.

7. Proljetni HATEOAS u akciji

Stavimo samo-vezu i stvaranje veze metode zajedno u getAllCustomers () metoda:

@GetMapping (proizvodi = {"application / hal + json"}) javni CollectionModel getAllCustomers () {Popis svihCustomers = customerService.allCustomers (); za (Kupac kupac: allCustomers) {String customerId = customer.getCustomerId (); Veza selfLink = linkTo (CustomerController.class) .slash (customerId) .withSelfRel (); kupac.add (selfLink); if (orderService.getAllOrdersForCustomer (customerId) .size ()> 0) {Link ordersLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). withRel ("allOrders"); customer.add (ordersLink); }} Link link = linkTo (CustomerController.class) .withSelfRel (); Rezultat CollectionModel = novi CollectionModel (sviCustomers, veza); povratni rezultat; }

Dalje, pozovimo se na getAllCustomers () metoda:

curl // localhost: 8080 / spring-security-rest / api / kupci 

I ispitajte rezultat:

{"_embedded": {"customerList": [{"customerId": "10A", "customerName": "Jane", "companyName": "ABC Company", "_links": {"self": {"href" : "// localhost: 8080 / spring-security-rest / api / customers / 10A"}, "allOrders": {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / narudžbe "}}}, {" customerId ":" 20B "," customerName ":" Bob "," companyName ":" XYZ Company "," _links ": {" self ": {" href ":" // localhost : 8080 / spring-security-rest / api / customers / 20B "}," allOrders ": {" href ":" // localhost: 8080 / spring-security-rest / api / customers / 20B / orders "}}} , {"customerId": "30C", "customerName": "Tim", "companyName": "CKV Company", "_links": {"self": {"href": "// localhost: 8080 / spring- security-rest / api / customers / 30C "}}}]}," _links ": {" self ": {" href ":" // localhost: 8080 / spring-security-rest / api / kupci "}}}

Unutar svakog predstavljanja resursa nalazi se sebe vezu i sveNaruči veza za izdvajanje svih narudžbi kupca. Ako kupac nema narudžbe, veza za narudžbe se neće pojaviti.

Ovaj primjer pokazuje kako Spring HATEOAS potiče otkrivanje API-ja u web usluzi za odmor. Ako veza postoji, klijent je može slijediti i dobiti sve narudžbe za kupca:

curl // localhost: 8080 / spring-security-rest / api / kupci / 10A / narudžbe 

{"_embedded": {"orderList": [{"orderId": "001A", "price": 150, "quantity": 25, "_links": {"self": {"href": "// localhost : 8080 / spring-security-rest / api / customers / 10A / 001A "}}}, {" orderId ":" 002A "," price ": 250," quantity ": 15," _links ": {" self " : {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / 002A"}}}]}}, "_links": {"self": {"href": "// localhost: 8080 / spring-security-rest / api / kupci / 10A / narudžbe "}}}

8. Zaključak

U ovom uputstvu razgovarali smo o tome kako izgraditi hipermedijski pokretani Spring REST web servis pomoću projekta Spring HATEOAS.

U primjeru vidimo da klijent može imati jednu ulaznu točku u aplikaciju i daljnje radnje mogu se poduzeti na temelju metapodataka u predstavljanju odgovora.

To omogućuje poslužitelju da promijeni svoju URI shemu bez razbijanja klijenta. Također, aplikacija može oglašavati nove mogućnosti stavljanjem novih veza ili URI-ja u predstavljanje.

Napokon, potpunu provedbu ovog članka možete pronaći u projektu GitHub.

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2: