streamalism.org

1. Prehľad

Pri písaní aplikácie Spring Boot je užitočné mapovať vlastnosti konfigurácie na fazuľa Java. Aký je najlepší spôsob zdokumentovania týchto vlastností?

V tomto tutoriáli sa pozrieme na Spring Boot Configuration Processor a súvisiace súbory metadát JSON, ktoré dokumentujú význam, obmedzenia atď. Každej vlastnosti.

2. Konfiguračné metadáta

Väčšina aplikácií, na ktorých pracujeme ako vývojári, musí byť do istej miery konfigurovateľná. Zvyčajne však naozaj nerozumieme tomu, čo konfiguračný parameter robí, ak má predvolenú hodnotu, ak je zastaraná a niekedy ani nevieme, či vlastnosť existuje.

Aby sme nám pomohli, Spring Boot generuje metadáta konfigurácie v súbore JSON, čo nám dáva užitočné informácie o tom, ako používať vlastnosti. Takže konfiguračné metadáta sú popisný súbor, ktorý obsahuje informácie potrebné na interakciu s vlastnosťami konfigurácie.

Skutočne pekné na tomto súbore je to Môžu si ho prečítať aj IDE, ktorá nám poskytuje automatické dopĺňanie vlastností pružiny, ako aj ďalšie tipy na konfiguráciu.

3. Závislosti

Na vygenerovanie týchto metaúdajov konfigurácie použijeme konfiguračný procesor z spring-boot-configuration-processor závislosť.

Poďme teda a pridajme závislosť ako voliteľné:

 org.springframework.boot spring-boot-configuration-processor 2.1.6.RELEASE true 

Táto závislosť nám poskytne procesor anotácií Java vyvolaný pri zostavovaní nášho projektu. O tom si ešte povieme neskôr.

Osvedčeným postupom je pridať závislosť ako voliteľné v Maven, aby sa zabránilo @ConfigurationProperties od použitia na ďalšie moduly, ktoré náš projekt používa.

4. Príklad vlastností konfigurácie

Aby sme videli procesor v akcii, predstavme si, že máme niekoľko vlastností, ktoré musíme zahrnúť do našej aplikácie Spring Boot cez fazuľa Java:

@Configuration @ConfigurationProperties (prefix = "databáza") verejná trieda DatabaseProperties {verejná statická trieda Server {súkromný reťazec ip; súkromný int port; // štandardní vyhľadávači a nastavovatelia} private Reťazec používateľské meno; súkromné ​​reťazcové heslo; súkromný serverový server; // štandardné getre a setre}

K tomu by sme použili @ConfigurationProperties anotácia. Konfiguračný procesor vyhľadáva triedy a metódy s touto anotáciou pre prístup k konfiguračným parametrom a generovanie konfiguračných metadát.

Pridajme niekoľko týchto vlastností do súboru vlastností. V tomto prípade to nazveme databaseproperties-test.properties:

# Jednoduché vlastnosti database.username = baeldung database.password = heslo

A pre istotu pridáme aj test, aby sme sa ubezpečili, že sme všetci zoradení:

@RunWith (SpringRunner.class) @SpringBootTest (classes = AnnotationProcessorApplication.class) @TestPropertySource ("classpath: databaseproperties-test.properties") verejná trieda DatabasePropertiesIntegrationTest {@Autowired private DatabaseProperties databaseProperties; @Test public void whenSimplePropertyQueriedThenReturnsPropertyValue () vyvolá výnimku {Assert.assertEquals ("Nesprávne viazaná vlastnosť používateľského mena", "baeldung", databaseProperties.getUsername ()); Assert.assertEquals ("Nesprávne viazaná vlastnosť hesla", "heslo", databaseProperties.getPassword ()); }}

Pridali sme tiež vnorené vlastnosti database.server.id a databáza.server.port cez vnútornú triedu Server. Mali by sme pridať vnútornú triedu Server aj pole server s vlastným getrom a setrom.

V našom teste urobíme rýchlu kontrolu, aby sme sa ubezpečili, že môžeme nastaviť a načítať aj úspešne vnorené vlastnosti:

@Test public void whenNestedPropertyQueriedThenReturnsPropertyValue () vyvolá výnimku {Assert.assertEquals ("Nesprávne viazaná vnorená vlastnosť servera IP", "127.0.0.1", databaseProperties.getServer (). GetIp ()); Assert.assertEquals ("Nesprávne viazaná vnorená vlastnosť serverového portu", 3306, databaseProperties.getServer (). GetPort ()); }

Dobre, teraz sme pripravení použiť procesor.

5. Generovanie konfiguračných metadát

Už sme spomenuli, že konfiguračný procesor generuje súbor - používa to anotačné spracovanie.

Po zostavení nášho projektu sa teda dočkáme a súbor s názvom spring-configuration-metadata.json vo vnútri cieľ / triedy / META-INF:

{"groups": [{"name": "database", "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}, {" name ":" database.server "," type ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "," sourceMethod ":" getServer ( ) "}]," properties ": [{" name ":" database.password "," type ":" java.lang.String "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "}, {"name": "database.server.ip", "type": "java.lang.String", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server"}, {"name": " database.server.port "," type ":" java.lang.Integer "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," defaultValue ": 0}, {" name ":" database.username "," type ":" java.lang.String " , "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}], "rady": []}

Ďalej sa pozrime, ako zmena anotácií v našich Java fazuliach ovplyvní metadáta.

5.1. Ďalšie informácie o metaúdajoch konfigurácie

Najskôr pridajme komentáre JavaDoc Server.

Po druhé, dajme predvolenú hodnotu parametru databáza.server.port pole a nakoniec pridajte @ Min a @ Max anotácie:

verejná statická trieda Server {/ ** * IP databázového servera * / private String ip; / ** * Port databázového servera. * Predvolená hodnota je 443. * Povolené hodnoty sú v rozmedzí 400-4000. * / @Min (400) @Max (800) private int port = 443; // štandardné getre a setre}

Ak skontrolujeme spring-configuration-metadata.json teraz, uvidíme tieto ďalšie informácie:

{"groups": [{"name": "database", "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}, {" name ":" database.server "," type ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "," sourceMethod ":" getServer ( ) "}]," properties ": [{" name ":" database.password "," type ":" java.lang.String "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "}, {"name": "database.server.ip", "type": "java.lang.String", "description": "IP databázového servera", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor .DatabaseProperties $ Server "}, {" name ":" database.server.port "," type ":" java.lang.Integer "," description ":" Port databázového servera. Predvolená hodnota je 443. Povolené hodnoty sú v rozmedzí 400-4000 "" s ourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," defaultValue ": 443}, {" name ":" database.username "," type ":" java.lang.String "," sourceType " : "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}], "rady": []}

Rozdiely môžeme skontrolovať pomocou database.server.ip a databáza.server.port polia. Dodatočné informácie sú skutočne užitočné. Vďaka tomu je pre vývojárov a IDE oveľa jednoduchšie pochopiť, čo jednotlivé vlastnosti robia.

Mali by sme sa tiež ubezpečiť, že spustíme zostavenie, aby sme získali aktualizovaný súbor. V Eclipse, ak skontrolujeme Stavať automaticky možnosť, každá akcia uloženia spustí zostavenie. V IntelliJ by sme mali spustiť zostavenie manuálne.

5.2. Porozumenie formátu metadát

Pozrime sa podrobnejšie na súbor metadát JSON a rozoberme jeho komponenty.

Skupiny sú položky vyššej úrovne používané na zoskupenie ďalších vlastností bez uvedenia samotnej hodnoty. V našom príklade máme databázy skupina, ktorá je zároveň predponou vlastností konfigurácie. Máme tiež a server skupina, ktorú sme vytvorili prostredníctvom vnútornej triedy a skupín ip a prístav vlastnosti.

Vlastnosti sú konfiguračné položky, pre ktoré môžeme určiť hodnotu. Tieto vlastnosti sú nastavené v .vlastnosti alebo .yml súbory a môžu obsahovať ďalšie informácie, napríklad predvolené hodnoty a overenia, ako sme videli v príklade vyššie.

Rady sú ďalšie informácie, ktoré pomôžu používateľovi nastaviť hodnotu vlastnosti. Napríklad, ak máme pre nehnuteľnosť sadu povolených hodnôt, môžeme poskytnúť popis toho, čo každá z nich robí. IDE poskytne pre tieto tipy pomoc s automatickou súťažou.

Každý komponent v metadátach konfigurácie má svoje vlastné atribúty, ktoré podrobnejšie vysvetľujú vlastnosti konfigurácie.

6. Záver

V tomto článku sme sa pozreli na Spring Boot Configuration Processor a jeho schopnosť vytvárať konfiguračné metadáta. Používanie týchto metadát výrazne uľahčuje interakciu s našimi konfiguračnými parametrami.

Uviedli sme príklad vygenerovaných metaúdajov konfigurácie a podrobne sme vysvetlili ich formát a komponenty.

Tiež sme videli, ako užitočná môže byť podpora automatického dokončovania na našom IDE.

Ako vždy, všetky útržky kódu uvedené v tomto článku nájdete v našom úložisku GitHub.