Panduan untuk Metadata Konfigurasi Boot Musim Semi

1. Gambaran keseluruhan

Semasa menulis aplikasi Spring Boot, sangat berguna untuk memetakan sifat konfigurasi ke kacang Java. Apa cara terbaik untuk mendokumentasikan sifat ini?

Dalam tutorial ini, kita akan meneroka Spring Boot Configuration Processor dan fail metadata JSON yang berkaitan yang mendokumentasikan makna, kekangan dan sebagainya setiap harta tanah.

2. Metadata Konfigurasi

Sebilangan besar aplikasi yang kami jalankan sebagai pembangun mesti dikonfigurasi hingga tahap tertentu. Namun, biasanya, kita tidak benar-benar memahami apa yang dilakukan parameter konfigurasi, jika ia memiliki nilai lalai, jika sudah tidak digunakan, dan kadang-kadang, kita bahkan tidak mengetahui bahawa harta itu ada.

Untuk membantu kami, Spring Boot menghasilkan metadata konfigurasi dalam fail JSON, yang memberi kami maklumat berguna tentang cara menggunakan sifat. Jadi, metadata konfigurasi adalah fail deskriptif yang mengandungi maklumat yang diperlukan untuk interaksi dengan sifat konfigurasi.

Perkara yang sangat menyenangkan mengenai fail ini ialah IDE juga dapat membacanya , memberi kami pelengkap automatik sifat Spring, dan juga petunjuk konfigurasi lain.

3. Kebergantungan

Untuk menghasilkan metadata konfigurasi ini, kami akan menggunakan pemproses konfigurasi dari pergantungan spring-boot-configuration-processor .

Oleh itu, mari teruskan dan tambahkan kebergantungan sebagai pilihan :

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

Ketergantungan ini akan memberi kita pemproses anotasi Java yang dipanggil semasa kita membina projek kita. Kami akan bercakap secara terperinci mengenai perkara ini di kemudian hari.

Merupakan amalan terbaik untuk menambahkan kebergantungan sebagai pilihan di Maven untuk mengelakkan @ConfigurationProperties daripada diterapkan ke modul lain yang digunakan oleh projek kami.

4. Contoh Sifat Konfigurasi

Untuk melihat pemproses beraksi, mari kita bayangkan kita mempunyai beberapa sifat yang perlu kita sertakan dalam aplikasi Spring Boot kami melalui kacang Java:

@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 }

Untuk melakukan ini, kami akan menggunakan anotasi @ConfigurationProperties . Pemproses konfigurasi mengimbas kelas dan kaedah dengan anotasi ini untuk mengakses parameter konfigurasi dan menghasilkan metadata konfigurasi.

Mari tambahkan beberapa sifat ini ke dalam fail sifat. Dalam kes ini, kami akan memanggilnya databaseaseproperties-test.properties :

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

Dan, untuk memastikan, kami juga akan menambahkan ujian untuk memastikan bahawa kami semua berbaris:

@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()); } }

Kami juga telah menambah sifat-sifat bersarang database.server.id dan database.server.port melalui kelas dalaman Server . Kita harus menambah Pelayan kelas dalaman dan juga pelayan lapangan dengan getter dan setternya sendiri.

Dalam ujian kami, mari buat pemeriksaan cepat untuk memastikan kami dapat mengatur dan membaca harta yang berjaya disarang juga:

@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()); }

Baiklah, sekarang kita sudah bersedia untuk menggunakan pemproses.

5. Menjana Metadata Konfigurasi

Kami sebutkan sebelumnya bahawa pemproses konfigurasi menghasilkan fail - ini menggunakan pemprosesan anotasi.

Oleh itu, setelah menyusun projek kami, kami akan melihat fail bernama spring-config-metadata.json di dalam target / class / 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": [] }

Seterusnya, mari kita lihat bagaimana mengubah anotasi pada kacang Java kita mempengaruhi metadata.

5.1. Maklumat Tambahan mengenai Konfigurasi Metadata

Pertama, mari tambah komen JavaDoc di Server .

Kedua, mari kita memberi nilai lalai kepada database.server.port lapangan dan akhirnya menambah @Min dan @Max anotasi:

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 }

Sekiranya kita memeriksa fail spring-config-metadata.json sekarang, kita akan melihat maklumat tambahan ini dicerminkan:

{ "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": [] }

Kita dapat memeriksa perbezaan dengan bidang database.server.ip dan database.server.port . Sesungguhnya, maklumat tambahan itu sangat membantu. Hasilnya, pemaju dan IDE lebih mudah memahami apa yang dilakukan oleh setiap harta tanah.

Kita juga harus memastikan kita mencetuskan build untuk mendapatkan fail yang dikemas kini. Di Eclipse, jika kita memeriksa pilihan Build Automatically , setiap tindakan save akan mencetuskan build. Di IntelliJ, kita harus mencetuskan binaan secara manual.

5.2. Memahami Format Metadata

Mari kita perhatikan lebih dekat fail metadata JSON dan bincangkan komponennya.

Kumpulan adalah item peringkat lebih tinggi yang digunakan untuk mengelompokkan sifat lain, tanpa menentukan nilai itu sendiri. Dalam contoh kami, kami mempunyai kumpulan pangkalan data , yang juga merupakan awalan sifat konfigurasi. Kami juga mempunyai kumpulan pelayan , yang kami buat melalui kelas dalaman dan kumpulan sifat ip dan port .

Properties adalah item konfigurasi yang mana kita dapat menentukan nilai. Properti ini ditetapkan dalam fail .properties atau .yml dan boleh mempunyai maklumat tambahan, seperti nilai dan pengesahan lalai, seperti yang kita lihat dalam contoh di atas.

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.

Seperti biasa, semua coretan kod yang disebutkan dalam artikel ini terdapat di repositori GitHub kami.