Eine Anleitung zu Spring Boot-Konfigurationsmetadaten

1. Übersicht

Beim Schreiben einer Spring Boot-Anwendung ist es hilfreich, Konfigurationseigenschaften Java-Beans zuzuordnen. Wie lassen sich diese Eigenschaften jedoch am besten dokumentieren?

In diesem Lernprogramm werden der Spring Boot-Konfigurationsprozessor und die zugehörigen JSON-Metadatendateien erläutert, in denen die Bedeutung, Einschränkungen usw. der einzelnen Eigenschaften dokumentiert sind.

2. Konfigurationsmetadaten

Die meisten Anwendungen, an denen wir als Entwickler arbeiten, müssen bis zu einem gewissen Grad konfigurierbar sein. Normalerweise verstehen wir jedoch nicht wirklich, was ein Konfigurationsparameter tut, wenn er einen Standardwert hat, wenn er veraltet ist, und manchmal wissen wir nicht einmal, dass die Eigenschaft existiert.

Um uns dabei zu helfen, generiert Spring Boot Konfigurationsmetadaten in einer JSON-Datei, die nützliche Informationen zur Verwendung der Eigenschaften enthält. So ist die Konfiguration von Metadaten eine Beschreibungsdatei , die die notwendigen Informationen für die Interaktion enthält mit den Konfigurationseigenschaften.

Das wirklich Schöne an dieser Datei ist, dass IDEs sie auch lesen können, wodurch wir die Spring-Eigenschaften sowie andere Konfigurationshinweise automatisch vervollständigen können .

3. Abhängigkeiten

Um diese Konfigurationsmetadaten zu generieren, verwenden wir den Konfigurationsprozessor aus der Abhängigkeit vom Spring-Boot-Konfigurationsprozessor .

Lassen Sie uns also die Abhängigkeit als optional hinzufügen :

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

Diese Abhängigkeit stellt uns einen Java-Annotationsprozessor zur Verfügung, der beim Erstellen unseres Projekts aufgerufen wird. Wir werden später ausführlich darüber sprechen.

Es wird empfohlen, in Maven eine optionale Abhängigkeit hinzuzufügen, um zu verhindern, dass @ConfigurationProperties auf andere Module angewendet wird, die in unserem Projekt verwendet werden.

4. Beispiel für Konfigurationseigenschaften

Um den Prozessor in Aktion zu sehen, stellen wir uns vor, wir haben einige Eigenschaften, die wir über eine Java-Bean in unsere Spring Boot-Anwendung aufnehmen müssen:

