streamalism.org

ODPOČINOK Najlepšie

Práve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:

>> SKONTROLUJTE KURZ

1. Prehľad

Tento článok vysvetľuje proces vytvárania hypermediálnej webovej služby REST pomocou projektu Spring HATEOAS.

2. Jar-HATEOAS

Projekt Spring HATEOAS je knižnica API, pomocou ktorej môžeme ľahko vytvárať reprezentácie REST, ktoré sa riadia princípom HATEOAS (Hypertext ako motor stavu aplikácie).

Zásada vo všeobecnosti znamená, že API by malo klienta sprevádzať aplikáciou a spolu s každou odpoveďou vrátiť príslušné informácie o ďalších potenciálnych krokoch.

V tomto článku si vytvoríme príklad pomocou Spring HATEOAS s cieľom oddelenia klienta a servera a teoreticky umožniť API zmeniť svoju schému URI bez toho, aby došlo k narušeniu klientov.

3. Príprava

Najskôr pridajme závislosť Spring HATEOAS:

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

Ak nepoužívame Spring Boot, môžeme do nášho projektu pridať nasledujúce knižnice:

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

Ako vždy, v Maven Central môžeme vyhľadávať najnovšie verzie štartovacieho HATEOAS, závislostí spring-hateoas a spring-plugin-core.

Ďalej tu máme Zákazník zdroj bez podpory Spring HATEOAS:

public class Customer {private String customerId; private String customerName; private String companyName; // štandardné getre a setre} 

A máme triedu ovládačov bez podpory Spring HATEOAS:

@RestController @RequestMapping (value = "/ customers") verejná trieda CustomerController {@Autowired private CustomerService customerService; @GetMapping ("/ {customerId}") public Customer getCustomerById (@PathVariable String customerId) {return customerService.getCustomerDetail (customerId); }} 

Nakoniec Zákazník zastúpenie zdrojov:

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

4. Pridanie podpory HATEOAS

V projekte Spring HATEOAS nemusíme vyhľadávať kontext servletu ani spájať premennú cesty so základným identifikátorom URI.

Namiesto toho Jarná HATEOAS ponúka tri abstrakcie na vytvorenie URI - RepresentationModel, Link a WebMvcLinkBuilder. Tieto môžeme použiť na vytvorenie metadát a ich priradenie k reprezentácii zdrojov.

4.1. Pridanie podpory Hypermedia k prostriedku

Projekt poskytuje základnú triedu s názvom Model zastúpenia dediť z pri vytváraní zdrojovej reprezentácie:

public class Customer extends RepresentationModel {private String customerId; private String customerName; private String companyName; // štandardné getre a setre} 

The Zákazník zdroj siaha od Model zastúpenia triedy zdediť pridať () metóda. Takže akonáhle vytvoríme odkaz, môžeme ľahko nastaviť túto hodnotu na reprezentáciu zdrojov bez toho, aby sme k nej pridali nejaké nové polia.

4.2. Vytváranie odkazov

Jarná HATEOAS poskytuje a Odkaz objekt na uloženie metaúdajov (umiestnenie alebo URI prostriedku).

Najprv si ručne vytvoríme jednoduchý odkaz:

Odkaz odkaz = nový odkaz ("// localhost: 8080 / spring-security-rest / api / customers / 10A"); 

The Odkaz objekt sleduje Atom syntax odkazu a pozostáva z a rel ktorý identifikuje vzťah k zdroju a href atribút, ktorým je samotný odkaz.

Tu je postup, ako Zákazník zdroj teraz vyzerá, že obsahuje nový odkaz:

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

Identifikátor URI spojený s odpoveďou je kvalifikovaný ako ja odkaz. Sémantika ja vzťah je jasný - je to jednoducho kanonické umiestnenie, na ktorom je zdroj prístupný.

4.3. Vytváranie lepších odkazov

Ďalšou veľmi dôležitou abstrakciou, ktorú ponúka knižnica, je the WebMvcLinkBuilder - čo zjednodušuje vytváranie URI vyhýbaním sa pevne zakódovaným odkazom.

Nasledujúci úryvok ukazuje vytváranie prepojenia zákazníka pomocou WebMvcLinkBuilder trieda:

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

Pozrime sa na to:

• the odkaz na() metóda kontroluje triedu radiča a získava jej koreňové mapovanie
• the lomítko () metóda pridáva customerId hodnota ako premenná cesty odkazu
• nakoniec withSelfMethod () kvalifikuje vzťah ako prepojenie na seba

5. Vzťahy

V predchádzajúcej časti sme si ukázali vzájomný odkaz. Zložitejšie systémy však môžu zahŕňať aj ďalšie vzťahy.

Napríklad a zákazník môže mať vzťah s objednávkami. Poďme modelovať objednať trieda ako zdroj tiež:

public class Order extends RepresentationModel {private String orderId; dvojitá súkromná cena; súkromné ​​množstvo; // štandardné getre a setre} 

V tomto okamihu môžeme rozšíriť CustomerController metódou, ktorá vracia všetky objednávky konkrétneho zákazníka:

@GetMapping (value = "/ {customerId} / orders", produce = {"application / hal + json"}) public CollectionModel getOrdersForCustomer (@PathVariable final String customerId) {List commands = orderService.getAllOrdersForCustomer (customerId); pre (konečná objednávka objednávky: objednávky) {Link selfLink = linkTo (methodOn (CustomerController.class) .getOrderById (customerId, order.getOrderId ())). withSelfRel (); order.add (selfLink); } Odkaz link = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithSelfRel (); Výsledok CollectionModel = nový CollectionModel (objednávky, odkaz); návratový výsledok; } 

Naša metóda vracia a KolekciaModel namietať proti dodržaniu návratového typu HAL, ako aj „_self ” odkaz na každú z objednávok a úplný zoznam.

Je dôležité si tu všimnúť, že hypertextový odkaz na objednávky zákazníka závisí od jeho mapovania getOrdersForCustomer () metóda. Tieto typy odkazov budeme označovať ako odkazy na metódy a ukážeme si, ako WebMvcLinkBuilder môžu pomôcť pri ich vytváraní.

6. Odkazy na metódy ovládača

The WebMvcLinkBuilder ponúka bohatú podporu pre Spring MVC Controllers. Nasledujúci príklad ukazuje, ako vytvoriť hypertextové odkazy HATEOAS na základe getOrdersForCustomer () metóda CustomerController trieda:

Prepojiť orderLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithRel ("allOrders"); 

The methodOn () získa mapovanie metódy vykonaním fiktívneho vyvolania cieľovej metódy na zástupcovi proxy a nastaví customerId ako premenná cesty URI.

7. Jarná HATEOAS v akcii

Poďme spolu vytvoriť prepojenie na vlastné prepojenie a na vytvorenie metódy getAllCustomers () metóda:

@GetMapping (produce = {"application / hal + json"}) public CollectionModel getAllCustomers () {List allCustomers = customerService.allCustomers (); pre (Zákaznícky zákazník: allCustomers) {String customerId = customer.getCustomerId (); Link selfLink = linkTo (CustomerController.class) .slash (customerId) .withSelfRel (); customer.add (selfLink); if (orderService.getAllOrdersForCustomer (customerId) .size ()> 0) {Link commandsLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). withRel ("allOrders"); customer.add (ordersLink); }} Link link = linkTo (CustomerController.class) .withSelfRel (); Výsledok CollectionModel = nový CollectionModel (allCustomers, link); návratový výsledok; }

Ďalej vyvoláme getAllCustomers () metóda:

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

A preskúmajte výsledok:

{"_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 / objednávky "}}}, {" customerId ":" 20B "," customerName ":" Bob "," companyName ":" spoločnosť XYZ "," _links ": {" self ": {" href ":" // localhost : 8080 / spring-security-rest / api / customers / 20B "}," allOrders ": {" href ":" // localhost: 8080 / spring-security-rest / api / customers / 20B / objednávky "}}} , {"customerId": "30C", "customerName": "Tim", "companyName": "Spoločnosť CKV", "_links": {"self": {"href": "// localhost: 8080 / spring- security-rest / api / customers / 30C "}}}]}}," _links ": {" self ": {" href ":" // localhost: 8080 / spring-security-rest / api / customers "}}}

