streamalism.org

1. Overzicht

Bij het schrijven van een Spring Boot-applicatie is het handig om configuratie-eigenschappen toe te wijzen aan Java Beans. Maar wat is de beste manier om deze eigenschappen te documenteren?

In deze zelfstudie verkennen we de Spring Boot-configuratieprocessor en de bijbehorende JSON-metadatabestanden die de betekenis, beperkingen, enzovoort van elke eigenschap documenteren.

2. Configuratiemetagegevens

De meeste applicaties waaraan we als ontwikkelaars werken, moeten tot op zekere hoogte configureerbaar zijn. Meestal begrijpen we echter niet echt wat een configuratieparameter doet, of deze een standaardwaarde heeft, of deze verouderd is, en soms weten we niet eens dat de eigenschap bestaat.

Om ons te helpen, genereert Spring Boot configuratiemetagegevens in een JSON-bestand, wat ons nuttige informatie geeft over het gebruik van de eigenschappen. Zo, de metadata van de configuratie is een beschrijvend bestand dat de nodige informatie bevat voor interactie met de configuratie-eigenschappen.

Het leuke van dit bestand is dat IDE's kunnen het ook lezen, waardoor we de eigenschappen van Spring automatisch aanvullen, evenals andere configuratiehints.

3. Afhankelijkheden

Om deze configuratiemetadata te genereren, gebruiken we de configuratieprocessor van het spring-boot-configuratie-processor afhankelijkheid.

Dus laten we doorgaan en de afhankelijkheid toevoegen als optioneel:

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

Deze afhankelijkheid geeft ons een Java-annotatieprocessor die wordt aangeroepen wanneer we ons project bouwen. We zullen hier later in detail over praten.

Het is een best practice om een ​​afhankelijkheid toe te voegen als optioneel in Maven om te voorkomen @ConfigurationProperties van toepassing op andere modules die ons project gebruikt.

4. Configuratie-eigenschappen Voorbeeld

Om de processor in actie te zien, stellen we ons voor dat we een paar eigenschappen hebben die we via een Java-bean in onze Spring Boot-applicatie moeten opnemen:

