SpringBoot 配置提示功能(超詳細(xì))

更新時(shí)間：2019年10月31日 09:35:01 作者：逸飛兮

這篇文章主要介紹了SpringBoot 配置提示功能，本文給大家介紹的超詳細(xì)，通過實(shí)例代碼給大家介紹的非常詳細(xì)，具有一定的參考借鑒價(jià)值,需要的朋友可以參考下

目的

配置自動(dòng)提示的輔助功能可以讓配置寫起來更快，準(zhǔn)確率大大提高。

springboot jar 包含提供所有支持的配置屬性細(xì)節(jié)的元數(shù)據(jù)文件。文件的目的是為了讓 IDE 開發(fā)者在用戶使用 application.properties 或 application.yml 文件時(shí)提供上下文幫助和代碼補(bǔ)全。
大多數(shù)元數(shù)據(jù)文件是在編譯時(shí)通過處理用 @ConfigurationProperties 注釋的所有項(xiàng)自動(dòng)生成的。也可以手動(dòng)編寫部分元數(shù)據(jù)。

版本

參考 SpringBoot 2.2.0.RELEASE 文檔

文件

jar包中的 META-INF/spring-configuration-metadata.json （自動(dòng)生成）或 META-INF/additional-spring-configuration-metadata.json （手動(dòng)添加）

實(shí)戰(zhàn)

<!-- 引入相關(guān)依賴 -->
<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;
 //注意：使用的時(shí)候必須要有g(shù)etter/setter，否則不會(huì)自動(dòng)生成該屬性對應(yīng)的提示
 //此處因?yàn)槠蚴÷?getter/setter
}
@Configuration
@ConfigurationProperties("map.test")
public class MapTestConfig {
 /** 測試Map類型數(shù)據(jù)的提示 */
 private Map<String, Object> data;
 //注意：使用的時(shí)候必須要有g(shù)etter/setter，否則不會(huì)自動(dòng)生成該屬性對應(yīng)的提示
 //此處因?yàn)槠蚴÷?getter/setter
}

中文注釋會(huì)亂碼，以上故意用中文注釋的地方，會(huì)在下面文件中指定對應(yīng)的描述，看是否會(huì)覆蓋。

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",
 "sourceType": "com.lw.metadata.config.FileUploadConfig"
 },
 {
 "name": "map.test",
 "type": "com.lw.metadata.config.MapTestConfig",
 "sourceType": "com.lw.metadata.config.MapTestConfig"
 }
 ],
 "properties": [
 {
 "name": "file.upload.max-size",
 "type": "java.lang.String",
 "description": "Maximum number of bytes per file",
 "sourceType": "com.lw.metadata.config.FileUploadConfig",
 "defaultValue": "1024M"
 },
 {
 "name": "file.upload.reject-suffix",
 "type": "java.lang.String",
 "description": "The file suffix is not allowed.",
 "sourceType": "com.lw.metadata.config.FileUploadConfig",
 "defaultValue": "exe,jar"
 },
 {
 "name": "map.test.data",
 "type": "java.util.Map<java.lang.String,java.lang.Object>",
 "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."
 }
 ]
 }
 ]
}

效果

由此可以看到以下現(xiàn)象：

代碼中的默認(rèn)值會(huì)自動(dòng)生成到提示文件中，如：FileUploadConfig#maxSize
代碼中的注釋會(huì)自動(dòng)生成到提示文件中，如：FileUploadConfig#maxSize
additional-spring-configuration-metadata.json 文件中存在的提示會(huì)覆蓋自動(dòng)生成的對應(yīng)屬性，若自動(dòng)生成的沒有此屬性則自動(dòng)增加。

手動(dòng)寫提示文件

示例

