streamalism.org

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

1. Pregled

U ovom uputstvu ćemo raspravljati što je HAL i zašto je koristan prije predstavljanja HAL preglednika.

Zatim ćemo koristiti Spring za izgradnju jednostavnog REST API-ja s nekoliko zanimljivih krajnjih točaka i popunjavanje baze podataka nekim test podacima.

Napokon, pomoću preglednika HAL istražit ćemo naš REST API i otkriti kako prelaziti podatke sadržane u njemu.

2. HAL i HAL preglednik

JSON Hypertext Application Language, ili HAL, jednostavan je format daje dosljedan i jednostavan način hiperveze između resursa u našem API-ju. Uključivanje HAL-a u naš REST API čini ga mnogo istraživijim za korisnike, kao i samo-dokumentiranjem.

Djeluje vraćanjem podataka u JSON formatu koji daje relevantne informacije o API-ju.

The Model HAL vrti se oko dva jednostavna koncepta.

Resursi, koji sadrže:

• Veze na relevantne URI-je
• Ugrađeni resursi
• država

Veze:

• Ciljni URI
• Veza ili veza prema poveznici
• Nekoliko drugih opcijskih svojstava koja pomažu u amortizaciji, pregovaranju o sadržaju itd

Preglednik HAL stvorila je ista osoba koja je razvila HAL i pruža GUI unutar preglednika za prolazak kroz vaš REST API.

Sada ćemo izraditi jednostavan REST API, uključiti HAL preglednik i istražiti značajke.

3. Ovisnosti

Ispod je pojedinačna ovisnost potrebna za integriranje HAL preglednika u naš REST API. Ostatak ovisnosti za API možete pronaći u GitHub kodu.

Prvo, ovisnost za projekte temeljene na Mavenu:

 org.springframework.data spring-data-rest-hal-browser 3.2.6.OSLOBOĐENJE 

Ako gradite s Gradleom, možete dodati ovaj redak u svoj graditi.gradle datoteka:

kompajlirati grupu: 'org.springframework.data', naziv: 'spring-data-rest-hal-browser', verzija: '3.0.8.RELEASE'

4. Izgradnja jednostavnog REST API-ja

4.1. Jednostavan model podataka

U našem ćemo primjeru postaviti jednostavni REST API za pregledavanje različitih knjiga u našoj knjižnici.

Ovdje definiramo jednostavni entitet knjige koji sadrži odgovarajuće napomene kako bismo mogli ustrajati u podacima pomoću hibernacije:

@ Entity public class Book {@Id @GeneratedValue (strategy = GenerationType.IDENTITY) private long id; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) naslov privatnog niza; @NotNull @Column (columnDefinition = "VARCHAR", length = 100) autor privatnog niza; @Column (columnDefinition = "VARCHAR", length = 1000) private String blurb; privatne int stranice; // uobičajeni getteri, postavljači i konstruktori}

4.2. Predstavljamo CRUD repozitorij

Dalje, trebat će nam neke krajnje točke. Da bismo to učinili, možemo iskoristiti PagingAndSortingRepositoryi navedite da želimo dobiti podatke iz našeg Knjiga entitet.

Ovaj sat pruža jednostavne CRUD naredbe, kao i mogućnosti straničenja i sortiranja odmah iz kutije:

Javno sučelje @Repository BookRepository proširuje PagingAndSortingRepository {@RestResource (rel = "title-contains", path = "title-contains") Stranica findByTitleContaining (@Param ("query") String query, Pageable page); @RestResource (rel = "author-contains", path = "author-contains", exported = false) Stranica findByAuthorContaining (@Param ("query") String upit, stranica koja se može stranicati); }

Ako ovo izgleda pomalo čudno ili ako želite znati više o Spring Repozitorijima, više možete pročitati ovdje.

Proširili smo spremište dodavanjem dvije nove krajnje točke:

• findByTitleContaining - vraća knjige koje sadrže upit uključen u naslov
• findByAuthorContaining - vraća knjige iz baze podataka u kojoj autor knjige sadrži upit

Imajte na umu da je naš druga krajnja točka sadrži izvoz = lažno atribut. Ovaj atribut zaustavlja generiranje HAL veza za ovu krajnju točku, a neće biti dostupan putem HAL preglednika.

Napokon, podatke ćemo učitati kad se Spring pokrene definiranjem klase koja implementira ApplicationRunner sučelje. Kôd možete pronaći na GitHubu.

5. Instaliranje HAL preglednika

Postavljanje preglednika HAL izuzetno je jednostavno prilikom izrade REST API-ja s Springom. Sve dok imamo ovisnost, Spring će automatski konfigurirati preglednik i učiniti ga dostupnim putem zadane krajnje točke.

Sve što sada trebamo je pritisnuti run i prebaciti se na preglednik. Tada će preglednik HAL biti dostupan na // localhost: 8080 /

6. Istraživanje našeg REST API-ja pomoću HAL preglednika

The Preglednik HAL podijeljen je na dva dijela - istraživač i inspektor. Razdvojit ćemo i istražiti svaki odjeljak zasebno.

6.1. Istraživač HAL

Kao što zvuči, istraživač je posvećen istraživanje novih dijelova našeg API-ja u odnosu na trenutnu krajnju točku. Sadrži traku za pretraživanje, kao i tekstne okvire za prikaz Prilagođena zaglavlja i svojstva zahtjeva trenutne krajnje točke.

Ispod njih imamo odjeljak s vezama i popis ugrađenih resursa na koji je moguće kliknuti.

6.2. Korištenje veza

Ako krenemo do našeg / knjige krajnju točku možemo vidjeti postojeće poveznice:

Ovi poveznice se generiraju iz HAL-a u susjednom odjeljku:

"_links": {"first": {"href": "// localhost: 8080 / books? page = 0 & size = 20"}, "self": {"href": "// localhost: 8080 / books {? stranica, veličina, sortiranje} "," templated ": true}," next ": {" href ":" // localhost: 8080 / books? page = 1 & size = 20 "}," last ": {" href ": "// // localhost: 8080 / books? page = 4 & size = 20"}, "profile": {"href": "// localhost: 8080 / profile / books"}, "search": {"href": "/ / localhost: 8080 / books / search "}},

Ako pređemo na krajnju točku pretraživanja, možemo vidjeti i prilagođene krajnje točke koje smo stvorili pomoću PagingAndSortingRepository:

{"_links": {"title-contains": {"href": "// localhost: 8080 / books / search / title-contains {? query, page, size, sort}", "templated": true}, "self": {"href": "// localhost: 8080 / books / search"}}} 

Gornji HAL prikazuje naše naslov-sadrži krajnja točka koja prikazuje odgovarajuće kriterije pretraživanja. Primijetite kako autor-sadrži krajnja točka nedostaje jer smo definirali da se ne smije izvoziti.

6.3. Pregled ugrađenih resursa

Ugrađeni resursi prikazuju pojedinosti pojedinih knjiga na naš / knjige krajnja točka. Svaki resurs sadrži i svoj Svojstva i Veze odjeljak:

6.4. Korištenje obrazaca

Gumb upitnika u stupcu GET unutar odjeljka veza označava da se modal obrasca može koristiti za unos prilagođenih kriterija pretraživanja.

Ovdje je obrazac za naš naslov-sadrži krajnja točka:

Naš prilagođeni URI vraća prva stranica od 20 knjiga gdje naslov sadrži riječ "Java".

6.5. Hal inspektor

Inspektor čini desnu stranu preglednika i sadrži Zaglavlja odgovora i tijelo odgovora. Ovaj Podaci HAL-a koriste se za generiranje poveznica i ugrađenih resursa što smo vidjeli ranije u vodiču.

7. Zaključak

U ovom smo članku saželi što je HAL, zašto je koristan i zašto nam može pomoći u stvaranju vrhunski REST API-ji za samo-dokumentiranje.

Izgradili smo jednostavan REST API s Springom koji implementira PagingAndSortingRepository, kao i definiranje vlastitih krajnjih točaka. Vidjeli smo i kako izuzeti određene krajnje točke iz HAL preglednika.

Nakon definiranja našeg API-ja, popunili smo ga testnim podacima i detaljno istražili uz pomoć preglednika HAL. Vidjeli smo kako je strukturiran preglednik HAL i kontrole korisničkog sučelja koje su nam omogućile da prođemo kroz API i istražimo njegove podatke.

Kao i uvijek, kôd je dostupan na GitHub-u.

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