目的

配置自動提示的輔助功能可以讓配置寫起來更快，準確率大大提高。

springboot jar 包含提供所有支援的配置屬性細節的元資料檔案。檔案的目的是為了讓 IDE 開發者在使用者使用 application.properties 或 application.yml 檔案時提供上下文幫助和程式碼補全。
大多數元資料檔案是在編譯時通過處理用 @ConfigurationProperties 註釋的所有項自動生成的。也可以手動編寫部分元資料。

版本

參考 SpringBoot 2.2.0.RELEASE 文件

檔案

jar包中的 META-INF/spring-configuration-metadata.json （自動生成）或 META-INF/additional-spring-configuration-metadata.json （手動新增）

實戰

<!-- 引入相關依賴 -->
<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-configuration-processor</artifactId>
 <optional>true</optional>
</dependency>
@Configuration
@ConfigurationProperties(prefix = "file.upload")
public class FileUploadConfig {
 /** Maximum number of bytes per file */
 private String maxSize = "1024M";

 /** 不允許的檔案字尾 */
 private String rejectSuffix;
 //注意：使用的時候必須要有getter/setter，否則不會自動生成該屬性對應的提示
 //此處因為篇幅原因省略 getter/setter
}
@Configuration
@ConfigurationProperties("map.test")
public class MapTestConfig {
 /** 測試Map型別資料的提示 */
 private Map<String,Object> data;
 //注意：使用的時候必須要有getter/setter，否則不會自動生成該屬性對應的提示
 //此處因為篇幅原因省略 getter/setter
}

中文註釋會亂碼，以上故意用中文註釋的地方，會在下面檔案中指定對應的描述，看是否會覆蓋。

additional-spring-configuration-metadata.json

{
 "properties": [
 {
 "name": "file.upload.reject-suffix","type": "java.lang.String","defaultValue": "exe,jar","description": "The file suffix is not allowed.","sourceType": "com.lw.metadata.config.FileUploadConfig"
 },{
 "name": "map.test.data","type": "java.util.Map","description": "Tips for testing Map type data.","sourceType": "com.lw.metadata.config.MapTestConfig"
 }
 ],"hints": [
 {
 "name": "map.test.data.keys","values": [
 {
  "value": "name","description": "The name of the person."
 },{
  "value": "sex","description": "The sex of the person."
 }
 ]
 }
 ]
}

maven compile 之後，生成的 additional-spring-configuration-metadata.json 與原始碼中的一樣，生成的 spring-configuration-metadata.json 如下：

{
 "groups": [
 {
 "name": "file.upload","type": "com.lw.metadata.config.FileUploadConfig",{
 "name": "map.test","type": "com.lw.metadata.config.MapTestConfig","properties": [
 {
 "name": "file.upload.max-size","description": "Maximum number of bytes per file","sourceType": "com.lw.metadata.config.FileUploadConfig","defaultValue": "1024M"
 },{
 "name": "file.upload.reject-suffix",jar"
 },"type": "java.util.Map<java.lang.String,java.lang.Object>","description": "The sex of the person."
 }
 ]
 }
 ]
}

效果

由此可以看到以下現象：

• 程式碼中的預設值會自動生成到提示檔案中，如：FileUploadConfig#maxSize
  
• 程式碼中的註釋會自動生成到提示檔案中，如：FileUploadConfig#maxSize
  
• additional-spring-configuration-metadata.json 檔案中存在的提示會覆蓋自動生成的對應屬性，若自動生成的沒有此屬性則自動增加。

手動寫提示檔案

示例