{
 "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",
   "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
  },
  {
   "name": "server.address",
   "type": "java.net.InetAddress",
   "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
  },
  {
    "name": "spring.jpa.hibernate.ddl-auto",
    "type": "java.lang.String",
    "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

分組，將配置類分組。

可以按照文件來分組，即：將同一個(gè)配置文件的所有屬性放在同一個(gè)組

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

properties

提示主體，必須

屬性	類型	是否必須	用途
name	String	Y	屬性的完整名稱。名稱采用小寫句點(diǎn)分隔格式，如：server.address
type	String	N	屬性數(shù)據(jù)類型的完整簽名（如：java.lang.String）或完整的泛型類型（如：java.util.Map<java.util.String,acme.Myenum>）。此屬性提示用戶輸入值得類型。原生類型在此處使用其包裝類型（如：boolean使用java.lang.Boolean）。
description	String	N	分組的簡短描述。
sourceType	String	N	提供分組來源的類名。
defaultValue	Object	N	默認(rèn)值。當(dāng)屬性為指定時(shí)使用。
deprecation	Deprecation	N	指定屬性是否已棄用。

deprecation屬性如下：

屬性	類型	是否必須	用途
level	String	N	棄用級別，可以是 warning（默認(rèn)值）或 error。warning：屬性應(yīng)該仍然可以使用；error：屬性不保證可以使用
reason	String	N	屬性棄用的簡短原因。
replacement	String	N	替換此棄用屬性的新屬性全名?？蔀榭?/td>

注意：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 中刪除，元數(shù)據(jù)中的自動(dòng)棄用提示也會(huì)消失。如果要保留提示，則添加具有 error 棄用級別的手動(dòng)元數(shù)據(jù)可以確保用戶仍然了解該屬性。在提供替代品時(shí)，這樣做特別有用。

hints

輔助提示，非必須

屬性	類型	是否必須	用途
name	String	Y	提示關(guān)聯(lián)的屬性的完整名稱。名稱是小寫句點(diǎn)分隔格式（如：spring.mvc.servlet.path），如果屬性關(guān)聯(lián)map類型（如：system.contexts），提示可以關(guān)聯(lián)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內(nèi)每一對 key-value 的提示。

.keys 和 .values 前綴必須分別關(guān)聯(lián) Map 的 keys 和 values。

providers 屬性如下：

屬性	類型	是否必須	用途
name	String	N	用于為提示所引用的元素提供其他內(nèi)容幫助的 provider 的名稱。
parameters	JSON object	N	provider 所支持的任何其他參數(shù)（有關(guān)詳細(xì)信息，請查看 provider 的文檔）。

ValueProvider

一般用不到，建議跳過

下表總結(jié)了支持的 providers 列表：

屬性	描述
any	允許提供任何附加值。
class-reference	自動(dòng)完成項(xiàng)目中可用的類。通常由目標(biāo)參數(shù)指定的基類約束。
handle-as	處理屬性，就像它是由必須的 target 參數(shù)定義的類型定義的一樣。
logger-name	自動(dòng)完成有效的記錄器名稱和記錄器組。通常，當(dāng)前項(xiàng)目中可用的包和類名可以自動(dòng)完成，也可以定義組。
spring-bean-reference	自動(dòng)完成當(dāng)前項(xiàng)目中可用的bean名稱。通常由 target 參數(shù)指定的基類約束。
spring-profile-name	自動(dòng)完成項(xiàng)目中可用的 spring 配置文件名稱。

any

符合屬性類型的所有值。

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

提供以下參數(shù)：

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

handle-as

允許您將屬性的類型替換為更高級的類型。

這通常在屬性具有 java.lang.String 類型時(shí)發(fā)生，因?yàn)槟幌Ｍ渲妙愐蕾囉诓辉陬惵窂缴系念悺?/p>

參數(shù)	類型	默認(rèn)值		描述
target	String（Class）	無	Y	為屬性考慮的類型的完全限定名。

可用的值如下：

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

java.nio.charset.Charset：支持自動(dòng)完成字符集/編碼值（如 utf-8）

java.util.Locale：自動(dòng)完成區(qū)域設(shè)置（如：en_US)

org.springframework.util.MimeType：支持自動(dòng)完成 content-type 值（如：text/plain）

org.springframework.core.io.Resource：支持自動(dòng)完成spring的資源抽象以引用文件系統(tǒng)或類路徑上的文件（如：

classpath:/sample.properties）

注意：如果要提供多個(gè)值，用 Collection 或數(shù)組類型

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

logger-name

logger-name provider 自動(dòng)完成有效的記錄器名稱和記錄器組。通常，當(dāng)前項(xiàng)目中可用的包和類名可以自動(dòng)完成。如果組已啟用（默認(rèn)），并且配置中標(biāo)識了自定義記錄器組，則應(yīng)提供該組的自動(dòng)完成。

支持以下參數(shù)：

參數(shù)	類型	默認(rèn)值	描述
group	boolean	true	指定是否應(yīng)考慮已知組。

由于記錄器名稱可以是任意名稱，此 provider 應(yīng)允許任何值，但可以突出顯示項(xiàng)目的類路徑中不可用的有效包和類名。

以下是 logging.level 屬性。keys 是 logger 名，values 關(guān)聯(lián)標(biāo)準(zhǔn)的 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 自動(dòng)完成在當(dāng)前項(xiàng)目的配置中定義的bean。支持以下參數(shù)：

