24. 外部配置 · Spring Boot 1.5.2 中文文檔

# 24\. 外部配置 Spring Boot允許您外部化您的配置，以便您可以在不同的環境中使用相同的應用程序代碼。您可以使用properties文件，YAML文件，環境變量和命令行參數來外部化配置。可以使用@Value注釋將屬性值直接注入到您的bean中，該注釋可通過Spring環境(Environment)抽象訪問，或通過@ConfigurationProperties[綁定到結構化對象](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-typesafe-configuration-properties)。 Spring Boot使用非常特別的PropertySource命令，旨在允許合理地覆蓋值。屬性按以下順序選擇： 1. 在您的HOME目錄設置的[Devtools全局屬性](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#using-boot-devtools-globalsettings)（~/.spring-boot-devtools.properties）。 2. 單元測試中的?[@TestPropertySource](http://docs.spring.io/spring/docs/4.3.7.RELEASE/javadoc-api/org/springframework/test/context/TestPropertySource.html)?注解。 3. 單元測試中的?[@SpringBootTest#properties](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/api/spring-boot-test/src/main/java/org/springframework/boot/test/context/SpringBootTest.html)?注解屬性 4. 命令行參數。 5. SPRING_APPLICATION_JSON 中的屬性值（內嵌JSON嵌入到環境變量或系統屬性中）。 6. ServletConfig 初始化參數。 7. ServletContext 初始化參數。 8. 來自 java:comp/env 的JNDI屬性。 9. Java系統屬性（System.getProperties()）。 10. 操作系統環境變量。 11. RandomValuePropertySource，只有隨機的屬性 random.* 中。 12. jar包外面的?[Profile-specific application properties](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-profile-specific-properties)?（application- {profile} .properties和YAML變體） 13. jar包內的?[Profile-specific application properties](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-profile-specific-properties)?（application-{profile}.properties和YAML變體） 14. jar包外的應用屬性文件（application.properties和YAML變體）。 15. jar包內的應用屬性文件（application.properties和YAML變體）。 16. 在@Configuration上的@PropertySource注解。 17. 默認屬性（使用SpringApplication.setDefaultProperties設置）。一個具體的例子，假設你開發一個使用name屬性的@Component： ``` import org.springframework.stereotype.* import org.springframework.beans.factory.annotation.* @Component public class MyBean { @Value("${name}") private String name; // ... } ``` 在應用程序類路徑（例如，您的jar中）中，您可以擁有一個application.properties，它為 name 屬性提供了默認屬性值。在新環境中運行時，可以在您的jar外部提供一個application.properties來覆蓋 name 屬性; 對于一次性測試，您可以使用特定的命令行開關啟動（例如，java -jar app.jar --name="Spring"）。 SPRING_APPLICATION_JSON屬性可以在命令行中提供一個環境變量。例如在UN*X shell中： ``` $ SPRING_APPLICATION_JSON='{"foo":{"bar":"spam"}}' java -jar myapp.jar ``` 在本例中，您將在Spring環境中使用foo.bar = spam。您也可以在系統變量中將JSON作為spring.application.json提供： ``` $ java -Dspring.application.json='{"foo":"bar"}' -jar myapp.jar ``` 或命令行參數： ``` $ java -jar myapp.jar --spring.application.json='{"foo":"bar"}' ``` 或作為JNDI變量 java:comp/env/spring.application.json 。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#241-配置隨機值)24.1 配置隨機值 RandomValuePropertySource可用于注入隨機值（例如，進入秘密或測試用例）。它可以產生整數，長整數，uuid或字符串，例如 ``` my.secret=${random.value} my.number=${random.int} my.bignumber=${random.long} my.uuid=${random.uuid} my.number.less.than.ten=${random.int(10)} my.number.in.range=${random.int[1024,65536]} ``` [random.int](http://random.int) *語法是 OPEN value (,max) CLOSE ，其中OPEN，CLOSE是任何字符和值，max是整數。如果提供max，則值為最小值，max為最大值（獨占）。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#242-訪問命令行屬性)24.2 訪問命令行屬性默認情況下，SpringApplication將任何命令行選項參數（以'-- '開頭，例如--server.port=9000）轉換為屬性，并將其添加到Spring環境中。如上所述，命令行屬性始終優先于其他屬性來源。如果不希望將命令行屬性添加到環境中，可以使用SpringApplication.setAddCommandLineProperties(false)禁用它們。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#243-應用程序屬性文件)24.3 應用程序屬性文件 SpringApplication將從以下位置的application.properties文件中加載屬性，并將它們添加到Spring Environment中： 1. 當前目錄的/config子目錄 2. 當前目錄 3. classpath中/config包 4. classpath root路徑該列表按優先級從高到低排序。 > 也可以[使用YAML（'.yml'）文件](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-yaml)替代“.properties”。如果您不喜歡application.properties作為配置文件名，[可以通過指定一個spring.config.name](http://xn--spring-9m7igl21dt6y8qu0luc56kg7a.config.name/)?Spring environment屬性來切換到另一個。您還可以使用spring.config.location環境屬性（用逗號分隔的目錄位置列表或文件路徑）顯式引用位置。 ``` $ java -jar myproject.jar --spring.config.name=myproject ``` 或 ``` $ java -jar myproject.jar --spring.config.location=classpath:/default.properties,classpath:/override.properties ``` > [spring.config.name](http://spring.config.name)和spring.config.location一開始就被用于確定哪些文件必須被加載，因此必須將它們定義為環境屬性（通常是OS env，system屬性或命令行參數）。如果spring.config.location包含的如果是目錄而非文件，那么它們應該以/結尾（并將在加載之前附加從[spring.config.name](http://spring.config.name)生成的名稱，包括profile-specific的文件名）。在spring.config.location中指定的文件按原樣使用，不支持特定于配置文件的變體，并且將被任何特定于配置文件的屬性覆蓋。默認的搜索路徑 classpath:,[classpath:/config,file:,file:config/](http://classpath/config,file:,file:config/) 始終會被搜索，不管spring.config.location的值如何。該搜索路徑從優先級排序從低到高（file:config/最高）。如果您指定自己的位置，則它們優先于所有默認位置，并使用相同的從最低到最高優先級排序。這樣，您可以在application.properties（或使用[spring.config.name](http://spring.config.name)選擇的任何其他基礎名稱）中為應用程序設置默認值，并在運行時使用不同的文件覆蓋它，并保留默認值。 > 如果您使用環境(environment)變量而不是系統屬性，大多數操作系統不允許使用句點分隔(period-separated)的鍵名稱，但可以使用下劃線（例如，SPRING_CONFIG_NAME，[而不是spring.config.name](http://xn--spring-vp7io16nrw9b.config.name/)） > 如果您運行在容器中，則可以使用JNDI屬性（在 java:comp/env 中）或servlet上下文初始化參數，而不是環境變量或系統屬性。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#244-指定配置profile-specific的屬性)24.4 指定配置(Profile-specific)的屬性除了application.properties文件外，還可以使用命名約定application- {profile}.properties定義的指定配置文件。環境具有一組默認配置文件，如果沒有設置活動配置文件（即，如果沒有顯式激活配置文件，則加載了來自application-default.properties的屬性）。指定配置文件（Profile-specific）的屬性從與標準application.properties相同的位置加載，指定配置( profile-specific)文件始終覆蓋非指定文件，而不管指定配置文件是否在打包的jar內部或外部。如果有幾個指定配置文件，則應用最后一個配置。例如，由spring.profiles.active屬性指定的配置文件在通過SpringApplication API配置的配置之后添加，因此優先級高。 > 如果您在spring.config.location中指定了任何文件，則不會考慮這些特定配置(profile-specific)文件的變體。如果您還想使用指定配置(profile-specific)文件的屬性，請使用`spring.config.location`中的目錄。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#245-properties-文件中的占位符)24.5 properties 文件中的占位符 application.properties中的值在使用時通過已有的環境進行過濾，以便您可以引用之前定義的值（例如，從系統屬性）。 ``` app.name=MyApp app.description=${app.name} is a Spring Boot application ``` > 您也可以使用此技術創建現有Spring Boot屬性的“簡寫“。有關詳細信息，請參見[第72.4節“使用”短命令行參數“how-to”](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#howto-use-short-command-line-arguments)。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#246-使用yaml替代-properties)24.6 使用YAML替代 Properties [YAML](http://yaml.org/)是JSON的超集，因此這是分層配置數據一種非常方便的格式，。每當您的類路徑中都有[SnakeYAML](http://www.snakeyaml.org/)庫時，SpringApplication類將自動支持YAML作為 properties 的替代方法。 > 如果您使用“Starters”，SnakeYAML將通過spring-boot-starter自動提供。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2461-加載-yaml)24.6.1 加載 YAML Spring Framework提供了兩個方便的類，可用于加載YAML文檔。?`YamlPropertiesFactoryBean`將YAML作為`Properties`加載，`YamlMapFactoryBean`將YAML作為Map加載。例如，下面YAML文檔： ``` environments: dev: url: http://dev.bar.com name: Developer Setup prod: url: http://foo.bar.com name: My Cool App ``` 將轉化為屬性： ``` environments.dev.url=http://dev.bar.com environments.dev.name=Developer Setup environments.prod.url=http://foo.bar.com environments.prod.name=My Cool App ``` YAML列表表示為具有[index] dereferencers的屬性鍵，例如YAML： ``` my: servers: - dev.bar.com - foo.bar.com ``` 將轉化為屬性： ``` my.servers[0]=dev.bar.com my.servers[1]=foo.bar.com ``` 要使用Spring DataBinder工具（@ConfigurationProperties做的）綁定到這樣的屬性，您需要有一個屬性類型為java.util.List（或Set）的目標bean，并且您需要提供一個setter，或者用可變值初始化它，例如這將綁定到上面的屬性 ``` @ConfigurationProperties(prefix="my") public class Config { private List<String> servers = new ArrayList<String>(); public List<String> getServers() { return this.servers; } } ``` #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2462-將yaml作為spring環境中的屬性文件)24.6.2 將YAML作為Spring環境中的屬性文件可以使用YamlPropertySourceLoader類在Spring環境中將YAML作為PropertySource暴露出來。這允許您使用熟悉的@Value注解和占位符語法來訪問YAML屬性。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2463-多個yaml文件)24.6.3 多個YAML文件您可以使用`spring.profiles`鍵指定單個文件中的多個特定配置文件YAML文檔，以指示文檔何時應用。例如： ``` server: address: 192.168.1.100 --- spring: profiles: development server: address: 127.0.0.1 --- spring: profiles: production server: address: 192.168.1.120 ``` 在上面的示例中，如果開發配置文件處于活動狀態，則server.address屬性將為127.0.0.1。如果開發和生產配置文件未啟用，則該屬性的值將為192.168.1.100。如果應用程序上下文啟動時沒有顯式激活，默認配置文件將被激活。所以在這個YAML中，我們為security.user.password設置一個僅在“默認”配置文件中可用的值： ``` server: port: 8000 --- spring: profiles: default security: user: password: weak ``` 使用“spring.profiles”元素指定的Spring profiles 以選擇使用`！`?字符。如果為單個文檔指定了否定和非否定的配置文件，則至少有一個非否定配置文件必須匹配，沒有否定配置文件可能匹配。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2464-yaml的缺點)24.6.4 YAML的缺點 YAML文件無法通過@PropertySource注解加載。因此，在需要以這種方式加載值的情況下，需要使用properties文件。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2465-合并yaml列表)24.6.5 合并YAML列表 [如上所述](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-loading-yaml)，任何YAML內容最終都會轉換為屬性。當通過配置文件覆蓋“列表”屬性時，該過程可能比較直觀。例如，假設名稱和描述屬性默認為空的MyPojo對象。讓我們從FooProperties中公開MyPojo的列表： ``` @ConfigurationProperties("foo") public class FooProperties { private final List<MyPojo> list = new ArrayList<>(); public List<MyPojo> getList() { return this.list; } } ``` 類比以下配置： ``` foo: list: - name: my name description: my description --- spring: profiles: dev foo: list: - name: my another name ``` 如果dev配置沒有激活，FooProperties.list將包含一個如上定義的MyPojo條目。如果啟用了配置文件，列表仍將包含一個條目（名稱為“my another name”，description=null）。此配置不會將第二個MyPojo實例添加到列表中，并且不會將項目合并。當在多個配置文件中指定集合時，使用具有最高優先級的集合（并且僅使用該配置文件）： ``` foo: list: - name: my name description: my description - name: another name description: another description --- spring: profiles: dev foo: list: - name: my another name ``` 在上面的示例中，考慮到dev配置文件處于激活狀態，FooProperties.list將包含一個MyPojo條目（名稱為“my another name”和description=null）。 ### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#247-類型安全的配置屬性)24.7 類型安全的配置屬性使用@Value(“${property}”)注釋來注入配置屬性有時可能很麻煩，特別是如果您正在使用多個層次結構的屬性或數據時。 Spring Boot提供了一種處理屬性的替代方法，允許強類型Bean管理并驗證應用程序的配置。 ``` package com.example; import java.net.InetAddress; import java.util.ArrayList; import java.util.Collections; import java.util.List; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties("foo") public class FooProperties { private boolean enabled; private InetAddress remoteAddress; private final Security security = new Security(); public boolean isEnabled() { ... } public void setEnabled(boolean enabled) { ... } public InetAddress getRemoteAddress() { ... } public void setRemoteAddress(InetAddress remoteAddress) { ... } public Security getSecurity() { ... } public static class Security { private String username; private String password; private List<String> roles = new ArrayList<>(Collections.singleton("USER")); public String getUsername() { ... } public void setUsername(String username) { ... } public String getPassword() { ... } public void setPassword(String password) { ... } public List<String> getRoles() { ... } public void setRoles(List<String> roles) { ... } } } ``` 上述POJO定義了以下屬性： * foo.enabled，默認為false * foo.remote-address，具有可以從String強轉的類型 * foo.security.username，具有內置的“安全性(security)”，其名稱由屬性名稱決定。特別是返回類型并沒有被使用，可能是SecurityProperties * foo.security.password * foo.security.roles，一個String集合 Getters和setter方法通常是必須要有的，因為綁定是通過標準的Java Beans屬性描述符，就像在Spring MVC中一樣。在某些情況下可能會省略setter方法： * Map 只要它們被初始化，需要一個getter，但不一定是一個setter，因為它們可以被binder修改。 * 集合和數組可以通過索引（通常使用YAML）或使用單個逗號分隔值（Properties中）來訪問。在后一種情況下，setter方法是強制性的。我們建議總是為這樣的類型添加一個設置器。如果您初始化集合，請確保它不是不可變的（如上例所示） * 如果已初始化嵌套POJO屬性（如上例中的Security字段），則不需要setter方法。如果您希望binder使用其默認構造函數即時創建實例，則需要一個setter。有些人使用Project Lombok自動添加getter和setter。確保Lombok不會為這種類型生成任何特定的構造函數，因為構造函將被容器自動用于實例化對象。 > 另請參閱[@Value和@ConfigurationProperties之間的不同](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-vs-value)。您還需要列出在`@EnableConfigurationProperties`注解中注冊的屬性類： ``` @Configuration @EnableConfigurationProperties(FooProperties.class) public class MyConfiguration { } ``` > 當`@ConfigurationProperties`?bean以這種方式注冊時，該bean將具有常規名稱：`<prefix> - <fqn>`，其中<prefix>是@ConfigurationProperties注解中指定的環境密鑰前綴，<fqn>是bean的全名(fully qualified name)。如果注解不提供任何前綴，則僅使用該bean的全名。上面示例中的bean名稱將是foo-com.example.FooProperties。即使上述配置將為FooProperties創建一個常規bean，我們建議@ConfigurationProperties僅處理環境，特別是不從上下文中注入其他bean。話雖如此，@EnableConfigurationProperties注釋也會自動應用于您的項目，以便使用@ConfigurationProperties注釋的任何現有的bean都將從環境配置。您可以通過確保FooProperties已經是一個bean來快速上面的MyConfiguration ``` @Component @ConfigurationProperties(prefix="foo") public class FooProperties { // ... see above } ``` 這種配置方式與SpringApplication外部的YAML配置相當： ``` # application.yml foo: remote-address: 192.168.1.1 security: username: foo roles: - USER - ADMIN # additional configuration as required ``` 要使用@ConfigurationProperties bean，您可以像其他任何bean一樣注入它們。 ``` @Service public class MyService { private final FooProperties properties; @Autowired public MyService(FooProperties properties) { this.properties = properties; } //... @PostConstruct public void openConnection() { Server server = new Server(this.properties.getRemoteAddress()); // ... } } ``` > 使用@ConfigurationProperties還可以生成IDE可以為自己的密鑰提供自動完成的元數據文件，有關詳細信息，請參見[附錄B，配置元數據附錄](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#configuration-metadata)。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2471第三方配置)24.7.1第三方配置除了使用@ConfigurationProperties來注解類，還可以在public @Bean方法中使用它。當您希望將屬性綁定到不受控制的第三方組件時，這可能特別有用。 ``` @ConfigurationProperties(prefix = "bar") @Bean public BarComponent barComponent() { ... } ``` 使用 bar 前綴定義的任何屬性將以與上述FooProperties示例類似的方式映射到該BarComponent bean。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2472-寬松的綁定)24.7.2 寬松的綁定 Spring Boot使用一些寬松的規則將環境屬性綁定到@ConfigurationProperties bean，因此不需要在Environment屬性名稱和bean屬性名稱之間進行完全匹配。常用的例子是這樣有用的：虛分離（例如上下文路徑綁定到contextPath）和大寫（例如PORT綁定到端口）環境屬性。例如，給定以下@ConfigurationProperties類： ``` @ConfigurationProperties(prefix="person") public class OwnerProperties { private String firstName; public String getFirstName() { return this.firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } } ``` 可以使用以下屬性名稱：表格 24.1\. relaxed binding | Property | Note | | --- | --- | | person.firstName | 標準駱峰命名法。 | | person.first-name | 虛線符號，推薦用于.properties和.yml文件。 | | person.first_name | 下劃線符號，用于.properties和.yml文件的替代格式。 | | PERSON_FIRST_NAME | 大寫格式推薦使用系統環境變量時。 | #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2473屬性轉換)24.7.3屬性轉換當Spring綁定到@ConfigurationProperties bean時，Spring將嘗試將外部應用程序屬性強制為正確的類型。如果需要自定義類型轉換，您可以提供ConversionService bean（使用bean id conversionService）或自定義屬性編輯器（通過CustomEditorConfigurer bean）或自定義轉換器（使用注釋為@ConfigurationPropertiesBinding的bean定義）。 > 由于在應用程序生命周期期間非常早請求此Bean，請確保限制ConversionService正在使用的依賴關系。通常，您需要的任何依賴關系可能無法在創建時完全初始化。如果配置密鑰強制不需要，只需依賴使用@ConfigurationPropertiesBinding限定的自定義轉換器，就可以重命名自定義ConversionService。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2474-configurationproperties驗證)24.7.4 @ConfigurationProperties驗證當Spring的@Validated注釋解時，Spring Boot將嘗試驗證@ConfigurationProperties類。您可以直接在配置類上使用JSR-303 javax.validation約束注釋。只需確保您的類路徑中符合JSR-303實現，然后在您的字段中添加約束注釋： ``` @ConfigurationProperties(prefix="foo") @Validated public class FooProperties { @NotNull private InetAddress remoteAddress; // ... getters and setters } ``` 為了驗證嵌套屬性的值，您必須將關聯字段注釋為@Valid以觸發其驗證。例如，基于上述FooProperties示例： ``` @ConfigurationProperties(prefix="connection") @Validated public class FooProperties { @NotNull private InetAddress remoteAddress; @Valid private final Security security = new Security(); // ... getters and setters public static class Security { @NotEmpty public String username; // ... getters and setters } } ``` 您還可以通過創建名為configurationPropertiesValidator的bean定義來添加自定義的Spring Validator。 @Bean方法應聲明為static。配置屬性驗證器在應用程序的生命周期早期創建，并聲明@Bean方法，因為static允許創建bean，而無需實例化@Configuration類。這避免了早期實例化可能引起的任何問題。這里有一個[屬性驗證的例子](https://github.com/spring-projects/spring-boot/tree/v1.5.2.RELEASE/spring-boot-samples/spring-boot-sample-property-validation)，所以你可以看到如何設置。 > `spring-boot-actuator`模塊包括一個暴露所有@ConfigurationProperties bean的端點。只需將您的Web瀏覽器指向/configprops 或使用等效的JMX端點。請參閱[生產就緒功能](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#production-ready-endpoints)?細節。 #### [](file:///C:/Users/geekidentity/AppData/Local/Youdao/YNote/markdown/index.html#2475-configurationproperties-對比-value)24.7.5 @ConfigurationProperties 對比 @Value @Value是核心容器功能，它不提供與類型安全配置屬性相同的功能。下表總結了@ConfigurationProperties和@Value支持的功能： | 功能 | @ConfigurationProperties | @Value | | --- | --- | --- | | Relaxed binding | Yes | No | | Meta-data support | Yes | No | | SpEL evaluation | No | Yes | 如果您為自己的組件定義了一組配置密鑰，我們建議您將其分組到使用@ConfigurationProperties注釋的POJO中。還請注意，由于@Value不支持寬松的綁定，如果您需要使用環境變量提供值，那么它不是一個很好的選擇。最后，當您可以在@Value中編寫一個Spel表達式時，這些表達式不會從[應用程序屬性文件](http://docs.spring.io/spring-boot/docs/1.5.2.RELEASE/reference/htmlsingle/#boot-features-external-config-application-property-files)中處理。