中繼資料格式

組態中繼資料檔案位於 jar 檔內的 META-INF/spring-configuration-metadata.json。它們使用 JSON 格式，項目分類在 “groups” 或 “properties” 下，其他值提示則分類在 “hints” 下，如下列範例所示

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

每個 “property” 都是使用者使用給定值指定的組態項目。例如，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

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

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

最後，“hints” 是用於協助使用者組態給定屬性的額外資訊。例如，當開發人員組態 spring.jpa.hibernate.ddl-auto 屬性時，工具可以使用提示來為 none、validate、update、create 和 create-drop 值提供一些自動完成協助。

群組屬性

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

名稱 類型 目的

name

字串

群組的完整名稱。此屬性為必填。

type

字串

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

description

字串

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

sourceType

字串

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

sourceMethod

字串

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

屬性屬性

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

名稱 類型 目的

name

字串

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

type

字串

屬性資料類型的完整簽名（例如，java.lang.String），但也包括完整的泛型類型（例如 java.util.Map<java.lang.String,com.example.MyEnum>）。您可以使用此屬性來引導使用者了解他們可以輸入的值的類型。為了保持一致性，基本類型的類型是透過使用其包装器對應項來指定的（例如，boolean 變成 java.lang.Boolean）。請注意，此類別可能是從字串轉換而來的複雜類型，因為值是綁定的。如果類型未知，則可以省略。

description

字串

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

sourceType

字串

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

defaultValue

物件

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

deprecation

棄用

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

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

名稱 類型 目的

level

字串

棄用層級，可以是 warning（預設值）或 error。當屬性的棄用層級為 warning 時，它仍應在環境中繫結。但是，當它的棄用層級為 error 時，該屬性不再被管理且未繫結。

reason

字串

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

replacement

字串

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

since

字串

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

也可以透過在程式碼中宣告式地指定棄用，方法是將 @DeprecatedConfigurationProperty 註解新增至公開已棄用屬性的 getter。例如，假設 my.app.target 屬性令人困惑，並且已重新命名為 my.app.name。以下範例說明如何處理這種情況

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")
	public String getTarget() {
		return this.name;
	}

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

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

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

提示屬性

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

名稱 類型 目的

name

字串

此提示所指屬性的完整名稱。名稱採用小寫句點分隔形式（例如 spring.mvc.servlet.path）。如果屬性指的是映射（例如 system.contexts），則提示適用於映射的鍵 (system.contexts.keys) 或映射的值 (system.contexts.values)。此屬性為必填。

values

ValueHint[]

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

providers

ValueProvider[]

由 ValueProvider 物件定義的供應商列表（稍後在本文檔中描述）。每個條目定義供應商的名稱及其參數（如果有的話）。

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

名稱 類型 目的

value

物件

提示所指元素的有效值。如果屬性的類型是陣列，則它也可以是值陣列。此屬性為必填。

description

字串

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

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

名稱 類型 目的

name

字串

用於為提示所指元素提供額外內容協助的供應商的名稱。

parameters

JSON 物件

供應商支援的任何其他參數（有關更多詳細資訊，請查看供應商的文件）。

重複的中繼資料項目

具有相同 “property” 和 “group” 名稱的物件可以在中繼資料檔案中多次出現。例如，您可以將兩個單獨的類別綁定到相同的前綴，每個類別都可能具有重疊的屬性名稱。雖然在中繼資料中多次出現相同的名稱應該不常見，但中繼資料的消費者應注意確保他們支援它。