元資料格式

配置元資料檔案位於 JAR 包中 META-INF/spring-configuration-metadata.json 路徑下。它們使用 JSON 格式，其中包含按“組”或“屬性”分類的項，按“提示”分類的附加值提示，以及按“忽略”分類的被忽略項，如下例所示

{"groups": [
	{
		"name": "server",
		"type": "org.springframework.boot.web.server.autoconfigure.ServerProperties",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "spring.jpa.hibernate",
		"type": "org.springframework.boot.jpa.autoconfigure.JpaProperties$Hibernate",
		"sourceType": "org.springframework.boot.jpa.autoconfigure.JpaProperties",
		"sourceMethod": "getHibernate()"
	}
	...
],"properties": [
	{
		"name": "server.port",
		"type": "java.lang.Integer",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "server.address",
		"type": "java.net.InetAddress",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.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.jpa.autoconfigure.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."
			}
		]
	}
	...
],"ignored": {
	"properties": [
		{
			"name": "server.ignored"
		}
		...
	]
}}

每個“屬性”是使用者指定值的配置項。例如，server.port 和 server.address 可能在您的 application.properties/application.yaml 中指定，如下所示

  • 屬性

  • YAML

server.port=9090
server.address=127.0.0.1
server:
  port: 9090
  address: 127.0.0.1

“組”是更高級別的項，它們本身不指定值，而是為屬性提供上下文分組。例如，server.port 和 server.address 屬性是 server 組的一部分。

並非每個“屬性”都必須有一個“組”。有些屬性可能獨立存在。

“提示”是用於幫助使用者配置給定屬性的附加資訊。例如，當開發人員配置 spring.jpa.hibernate.ddl-auto 屬性時，工具可以使用提示為 none、validate、update、create 和 create-drop 值提供自動補全幫助。

最後，“忽略”用於已被特意忽略的項。此部分的內容通常來自附加元資料。

組屬性

groups 陣列中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

name

字串

組的完整名稱。此屬性是強制性的。

型別

字串

組資料型別的類名。例如，如果組基於使用 @ConfigurationProperties 註解的類，則該屬性將包含該類的完全限定名。如果它基於 @Bean 方法，則它將是該方法的返回型別。如果型別未知，則可以省略該屬性。

描述

字串

可以向用戶顯示的組的簡短描述。如果沒有描述，可以省略。建議描述為簡短段落，第一行提供簡潔摘要。描述的最後一行應以句號 (.) 結尾。

sourceType

字串

提供此組的源的類名。例如，如果組基於使用 @Bean 方法且使用 @ConfigurationProperties 註解，則此屬性將包含包含該方法的 @Configuration 類的完全限定名。如果源型別未知，則可以省略該屬性。

sourceMethod

字串

提供此組的方法的完整名稱（包括括號和引數型別）（例如，使用 @ConfigurationProperties 註解的 @Bean 方法的名稱）。如果源方法未知，則可以省略。

屬性屬性

properties 陣列中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

name

字串

屬性的完整名稱。名稱採用小寫句點分隔形式（例如，server.address）。此屬性是強制性的。

型別

字串

屬性資料型別的完整簽名（例如，String），但也包括完整的泛型型別（例如 java.util.Map<java.lang.String,com.example.MyEnum>）。您可以使用此屬性來指導使用者輸入值的型別。為了一致性，原始型別透過其包裝器對應項指定（例如，boolean 變為 Boolean）。請注意，此型別可能是一個複雜型別，在繫結值時會從 String 轉換而來。如果型別未知，則可以省略。

描述

字串

可以向用戶顯示的屬性的簡短描述。如果沒有描述，可以省略。建議描述為簡短段落，第一行提供簡潔摘要。描述的最後一行應以句號 (.) 結尾。

sourceType

字串

提供此屬性的源的類名。例如，如果屬性來自使用 @ConfigurationProperties 註解的類，則此屬性將包含該類的完全限定名。如果源型別未知，則可以省略。

defaultValue

物件

預設值，如果未指定屬性，則使用此值。如果屬性型別是陣列，則可以是值的陣列。如果預設值未知，則可以省略。

deprecation

廢棄

指定屬性是否已廢棄。如果欄位未廢棄或該資訊未知，則可以省略。下表提供了有關 deprecation 屬性的更多詳細資訊。

每個 properties 元素的 deprecation 屬性中包含的 JSON 物件可以包含以下屬性

名稱 型別 目的

level

字串

