Hozzon létre egy REST API-t a Spring és a Java Config segítségével
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 FOLYAMATOT1. Á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ó