streamalism.org

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:

1. Áttekintés

Ez a cikk elmagyarázza a hipermédia által vezérelt REST webszolgáltatás létrehozásának folyamatát a Spring HATEOAS projekt segítségével.

2. Tavasz-HATEOAS

A tavaszi HATEOAS projekt az API-k könyvtárát jelenti, amelyek segítségével könnyen létrehozhatunk olyan REST reprezentációkat, amelyek követik a HATEOAS (Hypertext as the Engine of Application State) elvét.

Általánosságban elmondható, hogy az alapelv azt jelenti, hogy az API-nak végig kell vezetnie az ügyfelet az alkalmazáson keresztül azáltal, hogy az egyes válaszokkal együtt releváns információkat ad vissza a következő lehetséges lépésekről.

Ebben a cikkben egy példát fogunk építeni a Spring HATEOAS segítségével azzal a céllal, hogy leválasszuk az ügyfelet és a kiszolgálót, és elméletileg lehetővé tesszük az API számára, hogy az ügyfelek feltörése nélkül megváltoztassa az URI sémáját.

3. Előkészítés

Először tegyük hozzá a tavaszi HATEOAS-függőséget:

 org.springframework.boot spring-boot-starter-hateoas 2.1.4.KÖZLEMÉNY 

Ha nem a Spring Boot programot használjuk, akkor a következő könyvtárakat vehetjük fel projektünkbe:

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

Mint mindig, a Maven Central-ban is megkereshetjük a HATEOAS indító, a rugós-hateoák és a rugós-plugin-core függőségek legújabb verzióit.

Ezután megvan a Vevő forrás tavaszi HATEOAS támogatás nélkül:

public class Ügyfél {private String customerId; privát String ügyfélNév; privát String companyName; // szabványos mérőeszközök és beállítók} 

És van egy kontroller osztályunk a Spring HATEOAS támogatás nélkül:

@RestController @RequestMapping (value = "/ customers") public class CustomerController {@Autowired private CustomerService customerService; @GetMapping ("/ {customerId}") nyilvános ügyfél getCustomerById (@PathVariable String customerId) {return customerService.getCustomerDetail (customerId); }} 

Végül a Vevő erőforrás reprezentáció:

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

4. A HATEOAS támogatás hozzáadása

Egy tavaszi HATEOAS projektben nincs szükségünk sem a Servlet-kontextus megkeresésére, sem az útváltozó összefűzésére az alap URI-ba.

Helyette, A HATEOAS tavasz három absztrakciót kínál az URI létrehozásához - RepresentationModel, Link és WebMvcLinkBuilder. Ezekkel felhasználhatjuk a metaadatok létrehozását és az erőforrás-reprezentációhoz való társítását.

4.1. A Hypermedia támogatás hozzáadása egy erőforráshoz

A projekt biztosítja az úgynevezett alaposztályt RepresentationModel örökölni az erőforrás-reprezentáció létrehozásakor:

public class Az ügyfél kiterjeszti a RepresentationModel {private String customerId; privát String ügyfélNév; privát String companyName; // szabványos mérőeszközök és beállítók} 

A Vevő erőforrás a RepresentationModel osztály örökli a add () módszer. Tehát miután létrehoztunk egy linket, könnyen beállíthatjuk ezt az értéket az erőforrás-ábrázoláshoz anélkül, hogy új mezőket adnánk hozzá.

4.2. Linkek létrehozása

A tavaszi HATEOAS a Link objektum a metaadatok tárolására (az erőforrás helye vagy URI-ja).

Először létrehozunk egy egyszerű linket manuálisan:

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

A Link objektum követi a Atom link szintaxist, és a rel amely azonosítja az erőforrással való kapcsolatot és href attribútum, amely maga a tényleges link.

Itt van, hogyan Vevő Az erőforrás most úgy néz ki, hogy tartalmazza az új linket:

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

A válaszhoz társított URI minősítés a maga link. A szemantika a maga A kapcsolat egyértelmű - ez egyszerűen az a kanonikus hely, ahol az erőforrás elérhető.

4.3. Jobb linkek létrehozása

A könyvtár egy másik nagyon fontos absztrakciója az a WebMvcLinkBuilder - ami leegyszerűsíti az URI-k összeállítását elkerülve a keményen kódolt linkeket.

A következő részlet részletesen bemutatja az ügyfél önlinkjének felépítését a WebMvcLinkBuilder osztály:

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

Nézzük meg:

• a link ehhez() metódus megvizsgálja a vezérlő osztályt és megszerzi annak gyökér leképezését
• a vágás() módszer hozzáadja a Ügyfél-azonosító érték a link útváltozójaként
• végül a withSelfMethod () a kapcsolatot önkapcsolatnak minősíti

5. Kapcsolatok

Az előző részben megmutattunk egy önreferencia relációt. Az összetettebb rendszerek azonban más kapcsolatokat is magukban foglalhatnak.

Például a vevő kapcsolata lehet a megrendelésekkel. Modellezzük a Rendelés osztály, mint erőforrás:

public class Order kiterjeszti a RepresentationModel {private String orderId; magán dupla ár; privát int mennyiség; // szabványos mérőeszközök és beállítók} 

Ezen a ponton kiterjeszthetjük a CustomerController olyan módszerrel, amely egy adott ügyfél összes megrendelését visszaadja:

@GetMapping (value = "/ {customerId} / megrendelések", = = "application / hal + json"}) nyilvános CollectionModel getOrdersForCustomer (@PathVariable final String customerId) {List megrendelések = orderService.getAllOrdersForCustomer (customerId); for (végső megrendelés: megrendelések) {Link selfLink = linkTo (methodOn (CustomerController.class) .getOrderById (customerId, order.getOrderId ())). withSelfRel (); rendelés.add (selfLink); } Link link = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithSelfRel (); CollectionModel eredmény = new CollectionModel (megrendelések, link); visszatérési eredmény; } 

Módszerünk a CollectionModel objektumot, hogy megfeleljen a HAL visszatérési típusnak, valamint_maga" link az egyes megrendelésekhez és a teljes lista.

Fontos észrevenni itt, hogy az ügyfélrendelések hiperhivatala a feltérképezésétől függ getOrdersForCustomer () módszer. Az ilyen típusú hivatkozásokra metódus linkként hivatkozunk, és megmutatjuk, hogyan WebMvcLinkBuilder segíthet létrehozásában.

6. Linkek a vezérlő módszereihez

A WebMvcLinkBuilder gazdag támogatást kínál a tavaszi MVC vezérlők számára. Az alábbi példa bemutatja, hogyan lehet a HATEOAS hiperhivatkozásokat a getOrdersForCustomer () módszere CustomerController osztály:

Link megrendelésekLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)). WithRel ("allOrders"); 

