元資料格式

配置元資料檔案位於 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）”都是使用者指定一個給定值的配置項。例如，可以在 application.properties/application.yaml 中指定 server.port 和 server.address，如下所示

  • 屬性

  • 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

String

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

type

String

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

description

String

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

sourceType

String

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

sourceMethod

String

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

屬性屬性

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

名稱 型別 用途

name

String

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

type

String

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

description

String

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

sourceType

String

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

defaultValue

Object

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

deprecation

棄用

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

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

名稱 型別 用途

level

String

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

reason

String

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

replacement

String

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

since

String

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

棄用也可以在程式碼中透過向暴露棄用屬性的 getter 新增 @DeprecatedConfigurationProperty 註解來宣告性地指定。例如，假設 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 屬性）。一旦 getTarget 和 setTarget 方法可以從你的公共 API 中移除，元資料中的自動棄用提示也會消失。如果想保留提示，新增具有 error 棄用級別的手動元資料可以確保使用者仍然瞭解該屬性。在提供了 replacement 時，這樣做尤其有用。

提示屬性

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

名稱 型別 用途

name

String

此提示引用的屬性的完整名稱。名稱採用小寫句點分隔形式（例如 spring.mvc.servlet.path）。如果屬性引用了一個 Map（例如 system.contexts），則提示適用於 Map 的 鍵（system.contexts.keys）或 Map 的 值（system.contexts.values）。此屬性是強制的。

values

ValueHint[]

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

providers

ValueProvider[]

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

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

名稱 型別 用途

value

Object

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

description

String

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

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

名稱 型別 用途

name

String

用於為提示引用的元素提供額外內容輔助的提供者名稱。

parameters

JSON 物件

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

重複的元資料項

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