{
 "groups": [
  {
   "name": "server","type": "org.springframework.boot.autoconfigure.web.ServerProperties","sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
  },{
   "name": "spring.jpa.hibernate","type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate","sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties","sourceMethod": "getHibernate()"
  }
 ],"properties": [
  {
   "name": "server.port","type": "java.lang.Integer",{
   "name": "server.address","type": "java.net.InetAddress",{
    "name": "spring.jpa.hibernate.ddl-auto","description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.","sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
  }
 ],"hints": [
  {
   "name": "spring.jpa.hibernate.ddl-auto","values": [
    {
     "value": "none","description": "Disable DDL handling."
    },{
     "value": "validate","description": "Validate the schema,make no changes to the database."
    },{
     "value": "update","description": "Update the schema if necessary."
    },{
     "value": "create","description": "Create the schema and destroy previous data."
    },{
     "value": "create-drop","description": "Create and then destroy the schema at the end of the session."
    }
   ]
  }
 ]
}

groups

分組，將配置類分組。

可以按照檔案來分組，即：將同一個配置檔案的所有屬性放在同一個組

屬性	型別	是否必須	用途
name	String	Y	分組的完整名稱
type	String	N	分組資料型別的類名（如：使用@ConfigurationProperties註釋的完整類名、使用@Bean註釋的方法返回型別）
description	String	N	分組的簡短描述。
sourceType	String	N	提供分組來源的類名。
sourceMethod	String	N	提供分組的方法，包含括號和引數型別。

properties

提示主體，必須

屬性	型別	是否必須	用途
name	String	Y	屬性的完整名稱。名稱採用小寫句點分隔格式，如：server.address
type	String	N	屬性資料型別的完整簽名（如：java.lang.String）或完整的泛型型別（如：java.util.Map<java.util.String,acme.Myenum>）。此屬性提示使用者輸入值得型別。原生型別在此處使用其包裝型別（如：boolean使用java.lang.Boolean）。
description	String	N	分組的簡短描述。
sourceType	String	N	提供分組來源的類名。
defaultValue	Object	N	預設值。當屬性為指定時使用。
deprecation	Deprecation	N	指定屬性是否已棄用。

deprecation屬性如下：

屬性	型別	是否必須	用途
level	String	N	棄用級別，可以是warning（預設值） 或error。warning：屬性應該仍然可以使用；error：屬性不保證可以使用
reason	String	N	屬性棄用的簡短原因。
replacement	String	N	替換此棄用屬性的新屬性全名。可為空

注意：Spring Boot 1.3 版本之前，是使用 boolean 型別的 deprecated。

以下示例來源於官方文件，展示瞭如何處理這種場景：

@ConfigurationProperties("app.acme")
public class AcmeProperties {

 private String name;

 public String getName() { ... }

 public void setName(String name) { ... }

 @DeprecatedConfigurationProperty(replacement = "app.acme.name")
 @Deprecated
 public String getTarget() {
  return getName();
 }

 @Deprecated
 public void setTarget(String target) {
  setName(target);
 }
}

一旦 getTarget 和 setTarget 方法從公共 API 中刪除，元資料中的自動棄用提示也會消失。 如果要保留提示，則新增具有 error 棄用級別的手動元資料可以確保使用者仍然瞭解該屬性。在提供替代品時，這樣做特別有用。

hints

輔助提示，非必須

屬性	型別	是否必須	用途
name	String	Y	提示關聯的屬性的完整名稱。名稱是小寫句點分隔格式（如：spring.mvc.servlet.path），如果屬性關聯map型別（如：system.contexts），提示可以關聯map的鍵（system.contexts.keys）或者值（system.contexts.values）。
values	ValueHint[]	N	有效值集合。（下表詳述）
providers	ValueProvider[]	N	提供者集合。（下表詳述）

values 屬性如下：

@ConfigurationProperties("sample")
public class SampleProperties {

 private Map<String,Integer> contexts;
 // getters and setters
}
{"hints": [
 {
  "name": "sample.contexts.keys","values": [
   {
    "value": "sample1"
   },{
    "value": "sample2"
   }
  ]
 }
]}

提示是對Map內每一對 key-value 的提示。

.keys 和 .values 字首必須分別關聯 Map 的 keys 和 values。

providers 屬性如下：

屬性	型別	是否必須	用途
name	String	N	用於為提示所引用的元素提供其他內容幫助的 provider 的名稱。
parameters	JSON object	provider 所支援的任何其他引數（有關詳細資訊，請檢視 provider 的文件）。

ValueProvider

一般用不到，建議跳過

下表總結了支援的 providers 列表：

屬性	描述
any	允許提供任何附加值。
class-reference	自動完成專案中可用的類。通常由目標引數指定的基類約束。
handle-as	處理屬性，就像它是由必須的 target 引數定義的型別定義的一樣。
logger-name	自動完成有效的記錄器名稱和記錄器組。通常，當前專案中可用的包和類名可以自動完成，也可以定義組。
spring-bean-reference	自動完成當前專案中可用的bean名稱。通常由 target 引數指定的基類約束。
spring-profile-name	自動完成專案中可用的 spring 配置檔名稱。

any

符合屬性型別的所有值。

{"hints": [
 {
  "name": "system.state","values": [
   {
    "value": "on"
   },{
    "value": "off"
   }
  ],"providers": [
   {
    "name": "any"
   }
  ]
 }
]}
class-reference

提供以下引數：

 {"hints": [
 {
  "name": "server.servlet.jsp.class-name","providers": [
   {
    "name": "class-reference","parameters": {
     "target": "javax.servlet.http.HttpServlet"
    }
   }
  ]
 }
]}

handle-as

允許您將屬性的型別替換為更高階的型別。

這通常在屬性具有 java.lang.String 型別時發生，因為您不希望配置類依賴於不在類路徑上的類。

引數

預設值		描述
target	String（Class）	無	Y	為屬性考慮的型別的完全限定名。

可用的值如下：

任何 java.lang.Enum： 列出屬性的可能值。

java.nio.charset.Charset： 支援自動完成字符集/編碼值（如 utf-8）

java.util.Locale：自動完成區域設定（如：en_US)

org.springframework.util.MimeType：支援自動完成 content-type 值（如：text/plain）

org.springframework.core.io.Resource： 支援自動完成spring的資源抽象以引用檔案系統或類路徑上的檔案 （如：

classpath:/sample.properties）

注意：如果要提供多個值，用 Collection 或 陣列型別

{"hints": [
 {
  "name": "spring.liquibase.change-log","providers": [
   {
    "name": "handle-as","parameters": {
     "target": "org.springframework.core.io.Resource"
    }
   }
  ]
 }
]}

logger-name

logger-name provider 自動完成有效的記錄器名稱和記錄器組。 通常，當前專案中可用的包和類名可以自動完成。 如果組已啟用（預設），並且配置中標識了自定義記錄器組，則應提供該組的自動完成。

支援以下引數：

引數	型別	預設值	描述
group	boolean	true	指定是否應考慮已知組。

由於記錄器名稱可以是任意名稱，此 provider 應允許任何值，但可以突出顯示專案的類路徑中不可用的有效包和類名。

以下是 logging.level 屬性。keys 是 logger 名，values 關聯標準的 log levels 或 自定義的 level，

{"hints": [
 {
  "name": "logging.level.keys","values": [
   {
    "value": "root","description": "Root logger used to assign the default logging level."
   },{
    "value": "sql","description": "SQL logging group including Hibernate SQL logger."
   },{
    "value": "web","description": "Web logging group including codecs."
   }
  ],"providers": [
   {
    "name": "logger-name"
   }
  ]
 },{
  "name": "logging.level.values","values": [
   {
    "value": "trace"
   },{
    "value": "debug"
   },{
    "value": "info"
   },{
    "value": "warn"
   },{
    "value": "error"
   },{
    "value": "fatal"
   },{
    "value": "off"
   }

  ],"providers": [
   {
    "name": "any"
   }
  ]
 }
]}

spring-bean-reference

此 provider 自動完成在當前專案的配置中定義的bean。 支援以下引數：

引數	型別	預設值	描述
target	String（Class）	無	應該分配給候選物件的bean類的完全限定名。通常用於篩選非候選bean。

以下示例表示：spring.jmx.server 屬性定義了使用 MBeanServer

{"hints": [
 {
  "name": "spring.jmx.server","providers": [
   {
    "name": "spring-bean-reference","parameters": {
     "target": "javax.management.MBeanServer"
    }
   }
  ]
 }
]}

spring-profile-name

此 provider 自動完成在當前專案的配置中定義的spring配置檔案。

以下示例表示：spring.profiles.active屬性可啟用的配置檔名稱。

{"hints": [
 {
  "name": "spring.profiles.active","providers": [
   {
    "name": "spring-profile-name"
   }
  ]
 }
]}

可重複的元資料項

具有相同“property”和“group”名稱的物件可以在元資料檔案中多次出現。 例如，可以將兩個單獨的類繫結到同一字首，每個類都有可能重疊的屬性名。 雖然多次出現在元資料中的相同名稱不應是常見的，但元資料的使用者應注意確保他們支援該名稱。

自動生成提示檔案

通過使用 spring-boot-configuration-processor jar，您可以從用 @ConfigurationProperties 註釋的類中輕鬆生成自己的配置元資料檔案。 jar包含一個java註釋處理器，在編譯專案時呼叫它。 用此處理器，需要引入 spring-boot-configuration-processor 依賴。

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-configuration-processor</artifactId>
 <optional>true</optional>
</dependency>

處理器獲取用@configurationproperties註釋的類和方法。 配置類中欄位值的 javadoc 用於填充 description 屬性。

注意：僅僅只應將簡單文字與@configurationproperties欄位javadoc一起使用，因為在將它們新增到json之前不會對它們進行處理。

如果類有一個“至少一個引數”的建構函式，則為每個建構函式引數建立一個屬性。 否則，通過標準getter和setter來發現屬性，這些getter和setter對集合型別進行了特殊處理（即使只有getter存在，也會檢測到）。

註解處理器還支援使用@data、@getter和@setter 的 lombok 註解。

註解處理器無法自動檢測 Enum 和 Collections 的預設值。在集合或列舉屬性具有非空預設值的情況下，應提供手動元資料。

@ConfigurationProperties(prefix="acme.messaging")
public class MessagingProperties {

 private List<String> addresses = new ArrayList<>(Arrays.asList("a","b")) ;

 private ContainerType = ContainerType.SIMPLE;

 // ... getter and setters

 public enum ContainerType {
  SIMPLE,DIRECT
 }
}

為了提示上述屬性的預設值，應該手動新增如下元資料：

{"properties": [
 {
  "name": "acme.messaging.addresses","defaultValue": ["a","b"]
 },{
  "name": "acme.messaging.container-type","defaultValue": "simple"
 }
]}

注意： 如果在專案中使用 AspectJ，則需要確保註解處理器只執行一次。 使用 Maven 時， 可以顯式地配置 maven-apt-plugin外掛，並僅在那裡向註解處理器新增依賴項。 還可以讓 AspectJ 外掛運行於所有的處理且在 maven-compiler-plugin 的 configuration 中禁用註解處理，如下：

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-compiler-plugin</artifactId>
 <configuration>
  <proc>none</proc>
 </configuration>
</plugin>

繫結屬性

註解處理器自動將內部類視為巢狀屬性。

@ConfigurationProperties(prefix="server")
public class ServerProperties {
 private String name;
 private Host host;
 // ... getter and setters
 public static class Host {
  private String ip;
  private int port;
  // ... getter and setters
 }
}

上述示例生成 server.name、server.host.ip 和 server.host.port 屬性的元資料資訊。 可以在欄位上使用@NestedconfigurationProperty 註解來指示應將常規（非內部）類視為巢狀類。

注意： 這對集合和對映沒有影響，因為這些型別是自動標識的，並且為每個型別生成一個元資料屬性。

新增額外的元資料

Spring Boot 的配置檔案處理非常靈活，通常情況下，可能存在不繫結到 @ConfigurationProperties bean的屬性。 您還可能需要調整現有key的某些屬性，為了支援這種情況並讓您提供自定義的“提示”，註解處理器會自動將 META-INF/additional-spring-configuration-metadata.json 中的提示項合併到主要元資料檔案（spring-configuration-metadata.json）中。

如果引用已自動檢測到的屬性，則將覆蓋描述、預設值和棄用資訊（如果指定）。 如果當前模組中沒有標識手動屬性中的宣告，則將其作為新屬性新增。

additional-spring-configuration-metadata.json 檔案的格式與 spring-configuration-metadata.json 檔案一樣。 附加屬性檔案是可選的。如果沒有任何其他屬性，就不要新增檔案。

總結

以上所述是小編給大家介紹的SpringBoot 配置提示功能,希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回覆大家的。在此也非常感謝大家對我們網站的支援！
如果你覺得本文對你有幫助，歡迎轉載，煩請註明出處，謝謝！