@Configuration @ConfigurationProperties(prefix = "database") public class DatabaseProperties { public static class Server { private String ip; private int port; // standard getters and setters } private String username; private String password; private Server server; // standard getters and setters }

Dazu verwenden wir die Annotation @ConfigurationProperties . Der Konfigurationsprozessor sucht mit dieser Anmerkung nach Klassen und Methoden, um auf die Konfigurationsparameter zuzugreifen und Konfigurationsmetadaten zu generieren.

Fügen wir einer Eigenschaftendatei einige dieser Eigenschaften hinzu. In diesem Fall nennen wir es databaseProperties-test.properties :

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

Und um sicherzugehen, werden wir auch einen Test hinzufügen, um sicherzustellen, dass wir alle in einer Reihe stehen:

@RunWith(SpringRunner.class) @SpringBootTest(classes = AnnotationProcessorApplication.class) @TestPropertySource("classpath:databaseproperties-test.properties") public class DatabasePropertiesIntegrationTest { @Autowired private DatabaseProperties databaseProperties; @Test public void whenSimplePropertyQueriedThenReturnsPropertyValue() throws Exception { Assert.assertEquals("Incorrectly bound Username property", "baeldung", databaseProperties.getUsername()); Assert.assertEquals("Incorrectly bound Password property", "password", databaseProperties.getPassword()); } }

Wir haben auch die verschachtelten Eigenschaften database.server.id und database.server.port über den Server der inneren Klasse hinzugefügt . Wir sollten den Server der inneren Klasse sowie einen Feldserver mit einem eigenen Getter und Setter hinzufügen .

Lassen Sie uns in unserem Test eine kurze Überprüfung durchführen, um sicherzustellen, dass wir auch erfolgreich verschachtelte Eigenschaften festlegen und lesen können:

@Test public void whenNestedPropertyQueriedThenReturnsPropertyValue() throws Exception { Assert.assertEquals("Incorrectly bound Server IP nested property", "127.0.0.1", databaseProperties.getServer().getIp()); Assert.assertEquals("Incorrectly bound Server Port nested property", 3306, databaseProperties.getServer().getPort()); }

Okay, jetzt können wir den Prozessor verwenden.

5. Generieren von Konfigurationsmetadaten

Wir haben bereits erwähnt, dass der Konfigurationsprozessor eine Datei generiert. Dabei wird die Annotationsverarbeitung verwendet.

Nachdem wir unser Projekt kompiliert haben, sehen wir eine Datei namens spring-configuration-metadata.json in target / classes / 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" } ], "hints": [] }

Lassen Sie uns als Nächstes sehen, wie sich das Ändern von Anmerkungen auf unseren Java-Beans auf die Metadaten auswirkt.

5.1. Zusätzliche Informationen zu Konfigurationsmetadaten

Fügen wir zunächst JavaDoc-Kommentare zum Server hinzu .

Zweitens geben wir dem Feld database.server.port einen Standardwert und fügen schließlich die Anmerkungen @Min und @Max hinzu :

public static class Server { /** * The IP of the database server */ private String ip; /** * The Port of the database server. * The Default value is 443. * The allowed values are in the range 400-4000. */ @Min(400) @Max(800) private int port = 443; // standard getters and setters }

Wenn wir jetzt die Datei spring-configuration-metadata.json überprüfen , werden diese zusätzlichen Informationen angezeigt:

{ "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": "The IP of the database server", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server" }, { "name": "database.server.port", "type": "java.lang.Integer", "description": "The Port of the database server. The Default value is 443. The allowed values are in the range 400-4000", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server", "defaultValue": 443 }, { "name": "database.username", "type": "java.lang.String", "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties" } ], "hints": [] }

Wir können die Unterschiede mit den Feldern database.server.ip und database.server.port überprüfen . In der Tat sind die zusätzlichen Informationen sehr hilfreich. Infolgedessen ist es für Entwickler und IDEs viel einfacher zu verstehen, was jede Eigenschaft tut.

Wir sollten auch sicherstellen, dass wir den Build auslösen, um die aktualisierte Datei zu erhalten. Wenn wir in Eclipse die Option Automatisch erstellen aktivieren, löst jede Speicheraktion einen Build aus. In IntelliJ sollten wir den Build manuell auslösen.

5.2. Grundlegendes zum Metadatenformat

Schauen wir uns die JSON-Metadatendatei genauer an und diskutieren ihre Komponenten.

Gruppen sind übergeordnete Elemente, mit denen andere Eigenschaften gruppiert werden, ohne dass selbst ein Wert angegeben wird. In unserem Beispiel haben wir die Datenbankgruppe , die auch das Präfix der Konfigurationseigenschaften ist. Wir haben auch eine Server - Gruppe, die wir über eine innere Klasse erstellt und Gruppen ip und port Eigenschaften.

Eigenschaften sind Konfigurationselemente, für die wir einen Wert angeben können. Diese Eigenschaften werden in .properties- oder .yml- Dateien festgelegt und können zusätzliche Informationen wie Standardwerte und Validierungen enthalten, wie wir im obigen Beispiel gesehen haben.

Hints are additional information to help the user set the property value. For example, if we have a set of allowed value for a property, we can provide a description of what each of them does. The IDE will provide auto-competition help for these hints.

Each component on the configuration metadata has its own attributes to explain in finer details the configuration properties.

6. Conclusion

In this article, we looked at the Spring Boot Configuration Processor and its ability to create configuration metadata. Using this metadata makes it a lot easier to interact with our configuration parameters.

We gave an example of a generated configuration metadata and explained in details its format and components.

We also saw how helpful the autocomplete support on our IDE can be.

Wie immer finden Sie alle in diesem Artikel erwähnten Codefragmente in unserem GitHub-Repository.