streamalism.org

1. Oversigt

Når du skriver et Spring Boot-program, er det nyttigt at kortlægge konfigurationsegenskaber på Java-bønner. Hvad er dog den bedste måde at dokumentere disse egenskaber på?

I denne vejledning undersøger vi Spring Boot Configuration Processor og de tilknyttede JSON-metadatafiler, der dokumenterer hver egenskabs betydning, begrænsninger osv.

2. Konfigurationsmetadata

De fleste af de applikationer, vi arbejder på som udviklere, skal kunne konfigureres til en vis grad. Normalt forstår vi dog ikke rigtig, hvad en konfigurationsparameter gør, hvis den har en standardværdi, hvis den er udfaset, og til tider ved vi ikke engang, at ejendommen eksisterer.

For at hjælpe os genererer Spring Boot konfigurationsmetadata i en JSON-fil, som giver os nyttige oplysninger om, hvordan vi bruger egenskaberne. Så, konfigurationsmetadataene er en beskrivende fil, der indeholder de nødvendige oplysninger til interaktion med konfigurationsegenskaberne.

Det rigtig pæne ved denne fil er, at IDE'er kan også læse det, der giver os autofuldførelse af Spring-egenskaber samt andre konfigurationstip.

3. Afhængigheder

For at generere denne konfigurationsmetadata bruger vi konfigurationsprocessoren fra fjeder-boot-konfiguration-processor afhængighed.

Så lad os gå videre og tilføje afhængighed som valgfri:

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

Denne afhængighed giver os en Java-annoteringsprocessor, der påberåbes, når vi bygger vores projekt. Vi taler detaljeret om dette senere.

Det er en bedste praksis at tilføje en afhængighed som valgfri i Maven for at forhindre @ConfigurationProperties fra at blive anvendt på andre moduler, som vores projekt bruger.

4. Eksempel på konfigurationsegenskaber

For at se processoren i aktion, lad os forestille os, at vi har et par egenskaber, som vi skal medtage i vores Spring Boot-applikation via en Java-bønne:

@Configuration @ConfigurationProperties (prefix = "database") offentlig klasse DatabaseProperties {offentlig statisk klasse Server {privat streng ip; privat int port; // standard getters og setter} private streng brugernavn; privat strengadgangskode; privat server server; // standard getters og setter}

For at gøre dette bruger vi @ConfigurationProperties kommentar. Konfigurationsprocessoren scanner efter klasser og metoder med denne kommentar for at få adgang til konfigurationsparametrene og generere konfigurationsmetadata.

Lad os tilføje et par af disse egenskaber i en egenskabsfil. I dette tilfælde kalder vi det databaseproperties-test.properties:

#Simple Properties database.username = baeldung database.password = password

Og bare for at være sikker tilføjer vi også en test for at sikre, at vi alle er opstillet:

@RunWith (SpringRunner.class) @SpringBootTest (klasser = AnnotationProcessorApplication.class) @TestPropertySource ("classpath: databaseproperties-test.properties") public class DatabasePropertiesIntegrationTest {@Autowired private DatabaseProperties database; @Test offentlig ugyldigt nårSimplePropertyQueriedThenReturnsPropertyValue () kaster undtagelse {Assert.assertEquals ("Forkert bundet brugernavn egenskab", "baeldung", databaseProperties.getUsername ()); Assert.assertEquals ("Forkert bundet adgangskodeegenskab", "adgangskode", databaseProperties.getPassword ()); }}

Vi har også tilføjet de indlejrede ejendomme database.server.id og database.server.port via den indre klasse Server. Vi skal tilføje den indre klasse Server såvel som et felt server med sin egen getter og setter.

Lad os i vores test foretage en hurtig kontrol for at sikre, at vi også kan indstille og læse indlejrede egenskaber:

@Test offentlig ugyldig nårNestedPropertyQueriedThenReturnsPropertyValue () kaster undtagelse {Assert.assertEquals ("Forkert bundet server IP-indlejret egenskab", "127.0.0.1", databaseProperties.getServer (). GetIp ()); Assert.assertEquals ("Forkert bundet serverport indlejret ejendom", 3306, databaseProperties.getServer (). GetPort ()); }

Okay, nu er vi klar til at bruge processoren.

5. Generering af konfigurationsmetadata

Vi nævnte tidligere, at konfigurationsprocessoren genererer en fil - den bruger dette annoteringsbehandling.

Så efter udarbejdelse af vores projekt ser vi en fil kaldet spring-configuration-metadata.json inde mål / klasser / META-INF:

{"grupper": [{"name": "database", "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}, {" navn ":" database.server "," type ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "," sourceMethod ":" getServer ( ) "}]," egenskaber ": [{" 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"}], "hints": []}

Lad os derefter se, hvordan ændrede annoteringer på vores Java-bønner påvirker metadataene.

5.1. Yderligere oplysninger om konfigurationsmetadata

Lad os først tilføje JavaDoc-kommentarer til Server.

For det andet, lad os give en standardværdi til database.server.port felt og til sidst tilføje @Min og @Max kommentarer:

offentlig statisk klasse Server {/ ** * Databaseserverens IP / private streng ip; / ** * Databaseserverens havn. * Standardværdien er 443. * De tilladte værdier er i området 400-4000. * / @Min (400) @Max (800) privat int port = 443; // standard getters og setter}

Hvis vi tjekker spring-configuration-metadata.json fil nu, vi ser disse ekstra oplysninger afspejles:

{"grupper": [{"name": "database", "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}, {" navn ":" database.server "," type ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "," sourceMethod ":" getServer ( ) "}]," egenskaber ": [{" name ":" database.password "," type ":" java.lang.String "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "}, {"name": "database.server.ip", "type": "java.lang.String", "description": "Databaseserverens IP", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor .DatabaseProperties $ Server "}, {" name ":" database.server.port "," type ":" java.lang.Integer "," description ":" Porten til databaseserveren. Standardværdien er 443. De tilladte værdier er i området 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"}], "hints": []}

Vi kan kontrollere forskellene med database.server.ip og database.server.port felter. Faktisk er de ekstra oplysninger ret nyttige. Som et resultat er det meget lettere for udviklere og IDE'er at forstå, hvad hver ejendom gør.

Vi skal også sørge for, at vi udløser build for at få den opdaterede fil. I Eclipse, hvis vi tjekker Byg automatisk valgmulighed, vil hver gemte handling udløse en build. I IntelliJ skal vi udløse bygningen manuelt.

5.2. Forståelse af metadataformatet

Lad os se nærmere på JSON-metadatafilen og diskutere dens komponenter.

Grupper er elementer på højere niveau, der bruges til at gruppere andre egenskaber uden at angive en værdi selv. I vores eksempel har vi database gruppe, som også er præfikset for konfigurationsegenskaberne. Vi har også en server gruppe, som vi oprettede via en indre klasse og grupper ip og Havn ejendomme.

Ejendomme er konfigurationselementer, som vi kan angive en værdi for. Disse egenskaber er angivet i .ejendomme eller .yml filer og kan have ekstra information, som standardværdier og valideringer, som vi så i eksemplet ovenfor.

Tips er yderligere oplysninger, der hjælper brugeren med at indstille ejendomsværdien. For eksempel, hvis vi har et sæt tilladt værdi for en ejendom, kan vi give en beskrivelse af, hvad hver af dem gør. IDE vil yde hjælp til auto-konkurrence til disse tip.

Hver komponent i konfigurationsmetadata har sine egne attributter til at forklare konfigurationsegenskaberne i mere detaljerede detaljer.

6. Konklusion

I denne artikel kiggede vi på Spring Boot Configuration Processor og dens evne til at oprette konfigurationsmetadata. Brug af disse metadata gør det meget nemmere at interagere med vores konfigurationsparametre.

Vi gav et eksempel på en genereret konfigurationsmetadata og forklarede detaljeret dets format og komponenter.

Vi så også, hvor hjælpsom den autofuldførte support på vores IDE kan være.

Som altid kan alle kodestykker, der er nævnt i denne artikel, findes i vores GitHub-lager.