V rámci každej reprezentácie zdrojov je a ja odkaz a všetky objednávky odkaz na výpis všetkých objednávok zákazníka. Ak zákazník nemá objednávky, odkaz na objednávky sa nezobrazí.

Tento príklad ukazuje, ako Spring HATEOAS podporuje objaviteľnosť API v odpočinkovej webovej službe. Ak odkaz existuje, klient ho môže sledovať a získať všetky objednávky pre zákazníka:

zvlnenie // localhost: 8080 / spring-security-rest / api / customers / 10A / objednávky 

{"_embedded": {"orderList": [{"orderId": "001A", "cena": 150, "množstvo": 25, "_links": {"self": {"href": "// localhost : 8080 / spring-security-rest / api / customers / 10A / 001A "}}}, {" orderId ":" 002A "," cena ": 250," množstvo ": 15," _links ": {" ja " : {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / 002A"}}}]}, "_links": {"self": {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / objednávky "}}}

8. Záver

V tomto tutoriáli sme diskutovali o tom, ako na to vybudovať webovú službu Spring REST založenú na hypermédiách pomocou projektu Spring HATEOAS.

V príklade vidíme, že klient môže mať jeden vstupný bod do aplikácie a na základe metadát v reprezentácii odpovede je možné podniknúť ďalšie kroky.

To umožňuje serveru zmeniť svoju schému URI bez toho, aby došlo k rozbitiu klienta. Aplikácia tiež môže inzerovať nové funkcie vložením nových odkazov alebo identifikátorov URI do reprezentácie.

Celú implementáciu tohto článku nakoniec nájdete v projekte GitHub.

REST spodok

Práve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:

>> SKONTROLUJTE KURZ