@Configuration @ConfigurationProperties (prefix = "database") openbare klasse DatabaseProperties {openbare statische klasse Server {privé String ip; privé int poort; // standard getters and setters} private String gebruikersnaam; privé String-wachtwoord; privé serverserver; // standaard getters en setters}

Om dit te doen, gebruiken we de @ConfigurationProperties annotatie. De configuratieprocessor zoekt met deze annotatie naar klassen en methoden om toegang te krijgen tot de configuratieparameters en om metagegevens van de configuratie te genereren.

Laten we een paar van deze eigenschappen toevoegen aan een eigenschappenbestand. In dit geval noemen we het databaseproperties-test.properties:

# Eenvoudige eigenschappen database.username = baeldung database.password = wachtwoord

En voor de zekerheid voegen we ook een test toe om er zeker van te zijn dat we allemaal in de rij staan:

@RunWith (SpringRunner.class) @SpringBootTest (klassen = AnnotationProcessorApplication.class) @TestPropertySource ("classpath: databaseproperties-test.properties") openbare klasse DatabasePropertiesIntegrationTest {@Autowired privé DatabaseProperties databaseProperties; @Test openbare leegte whenSimplePropertyQueriedThenReturnsPropertyValue () gooit Uitzondering {Assert.assertEquals ("Onjuist gebonden gebruikersnaameigenschap", "baeldung", databaseProperties.getUsername ()); Assert.assertEquals ("Onjuist gebonden wachtwoordeigenschap", "wachtwoord", databaseProperties.getPassword ()); }}

We hebben ook de geneste eigenschappen toegevoegd database.server.id en database.server.port via de innerlijke klasse Server. We zouden de innerlijke klasse moeten toevoegen Server evenals een veld server met zijn eigen vangstof en zetter.

Laten we in onze test een snelle controle uitvoeren om er zeker van te zijn dat we ook geneste eigenschappen met succes kunnen instellen en lezen:

@Test public void whenNestedPropertyQueriedThenReturnsPropertyValue () genereert Uitzondering {Assert.assertEquals ("Onjuist gebonden Server IP geneste eigenschap", "127.0.0.1", databaseProperties.getServer (). GetIp ()); Assert.assertEquals ("Onjuist gebonden geneste eigenschap van serverpoort", 3306, databaseProperties.getServer (). GetPort ()); }

Oké, nu zijn we klaar om de processor te gebruiken.

5. Configuratiemetagegevens genereren

We hebben eerder vermeld dat de configuratieprocessor een bestand genereert - het maakt gebruik van annotatieverwerking.

Dus na het samenstellen van ons project zullen we een bestand genaamd spring-configuratie-metadata.json binnen doel / klassen / META-INF:

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

Laten we vervolgens kijken hoe veranderende annotaties op onze Java-bonen van invloed zijn op de metadata.

5.1. Aanvullende informatie over configuratiemetagegevens

Laten we eerst JavaDoc-opmerkingen toevoegen aan Server.

Ten tweede: laten we een standaardwaarde geven aan de database.server.port veld en voeg tenslotte het @Min en @Max annotaties:

public static class Server {/ ** * Het IP-adres van de databaseserver * / private String ip; / ** * De poort van de databaseserver. * De standaardwaarde is 443. * De toegestane waarden liggen in het bereik van 400-4000. * / @Min (400) @Max (800) privé int-poort = 443; // standaard getters en setters}

Als we het spring-configuratie-metadata.json bestand nu, dan zien we deze extra informatie terug:

{"groups": [{"name": "database", "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"}, {" naam ":" database.server "," type ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties $ Server "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "," sourceMethod ":" getServer ( ) "}]," eigenschappen ": [{" naam ":" database.password "," type ":" java.lang.String "," sourceType ":" com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties "}, {"name": "database.server.ip", "type": "java.lang.String", "description": "Het IP-adres van de databaseserver", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor .DatabaseProperties $ Server "}, {" naam ":" database.server.port "," type ":" java.lang.Integer "," description ":" De poort van de databaseserver. De standaardwaarde is 443. De toegestane waarden liggen in het bereik 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": []}

We kunnen de verschillen controleren met de database.server.ip en database.server.port velden. De extra informatie is inderdaad heel nuttig. Het resultaat is dat het voor ontwikkelaars en IDE's veel gemakkelijker is om te begrijpen wat elke eigenschap doet.

We moeten er ook voor zorgen dat we de build activeren om het bijgewerkte bestand op te halen. Als we in Eclipse het Bouw automatisch optie, zal elke opslagactie een build activeren. In IntelliJ moeten we de build handmatig activeren.

5.2. Inzicht in de metadata-indeling

Laten we het JSON-metadatabestand eens nader bekijken en de componenten ervan bespreken.

Groepen zijn items op een hoger niveau die worden gebruikt om andere eigenschappen te groeperen, zonder zelf een waarde op te geven. In ons voorbeeld hebben we de database group, dat ook het voorvoegsel is van de configuratie-eigenschappen. We hebben ook een server groep, die we hebben gemaakt via een innerlijke klasse en groepen ik p en haven eigendommen.

Eigendommen zijn configuratie-items waarvoor we een waarde kunnen specificeren. Deze eigenschappen zijn ingesteld .eigendommen of .yml bestanden en kunnen extra informatie bevatten, zoals standaardwaarden en validaties, zoals we in het bovenstaande voorbeeld hebben gezien.

Hints zijn aanvullende informatie om de gebruiker te helpen bij het instellen van de eigenschapswaarde. Als we bijvoorbeeld een reeks toegestane waarden voor een eigenschap hebben, kunnen we een beschrijving geven van wat elk van hen doet. De IDE biedt hulp bij de autocompetitie voor deze hints.

Elk onderdeel van de metadata van de configuratie heeft zijn eigen attributen om de configuratie-eigenschappen in meer detail uit te leggen.

6. Conclusie

In dit artikel hebben we gekeken naar de Spring Boot-configuratieprocessor en de mogelijkheid om configuratiemetagegevens te maken. Het gebruik van deze metadata maakt het een stuk eenvoudiger om te communiceren met onze configuratieparameters.

We gaven een voorbeeld van een gegenereerde configuratiemetagegevens en legden in detail het formaat en de componenten ervan uit.

We hebben ook gezien hoe nuttig de ondersteuning voor automatisch aanvullen op onze IDE kan zijn.

Zoals altijd zijn alle codefragmenten die in dit artikel worden genoemd, te vinden op onze GitHub-repository.