廢棄級別，可以是 warning（預設值）或 error。當屬性具有 warning 廢棄級別時，它仍應在環境中繫結。但是，當它具有 error 廢棄級別時，該屬性不再受管理且未繫結。

reason

字串

屬性被廢棄的簡短原因描述。如果沒有原因，可以省略。建議描述為簡短段落，第一行提供簡潔摘要。描述的最後一行應以句號 (.) 結尾。

replacement

字串

替換此廢棄屬性的屬性的完整名稱。如果此屬性沒有替換項，則可以省略。

since

字串

屬性被廢棄的版本。可以省略。
在 Spring Boot 1.3 之前，可以使用單個 deprecated 布林屬性而不是 deprecation 元素。這仍然以廢棄的方式受支援，不應再使用。如果沒有原因和替換，應設定一個空的 deprecation 物件。

廢棄也可以透過向公開廢棄屬性的 getter 新增 @DeprecatedConfigurationProperty 註解在程式碼中宣告性地指定。例如，假設 my.app.target 屬性令人困惑，並已重新命名為 my.app.name。以下示例展示瞭如何處理這種情況

  • Java

  • Kotlin

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;

@ConfigurationProperties("my.app")
public class MyProperties {

	private String name;

	public String getName() {
		return this.name;
	}

	public void setName(String name) {
		this.name = name;
	}

	@Deprecated
	@DeprecatedConfigurationProperty(replacement = "my.app.name", since = "1.2.0")
	public String getTarget() {
		return this.name;
	}

	@Deprecated
	public void setTarget(String target) {
		this.name = target;
	}

}
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty

@ConfigurationProperties("my.app")
class MyProperties(val name: String?) {

	var target: String? = null
		@Deprecated("") @DeprecatedConfigurationProperty(replacement = "my.app.name", since = "1.2.0") get
		@Deprecated("") set

}
無法設定 level。始終假定為 warning，因為程式碼仍在處理該屬性。

前面的程式碼確保廢棄的屬性仍然有效（在幕後委託給 name 屬性）。一旦 getTarget 和 setTarget 方法可以從您的公共 API 中刪除，元資料中的自動廢棄提示也會消失。如果您想保留提示，新增帶有 error 廢棄級別的手動元資料可確保使用者仍然瞭解該屬性。當提供了 replacement 時，這樣做特別有用。

提示屬性

hints 陣列中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

name

字串

此提示所指屬性的完整名稱。名稱採用小寫句點分隔形式（例如 spring.mvc.servlet.path）。如果屬性指的是對映（例如 system.contexts），則提示要麼應用於對映的 鍵（system.contexts.keys），要麼應用於對映的 值（system.contexts.values）。此屬性是強制性的。

值

ValueHint[]

由 ValueHint 物件（在下表中描述）定義的一系列有效值。每個條目定義值並可能具有描述。

提供者

ValueProvider[]

由 ValueProvider 物件（本文件後面描述）定義的一系列提供者。每個條目定義提供者的名稱及其引數（如果有）。

每個 hint 元素的 values 屬性中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

價值

物件

提示所指元素的有效值。如果屬性型別是陣列，它也可以是值的陣列。此屬性是強制性的。

描述

字串

可以向用戶顯示的值的簡短描述。如果沒有描述，可以省略。建議描述為簡短段落，第一行提供簡潔摘要。描述的最後一行應以句號 (.) 結尾。

每個 hint 元素的 providers 屬性中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

name

字串

用於為提示所指元素提供附加內容輔助的提供者名稱。

parameters

JSON 物件

提供者支援的任何附加引數（有關詳細資訊，請檢視提供者的文件）。

忽略的屬性

ignored 物件可以包含下表所示的屬性

名稱 型別 目的

屬性

ItemIgnore[]

由 ItemIgnore 物件（在下表中描述）定義的一系列被忽略的屬性。每個條目定義被忽略屬性的名稱。

每個 ignored 元素的 properties 屬性中包含的 JSON 物件可以包含下表所示的屬性

名稱 型別 目的

name

字串

要忽略的屬性的完整名稱。名稱採用小寫句點分隔形式（例如 spring.mvc.servlet.path）。此屬性是強制性的。

重複的元資料項

具有相同“屬性”和“組”名稱的物件可以在元資料檔案中多次出現。例如，您可以將兩個獨立的類繫結到相同的字首，每個類可能具有重疊的屬性名稱。儘管元資料中多次出現相同的名稱不常見，但元資料的使用者應注意確保它們支援此情況。

© . This site is unofficial and not affiliated with VMware.