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 ukazuje, ako na to nastaviť REST na jar - kontrolné kódy a kódy odpovede HTTP, konfigurácia radenia užitočného zaťaženia a vyjednávania obsahu.

2. Pochopenie REST na jar

Jarný rámec podporuje dva spôsoby vytvárania služieb RESTful:

• pomocou MVC s ModelAndView
• pomocou prevádzačov správ HTTP

The ModelAndView prístup je starší a oveľa lepšie zdokumentovaný, ale aj podrobnejší a zložitejší. Snaží sa vrhnúť REST paradigmu do starého modelu, čo však nie je bezproblémové. Jarný tím to pochopil a poskytoval prvotriednu podporu REST počnúc jarom 3.0.

Nový prístup založený na HttpMessageConverter a anotácie, je oveľa ľahší a ľahko implementovateľný. Konfigurácia je minimálna a poskytuje rozumné predvolené hodnoty, ktoré by ste od služby RESTful očakávali.

3. Konfigurácia Java

@Configuration @EnableWebMvc verejná trieda WebConfig {//}

Nové @EnableWebMvc anotácia robí niektoré užitočné veci - konkrétne v prípade REST zistí existenciu Jacksona a JAXB 2 na ceste triedy a automaticky vytvorí a zaregistruje predvolené prevádzače JSON a XML. Funkčnosť anotácie je ekvivalentná verzii XML:

Toto je skratka a hoci to môže byť užitočné v mnohých situáciách, nie je to dokonalé. Ak je potrebná zložitejšia konfigurácia, odstráňte anotáciu a rozšírte ju WebMvcConfigurationSupport priamo.

3.1. Používanie Spring Boot

Ak používame @SpringBootApplication anotácia a jar-webmvc knižnica je na triednej ceste, potom @EnableWebMvc anotácia sa pridáva automaticky s predvolenou automatickou konfiguráciou.

Stále môžeme do tejto konfigurácie pridať funkčnosť MVC implementáciou WebMvcConfigurer rozhranie na a @ Konfigurácia komentovaná trieda. Môžeme tiež použiť a WebMvcRegistrationsAdapter napríklad poskytnúť svoje vlastné RequestMappingHandlerMapping, RequestMappingHandlerAdapteralebo ExceptionHandlerExceptionResolver implementácie.

Nakoniec, ak chceme zahodiť funkcie MVC Spring Boot a deklarovať vlastnú konfiguráciu, môžeme tak urobiť pomocou @EnableWebMvc anotácia.

4. Testovanie jarného kontextu

Od jari 3.1 dostávame podporu prvotriedneho testovania pre @ Konfigurácia triedy:

@RunWith (SpringJUnit4ClassRunner.class) @ContextConfiguration (classes = {WebConfig.class, PersistenceConfig.class}, loader = AnnotationConfigContextLoader.class) verejná trieda SpringContextIntegrationTest {@Test verejné void contextLoads ()

Špecifikujeme konfiguračné triedy Java s @ContextConfiguration anotácia. Nové AnnotationConfigContextLoader načíta definície fazule z @ Konfigurácia triedy.

Všimnite si, že WebConfig konfiguračná trieda nebola zahrnutá do testu, pretože je potrebné ju spustiť v kontexte servletu, ktorý nie je uvedený.

4.1. Používanie Spring Boot

Spring Boot poskytuje niekoľko anotácií na nastavenie Spring ApplicationContext pre naše testy intuitívnejším spôsobom.

Môžeme načítať iba konkrétny výrez konfigurácie aplikácie alebo môžeme simulovať celý proces spúšťania kontextu.

Napríklad môžeme použiť @SpringBootTest anotáciu, ak chceme, aby sa vytvoril celý kontext bez spustenia servera.

Keď je to na mieste, môžeme pridať @AutoConfigureMockMvc podať injekciu a MockMvc inštancie a odosielať požiadavky HTTP:

@RunWith (SpringRunner.class) @SpringBootTest @AutoConfigureMockMvc verejná trieda FooControllerAppIntegrationTest {@Autowired private MockMvc mockMvc; @Test public void whenTestApp_thenEmptyResponse () vyvolá výnimku {this.mockMvc.perform (get ("/ foos") .andExpect (status (). IsOk ()) .andExpect (...);}}

Aby sme sa vyhli vytvoreniu celého kontextu a testovali iba naše radiče MVC, môžeme použiť @WebMvcTest:

@RunWith (SpringRunner.class) @WebMvcTest (FooController.class) verejná trieda FooControllerWebLayerIntegrationTest {@Autowired private MockMvc mockMvc; @MockBean súkromná služba IFooService; @Test () public void whenTestMvcController_thenRetrieveExpectedResult () vyvolá výnimku {// ... this.mockMvc.perform (get ("/ foos") .andExpect (...);}}

Podrobné informácie o tejto téme nájdete v našom článku „Testovanie v jarnom zavedení“.

5. Prevádzkovateľ

The @RestController je ústredným artefaktom v celej webovej vrstve rozhrania RESTful API. Na účely tohto príspevku kontrolór modeluje jednoduchý prostriedok REST - Foo:

@RestController @RequestMapping ("/ foos") trieda FooController {@Autowired súkromná služba IFooService; @GetMapping verejný zoznam 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 resource) {Preconditions.checkNotNull (zdroj); návrat service.create (zdroj); } @PutMapping (value = "/ {id}") @ResponseStatus (HttpStatus.OK) public void update (@PathVariable ("id") Long id, @RequestBody Foo resource) {Preconditions.checkNotNull (zdroj); RestPreconditions.checkNotNull (service.getById (resource.getId ())); service.update (zdroj); } @DeleteMapping (value = "/ {id}") @ResponseStatus (HttpStatus.OK) public void delete (@PathVariable ("id") Long id) {service.deleteById (id); }}

Možno ste si všimli, že používam priamy, guavský štýl RestPreconditions užitočnosť:

public class RestPreconditions {public static T checkFound (T resource) {if (resource == null) {throw new MyResourceNotFoundException (); } návratový zdroj; }}

Implementácia radiča je neverejná - je to tak preto, lebo nemusí byť.

Ovládač je zvyčajne posledný v reťazci závislostí. Prijíma požiadavky HTTP z predného ovládača Spring (the DispatcherServlet) a jednoducho ich deleguje ďalej na vrstvu služieb. Ak nie je možné použiť prípad, keď musí byť kontrolór vložený alebo manipulovaný prostredníctvom priameho odkazu, radšej to nevyhlasujem ako verejné.

Mapovania požiadaviek sú jednoduché. Rovnako ako u každého radiča, skutočné hodnotu mapovania, ako aj metóda HTTP, určia cieľovú metódu pre požiadavku. @RequestBody naviaže parametre metódy na telo požiadavky HTTP, zatiaľ čo @ResponseBody robí to isté pre typ odpovede a návratu.

The @RestController je skratka zahrňujúca aj @ResponseBody a @ Kontrolór anotácie v našej triede.

Zaisťujú tiež, že zdroj bude zaradený a zrušený pomocou správneho prevodníka HTTP. Bude prebiehať rokovanie o obsahu s cieľom zvoliť, ktorý z aktívnych prevádzačov sa použije, väčšinou na základe súhlasiť hlavičku, aj keď na určenie reprezentácie je možné použiť aj iné hlavičky HTTP.

6. Mapovanie kódov odpovede HTTP

Stavové kódy odpovede HTTP sú jednou z najdôležitejších častí služby REST a subjekt sa môže rýchlo stať veľmi komplikovaným. Správne nastavenie môže byť to, čo robí alebo pokazí službu.

6.1. Nezmapované požiadavky

Ak Spring MVC dostane požiadavku, ktorá nemá mapovanie, považuje ju za neprípustnú a vráti klientovi SPÔSOB 405 NEDOVOLENÝ.

Je tiež dobrým zvykom zahrnúť Povoliť Hlavička HTTP pri vrátení a 405 klientovi, aby určil, ktoré operácie sú povolené. Toto je štandardné správanie Spring MVC a nevyžaduje žiadnu ďalšiu konfiguráciu.

6.2. Platné mapované požiadavky

Pre každú požiadavku, ktorá má mapovanie, považuje Spring MVC požiadavku za platnú a odpovie 200 OK, ak nie je uvedený iný stavový kód inak.

Je to kvôli tomu, čo kontrolór vyhlasuje za odlišné @ResponseStatus pre vytvoriť, aktualizovať a vymazať akcie, ale nie za dostať, ktorá by mala skutočne vrátiť predvolených 200 v poriadku.

6.3. Chyba klienta

V prípade chyby klienta sa definujú vlastné výnimky, ktoré sa mapujú na príslušné chybové kódy.

Jednoduchým odstránením týchto výnimiek z ktorejkoľvek z vrstiev webovej vrstvy sa zabezpečí, že Spring mapuje zodpovedajúci stavový kód v odpovedi HTTP:

@ResponseStatus (HttpStatus.BAD_REQUEST) verejná trieda BadRequestException rozširuje RuntimeException {//} @ResponseStatus (HttpStatus.NOT_FOUND) verejná trieda ResourceNotFoundException rozširuje RuntimeException {//}

Tieto výnimky sú súčasťou REST API a ako také by sa mali používať iba v príslušných vrstvách zodpovedajúcich REST; ak napríklad existuje vrstva DAO / DAL, nemala by priamo používať výnimky.

Upozorňujeme, že nejde o kontrolované výnimky, ale o výnimky za behu - v súlade s jarnými postupmi a idiómami.

6.4. Použitím @ExceptionHandler

Ďalšou možnosťou na mapovanie vlastných výnimiek pre konkrétne stavové kódy je použitie @ExceptionHandler anotácia v radiči. Problém tohto prístupu spočíva v tom, že anotácia sa týka iba ovládača, v ktorom je definovaná. To znamená, že musíme deklarovať v každom kontrolóri osobitne.

Samozrejme existuje viac spôsobov, ako riešiť chyby v Spring aj Spring Boot, ktoré ponúkajú väčšiu flexibilitu.

7. Ďalšie závislosti Maven

Navyše k jar-webmvc závislosť vyžadovaná pre štandardnú webovú aplikáciu, budeme musieť nastaviť radenie a oddeľovanie obsahu pre REST API:

  com.fasterxml.jackson.core jackson-databind 2.9.8 javax.xml.bind jaxb-api 2.3.1 runtime 

Toto sú knižnice, ktoré sa používajú na prevod reprezentácie prostriedku REST na formát JSON alebo XML.

7.1. Používanie Spring Boot

Ak chceme načítať zdroje formátované vo formáte JSON, Spring Boot poskytuje podporu pre rôzne knižnice, konkrétne Jackson, Gson a JSON-B.

Automatická konfigurácia sa vykoná iba zahrnutím ktorejkoľvek z mapovacích knižníc do cesty triedy.

Zvyčajne, ak vyvíjame webovú aplikáciu, len pridáme spring-boot-starter-web závislosť a spoliehajte sa na to, že do nášho projektu zahrnie všetky potrebné artefakty:

 org.springframework.boot spring-boot-starter-web 2.1.2.RELEASE 

Spring Boot predvolene používa Jackson.

Ak chceme serializovať naše zdroje vo formáte XML, budeme musieť pridať rozšírenie Jackson XML (jackson-dataformat-xml) k našim závislostiam, alebo záložná implementácia JAXB (štandardne poskytovaná v JDK) pomocou @XmlRootElement anotácia k nášmu zdroju.

8. Záver

Tento výukový program ilustroval, ako implementovať a nakonfigurovať službu REST pomocou jarnej a Java konfigurácie.

V ďalších článkoch série sa budem venovať objaviteľnosti API, pokročilému vyjednávaniu o obsahu a práci s ďalšími reprezentáciami Zdroj.

Celý kód tohto článku je k dispozícii na stránkach Github. Toto je projekt založený na Maven, takže by malo byť ľahké ho importovať a spustiť tak, ako je.

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