A methodOn () megkapja a módszer leképezését a cél metódus dummy meghívásával a proxy vezérlőn, és beállítja a Ügyfél-azonosító mint az URI útváltozója.

7. Tavaszi HATEOAS akcióban

Tegyük össze az önlinket és a metódus link létrehozását a getAllCustomers () módszer:

@GetMapping (produkció = {"application / hal + json"}) nyilvános CollectionModel getAllCustomers () {List allCustomers = customerService.allCustomers (); for (Ügyfél ügyfél: allCustomers) {String customerId = customer.getCustomerId (); Link selfLink = linkTo (CustomerController.class) .slash (customerId) .withSelfRel (); customer.add (selfLink); if (orderService.getAllOrdersForCustomer (customerId) .size ()> 0) {Link megrendelésekLink = linkTo (methodOn (CustomerController.class) .getOrdersForCustomer (customerId)) withRel ("allOrders"); ügyfél.add (megrendelésekLink); }} Link link = linkTo (CustomerController.class) .withSelfRel (); CollectionModel eredmény = new CollectionModel (allCustomers, link); visszatérési eredmény; }

Ezután hívjuk meg a getAllCustomers () módszer:

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

És vizsgálja meg az eredményt:

{"_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 / megrendelések: "}}}, {" 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 / megrendelések "}}} , {"customerId": "30C", "customerName": "Tim", "companyName": "CKV Company", "_linkek": {"self": {"href": "// localhost: 8080 / spring- security-rest / api / customers / 30C "}}}]]}," _linkek ": {" self ": {" href ":" // localhost: 8080 / spring-security-rest / api / customers "}}}

Az egyes erőforrás-ábrázolásokon belül van egy maga link és a allRendelések link az ügyfél összes megrendelésének kibontásához. Ha az ügyfélnek nincs megrendelése, akkor a megrendelések linkje nem jelenik meg.

Ez a példa bemutatja, hogy a Spring HATEOAS hogyan segíti elő az API felfedezhetőségét egy pihenő webes szolgáltatásban. Ha a link létezik, az ügyfél követheti azt, és megszerezheti az összes megrendelést az ügyfél számára:

curl // localhost: 8080 / spring-security-rest / api / customers / 10A / megrendelések 

{"_embedded": {"orderList": [{"orderId": "001A", "price": 150, "mennyiség": 25, "_linkek": {"self": {"href": "// localhost : 8080 / spring-security-rest / api / customers / 10A / 001A "}}}, {" orderId ":" 002A "," price ": 250," mennyiség ": 15," _linkek ": {" self " : {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / 002A"}}}]]}, "_links": {"self": {"href": "// localhost: 8080 / spring-security-rest / api / customers / 10A / megrendelések "}}}

8. Következtetés

Ebben az oktatóanyagban megvitattuk, hogyan kell készítsen egy hipermédia által vezérelt Spring REST webszolgáltatást a Spring HATEOAS projekt segítségével.

A példában azt látjuk, hogy az ügyfélnek egyetlen belépési pontja lehet az alkalmazáshoz, és a válaszábrázolás metaadatai alapján további műveletek hajthatók végre.

Ez lehetővé teszi a kiszolgáló számára az URI-séma megváltoztatását az ügyfél megszakítása nélkül. Az alkalmazás új lehetőségeket is hirdethet azáltal, hogy új hivatkozásokat vagy URI-kat tesz a reprezentációba.

Végül a cikk teljes megvalósítása megtalálható a GitHub projektben.

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak: