Hozzon létre egy REST API-t a Spring és a Java Config segítségével

REST felső

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

>> ELLENŐRIZZE A FOLYAMATOT

1. Áttekintés

Ez a cikk bemutatja, hogyan kell tavasszal felállította a REST-et - a vezérlő és a HTTP válaszkódok, a hasznos teher rendezésének és a tartalmi egyeztetés konfigurációja.

2. A REST megértése tavasszal

A tavaszi keret a RESTful szolgáltatások létrehozásának két módját támogatja:

  • az MVC használatával ModelAndView
  • HTTP üzenet konverterek használatával

A ModelAndView A megközelítés régebbi és sokkal jobban dokumentált, ugyanakkor bőbeszédűbb és konfigurációsbb is. Megpróbálja a REST paradigmát a régi modellbe cipelni, ami nem probléma. A tavaszi csapat megértette ezt, és első osztályú REST támogatást nyújtott a 3.0 tavasztól kezdve.

Az új megközelítés, amely HttpMessageConverter és a kommentárokkal sokkal könnyebb és könnyebben kivitelezhető. A konfiguráció minimális, ésszerű alapértelmezéseket nyújt arra vonatkozóan, amit elvárhat egy RESTful szolgáltatástól.

3. A Java konfiguráció

@Configuration @EnableWebMvc public class WebConfig {//}

Az új @EnableWebMvc az annotáció hasznos dolgokat végez - konkrétan a REST esetében felismeri Jackson és JAXB 2 létezését az osztályúton, és automatikusan létrehozza és regisztrálja az alapértelmezett JSON és XML konvertereket. Az annotáció funkcionalitása egyenértékű az XML verzióval:

Ez egy parancsikon, és bár sok helyzetben hasznos lehet, mégsem tökéletes. Ha bonyolultabb konfigurációra van szükség, távolítsa el a feliratot és bontsa ki WebMvcConfigurationSupport közvetlenül.

3.1. A Spring Boot használata

Ha a @SpringBootApplication kommentár és a tavasz-webmvc könyvtár az osztályúton van, akkor a @EnableWebMvc a kommentár automatikusan hozzáadásra kerül az alapértelmezett automatikus beállítással.

Az MVC funkcionalitását továbbra is hozzáadhatjuk ehhez a konfigurációhoz a WebMvcConfigurer interfész a @ Konfiguráció jegyzetekkel ellátott osztály. Használhatjuk a WebMvcRegistrationsAdapter például a sajátjaink biztosítására RequestMappingHandlerMapping, RequestMappingHandlerAdapter, vagy ExceptionHandlerExceptionResolver megvalósítások.

Végül, ha el akarjuk dobni a Spring Boot MVC szolgáltatásait és deklarálunk egy egyedi konfigurációt, akkor ezt megtehetjük a @EnableWebMvc annotáció.

4. A tavaszi kontextus tesztelése

A 3.1 tavasztól kezdve első osztályú tesztelési támogatást kapunk @ Konfiguráció osztályok:

@RunWith (SpringJUnit4ClassRunner.class) @ContextConfiguration (class = {WebConfig.class, PersistenceConfig.class}, loader = AnnotationConfigContextLoader.class) public class SpringContextIntegrationTest {@Test public void context Whenloads ((

A Java konfigurációs osztályokat a @ContextConfiguration annotáció. Az új AnnotationConfigContextLoader betölti a babdefiníciókat a @ Konfiguráció osztályok.

Figyeljük meg, hogy a WebConfig konfigurációs osztály nem került bele a tesztbe, mert Servlet-környezetben kell futnia, ami nincs megadva.

4.1. A Spring Boot használata

A Spring Boot számos feljegyzéssel látja el a Spring beállítását ApplicationContext tesztjeinkhez intuitívabb módon.

Betölthetünk csak egy adott szeletet az alkalmazáskonfigurációból, vagy szimulálhatjuk a teljes kontextus indítási folyamatot.

Például használhatjuk a @SpringBootTest megjegyzés, ha azt akarjuk, hogy a teljes kontextus létrejöjjön a szerver indítása nélkül.

Ha ez a helyén van, akkor hozzáadhatjuk a @AutoConfigureMockMvc beadni a MockMvc példányt és küldjön HTTP kéréseket:

@RunWith (SpringRunner.class) @SpringBootTest @AutoConfigureMockMvc nyilvános osztály FooControllerAppIntegrationTest {@Autowired private MockMvc mockMvc; @Test public void, amikor a TestApp_thenEmptyResponse () kivételt dob ​​{this.mockMvc.perform (get ("/ foos") .andExpect (status (). IsOk ()) .ésExpect (...);}}

Annak elkerülése érdekében, hogy létrehozzuk a teljes kontextust, és csak az MVC vezérlőket teszteljük, használhatjuk @WebMvcTest:

@RunWith (SpringRunner.class) @WebMvcTest (FooController.class) nyilvános osztály FooControllerWebLayerIntegrationTest {@Autowired private MockMvc mockMvc; @MockBean IFooService privát szolgáltatás; A @Test () public void amikor a TestMvcController_thenRetrieveExpectedResult () kivételt dob ​​{// ... this.mockMvc.perform (get ("/ foos") .andExpect (...);}}

Részletes információkat találhatunk erről a témáról a „Tesztelés tavaszi csomagtartóban” cikkünkben.

5. A vezérlő

A @RestController a RESTful API teljes webszintjének központi műtárgya. E bejegyzés céljára a vezérlő egy egyszerű REST erőforrást modellez - Foo:

@RestController @RequestMapping ("/ foos") osztályú FooController {@Autowired privát IFooService szolgáltatás; @GetMapping public List findAll () {return service.findAll (); } @GetMapping (value = "/ {id}") public Foo findById (@PathVariable ("id") Long id) {return RestPreconditions.checkFound (service.findById (id)); } @PostMapping @ResponseStatus (HttpStatus.CREATED) public Long create (@RequestBody Foo erőforrás) {Preconditions.checkNotNull (erőforrás); return service.create (erőforrás); } @PutMapping (value = "/ {id}") @ResponseStatus (HttpStatus.OK) public void update (@PathVariable ("id") Long id, @RequestBody Foo erőforrás) {Preconditions.checkNotNull (erőforrás); RestPreconditions.checkNotNull (service.getById (resource.getId ())); service.update (erőforrás); } @DeleteMapping (value = "/ {id}") @ResponseStatus (HttpStatus.OK) public void delete (@PathVariable ("id") Long id) {service.deleteById (id); }}

Talán észrevette, hogy egyenes, guavai stílust használok RestPreconditions hasznosság:

public class RestPreconditions {public static T checkFound (T erőforrás) {if (erőforrás == null) {dobjon új MyResourceNotFoundException (); } visszatérési erőforrás; }}

A vezérlő implementációja nem nyilvános - ez azért van, mert nem kell annak lennie.

Általában a vezérlő az utolsó a függőségi láncban. HTTP kéréseket fogad a Spring front vezérlőtől (a DispatcherServlet), és egyszerűen átadja őket egy szolgáltatási rétegnek. Ha nincs olyan eset, amikor a vezérlőt közvetlen referencián keresztül kell beadni vagy manipulálni, akkor inkább nem nyilvánítom nyilvánosnak.

A kérelem-hozzárendelések egyértelműek. Mint minden vezérlőnél, a tényleges érték a leképezés, valamint a HTTP metódus meghatározza a kérelem célmódszerét. @RequestBody a metódus paramétereit a HTTP kérés törzséhez fogja kötni, míg @ResponseBody ugyanezt teszi a válasz és a visszatérés típusával.

A @RestController rövidítés, amely magában foglalja mind a @ResponseBody és a @Vezérlő jegyzetek az osztályunkban.

Gondoskodnak arról is, hogy az erőforrás a megfelelő HTTP-átalakító segítségével rendeződjön és megszűnik. Tartalmi egyeztetésre kerül sor annak kiválasztására, hogy melyik aktív átalakítót használják, főleg a Elfogad fejléc, bár más HTTP fejlécek is felhasználhatók az ábrázolás meghatározására.

6. A HTTP válaszkódok feltérképezése

A HTTP válasz állapotkódjai a REST szolgáltatás egyik legfontosabb része, és a téma gyorsan nagyon bonyolulttá válhat. Ezeknek a helyes megszerzése lehet az, ami megszakítja vagy megszakítja a szolgáltatást.

6.1. Nem feltérképezett kérések

Ha a Spring MVC olyan kérést kap, amely nem rendelkezik leképezéssel, úgy ítéli meg, hogy a kérés nem engedélyezett, és egy 405 NEM Engedélyezett módszert küld vissza az ügyfélnek.

Az is jó gyakorlat, ha a Lehetővé teszi HTTP fejléc a 405 az ügyfélnek, hogy megadják, mely műveletek engedélyezettek. Ez a Spring MVC szokásos viselkedése, és nem igényel további konfigurációt.

6.2. Érvényes leképezett kérések

Minden lekérdezéssel, amely rendelkezik leképezéssel, a Spring MVC érvényesnek tekinti a kérést, és 200 OK-val válaszol, ha más státuskód nincs megadva másként.

Emiatt a vezérlő másként nyilatkozik @ResponseStatus a teremt, frissítés és töröl cselekedetek, de nem kap, aminek valóban vissza kell adnia az alapértelmezett 200 OK-ot.

6.3. Kliens hiba

Kliens hiba esetén az egyedi kivételeket definiálják és hozzárendelik a megfelelő hibakódokhoz.

Ha ezeket a kivételeket egyszerűen elveti a webszint bármely rétegéről, akkor Spring biztosítja a megfelelő állapotkódot a HTTP-válaszon:

@ResponseStatus (HttpStatus.BAD_REQUEST) nyilvános osztály BadRequestException kiterjeszti a RuntimeException {//} @ResponseStatus (HttpStatus.NOT_FOUND) nyilvános osztály ResourceNotFoundException kiterjeszti RuntimeException {//}

Ezek a kivételek a REST API részei, és mint ilyenek, csak a REST-nek megfelelő megfelelő rétegekben szabad használni; ha például létezik DAO / DAL réteg, akkor nem használja közvetlenül a kivételeket.

Vegye figyelembe azt is, hogy ezek nem ellenőrzött kivételek, hanem futásidejű kivételek - összhangban a tavaszi gyakorlatokkal és szólásokkal.

6.4. Használata @ExceptionHandler

Egy másik lehetőség az egyedi kivételek leképezésére az adott állapotkódokra a @ExceptionHandler annotáció a vezérlőben. Ezzel a megközelítéssel az a probléma, hogy az annotáció csak arra a vezérlőre vonatkozik, amelyben meghatározták. Ez azt jelenti, hogy minden vezérlőben külön-külön kell nyilatkoznunk.

Természetesen a Spring és Spring Boot hibáinak kezelésére is több módszer kínál nagyobb rugalmasságot.

7. További Maven-függőségek

Amellett, hogy a tavasz-webmvc a szokásos webalkalmazáshoz szükséges függőség, be kell állítanunk a REST API tartalom-rendezését és eltávolítását:

  com.fasterxml.jackson.core jackson-databind 2.9.8 javax.xml.bind jaxb-api 2.3.1 futásidejű 

Ezek azok a könyvtárak, amelyek a REST erőforrás ábrázolását JSON vagy XML formátumra konvertálják.

7.1. A Spring Boot használata

Ha JSON-formátumú erőforrásokat szeretnénk beolvasni, a Spring Boot támogatást nyújt a különböző könyvtárakhoz, nevezetesen Jackson, Gson és JSON-B.

Az automatikus konfigurálást úgy végezzük, hogy a leképező könyvtárak bármelyikét belefoglaljuk az osztályútba.

Általában, ha webes alkalmazást fejlesztünk, csak hozzáadjuk a tavasz-boot-starter-web függőséget, és támaszkodhat rá, hogy belefoglalja a projektünk összes szükséges tárgyát:

 org.springframework.boot spring-boot-starter-web 2.1.2.FELHASZNÁLÁS 

A Spring Boot alapértelmezés szerint Jacksont használja.

Ha erőforrásainkat XML formátumban szeretnénk sorosítani, hozzá kell adnunk a Jackson XML kiterjesztést (jackson-dataformat-xml) függőségeinkre, vagy a JAXB megvalósításának (amely alapértelmezés szerint a JDK-ban van) a @XmlRootElement kommentár az erőforrásunkon.

8. Következtetés

Ez az oktatóanyag bemutatja, hogyan lehet egy REST szolgáltatást megvalósítani és konfigurálni a Spring és a Java alapú konfiguráció segítségével.

A sorozat következő cikkeiben az API felfedezhetőségére, a fejlett tartalmi tárgyalásokra és a Forrás.

A cikk összes kódja elérhető a Github oldalon. Ez egy Maven-alapú projekt, ezért könnyen importálhatónak és futtathatónak kell lennie.

REST alsó

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

>> ELLENŐRIZZE A FOLYAMATOT