參數(shù)	類型	默認(rèn)值	描述
target	String（Class）	無	應(yīng)該分配給候選對象的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 自動(dòng)完成在當(dāng)前項(xiàng)目的配置中定義的spring配置文件。

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

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

可重復(fù)的元數(shù)據(jù)項(xiàng)

具有相同“property”和“group”名稱的對象可以在元數(shù)據(jù)文件中多次出現(xiàn)。例如，可以將兩個(gè)單獨(dú)的類綁定到同一前綴，每個(gè)類都有可能重疊的屬性名。雖然多次出現(xiàn)在元數(shù)據(jù)中的相同名稱不應(yīng)是常見的，但元數(shù)據(jù)的使用者應(yīng)注意確保他們支持該名稱。

自動(dòng)生成提示文件

通過使用 spring-boot-configuration-processor jar，您可以從用 @ConfigurationProperties 注釋的類中輕松生成自己的配置元數(shù)據(jù)文件。 jar包含一個(gè)java注釋處理器，在編譯項(xiàng)目時(shí)調(diào)用它。用此處理器，需要引入 spring-boot-configuration-processor 依賴。

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

處理器獲取用@configurationproperties注釋的類和方法。配置類中字段值的 javadoc 用于填充 description 屬性。

注意：僅僅只應(yīng)將簡單文本與@configurationproperties字段javadoc一起使用，因?yàn)樵趯⑺鼈兲砑拥絡(luò)son之前不會(huì)對它們進(jìn)行處理。

如果類有一個(gè)“至少一個(gè)參數(shù)”的構(gòu)造函數(shù)，則為每個(gè)構(gòu)造函數(shù)參數(shù)創(chuàng)建一個(gè)屬性。否則，通過標(biāo)準(zhǔn)getter和setter來發(fā)現(xiàn)屬性，這些getter和setter對集合類型進(jìn)行了特殊處理（即使只有g(shù)etter存在，也會(huì)檢測到）。

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

注解處理器無法自動(dòng)檢測 Enum 和 Collections 的默認(rèn)值。在集合或枚舉屬性具有非空默認(rèn)值的情況下，應(yīng)提供手動(dòng)元數(shù)據(jù)。

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

為了提示上述屬性的默認(rèn)值，應(yīng)該手動(dòng)添加如下元數(shù)據(jù)：

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

注意：如果在項(xiàng)目中使用 AspectJ，則需要確保注解處理器只運(yùn)行一次。使用 Maven 時(shí)，可以顯式地配置 maven-apt-plugin插件，并僅在那里向注解處理器添加依賴項(xiàng)。還可以讓 AspectJ 插件運(yùn)行于所有的處理且在 maven-compiler-plugin 的 configuration 中禁用注解處理，如下：

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

綁定屬性

注解處理器自動(dòng)將內(nèi)部類視為嵌套屬性。

@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 屬性的元數(shù)據(jù)信息。可以在字段上使用@NestedconfigurationProperty 注解來指示應(yīng)將常規(guī)（非內(nèi)部）類視為嵌套類。

注意：這對集合和映射沒有影響，因?yàn)檫@些類型是自動(dòng)標(biāo)識的，并且為每個(gè)類型生成一個(gè)元數(shù)據(jù)屬性。

添加額外的元數(shù)據(jù)

Spring Boot 的配置文件處理非常靈活，通常情況下，可能存在不綁定到 @ConfigurationProperties bean的屬性。您還可能需要調(diào)整現(xiàn)有key的某些屬性，為了支持這種情況并讓您提供自定義的“提示”，注解處理器會(huì)自動(dòng)將 META-INF/additional-spring-configuration-metadata.json 中的提示項(xiàng)合并到主要元數(shù)據(jù)文件（spring-configuration-metadata.json）中。

如果引用已自動(dòng)檢測到的屬性，則將覆蓋描述、默認(rèn)值和棄用信息（如果指定）。如果當(dāng)前模塊中沒有標(biāo)識手動(dòng)屬性中的聲明，則將其作為新屬性添加。

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

總結(jié)

以上所述是小編給大家介紹的SpringBoot 配置提示功能,希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會(huì)及時(shí)回復(fù)大家的。在此也非常感謝大家對腳本之家網(wǎng)站的支持！
如果你覺得本文對你有幫助，歡迎轉(zhuǎn)載，煩請注明出處，謝謝！

您可能感興趣的文章: