提供手動提示

為了改善使用者體驗並進一步協助使用者組態給定的屬性，您可以提供額外的元資料，以

  • 描述屬性的潛在值清單。

  • 關聯提供者，將明確定義的語意附加到屬性，以便工具可以根據專案的上下文發現潛在值的清單。

值提示

每個提示的 name 屬性都指向屬性的 name。在先前顯示的初始範例中，我們為 spring.jpa.hibernate.ddl-auto 屬性提供了五個值：none、validate、update、create 和 create-drop。每個值也可以有描述。

如果您的屬性類型為 Map，您可以為鍵和值提供提示（但不能為 map 本身提供提示）。特殊的 .keys 和 .values 後綴必須分別指向鍵和值。

假設 my.contexts 將 magic String 值對應到整數，如下例所示

import java.util.Map;

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

@ConfigurationProperties("my")
public class MyProperties {

	private Map<String, Integer> contexts;

	// getters/setters ...

	public Map<String, Integer> getContexts() {
		return this.contexts;
	}

	public void setContexts(Map<String, Integer> contexts) {
		this.contexts = contexts;
	}

}

magic 值（在此範例中）是 sample1 和 sample2。為了為鍵提供額外的內容輔助，您可以將以下 JSON 新增到模組的手動元資料中

{"hints": [
	{
		"name": "my.contexts.keys",
		"values": [
			{
				"value": "sample1"
			},
			{
				"value": "sample2"
			}
		]
	}
]}
我們建議您為這兩個值使用 Enum。如果您的 IDE 支援，這是迄今為止最有效的自動完成方法。

值提供者

提供者是一種將語意附加到屬性的強大方法。在本節中，我們定義了您可以為自己的提示使用的官方提供者。但是，您最喜歡的 IDE 可能會實作其中一些或全部都不實作。此外，它最終可能會提供自己的提供者。

由於這是一項新功能，IDE 供應商必須趕上它的運作方式。採用時間自然會有所不同。

下表總結了支援的提供者清單

名稱 描述

any

允許提供任何其他值。

class-reference

自動完成專案中可用的類別。通常受 target 參數指定的基底類別約束。

handle-as

將屬性視為由強制性 target 參數定義的類型定義。

logger-name

自動完成有效的記錄器名稱和記錄器群組。通常，目前專案中可用的套件和類別名稱可以自動完成，以及定義的群組。

spring-bean-reference

自動完成目前專案中可用的 bean 名稱。通常受 target 參數指定的基底類別約束。

spring-profile-name

自動完成專案中可用的 Spring 設定檔名稱。
給定屬性只能有一個提供者處於活動狀態，但如果多個提供者可以以某種方式管理該屬性，則可以指定多個提供者。請確保將最強大的提供者放在第一位，因為 IDE 必須使用 JSON 區段中它可以處理的第一個提供者。如果給定屬性沒有支援提供者，則不會提供任何特殊的內容輔助。

Any

特殊的 any 提供者值允許提供任何其他值。如果支援，則應應用基於屬性類型的常規值驗證。

如果您有值清單，並且任何額外的值仍應被視為有效，則通常使用此提供者。

以下範例提供 on 和 off 作為 system.state 的自動完成值

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

請注意，在前面的範例中，也允許任何其他值。

類別參考

class-reference 提供者自動完成專案中可用的類別。此提供者支援以下參數

參數 類型 預設值 描述

target

String (Class)

無

應該可指派給所選值的類別的完整名稱。通常用於篩選掉非候選類別。請注意，此資訊可以由類型本身透過公開具有適當上限的類別來提供。

concrete

boolean

true

指定是否僅將具體類別視為有效候選類別。

以下元資料程式碼片段對應於標準 server.servlet.jsp.class-name 屬性，該屬性定義要使用的 JspServlet 類別名稱

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

Handle As

handle-as 提供者可讓您將屬性的類型替換為更高等級的類型。當屬性的類型為 java.lang.String 時，通常會發生這種情況，因為您不希望組態類別依賴可能不在類別路徑上的類別。此提供者支援以下參數

參數 類型 預設值 描述

target

String (Class)

無

要考慮用於屬性的類型的完整名稱。此參數為必填項。

可以使用以下類型

  • 任何 java.lang.Enum：列出屬性的可能值。（我們建議使用 Enum 類型定義屬性，因為 IDE 自動完成值不需要進一步的提示）

  • java.nio.charset.Charset：支援字元集/編碼值的自動完成（例如 UTF-8）

  • java.util.Locale：地區設定的自動完成（例如 en_US）

  • org.springframework.util.MimeType：支援內容類型值的自動完成（例如 text/plain）

  • org.springframework.core.io.Resource：支援 Spring 的 Resource 抽象的自動完成，以引用檔案系統或類別路徑上的檔案（例如 classpath:/sample.properties）

如果可以提供多個值，請使用 Collection 或陣列類型來教導 IDE 關於它的資訊。

以下元資料程式碼片段對應於標準 spring.liquibase.change-log 屬性，該屬性定義要使用的變更日誌的路徑。它實際上在內部用作 org.springframework.core.io.Resource，但不能以此方式公開，因為我們需要保留原始 String 值以將其傳遞給 Liquibase API。

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

記錄器名稱

logger-name 提供者自動完成有效的記錄器名稱和記錄器群組。通常，目前專案中可用的套件和類別名稱可以自動完成。如果啟用了群組（預設）並且在組態中識別了自訂記錄器群組，則應為其提供自動完成功能。特定框架可能具有可以支援的額外 magic 記錄器名稱。

此提供者支援以下參數

參數 類型 預設值 描述

group

boolean

true

指定是否應考慮已知的群組。

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

以下元資料程式碼片段對應於標準 logging.level 屬性。鍵是記錄器名稱，值對應於標準日誌等級或任何自訂等級。由於 Spring Boot 定義了一些現成的記錄器群組，因此已為這些群組新增了專用的值提示。

{"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 參考

spring-bean-reference 提供者自動完成目前專案組態中定義的 bean。此提供者支援以下參數

參數 類型 預設值 描述

target

String (Class)

無

應該可指派給候選項的 bean 類別的完整名稱。通常用於篩選掉非候選 bean。

以下元資料程式碼片段對應於標準 spring.jmx.server 屬性，該屬性定義要使用的 MBeanServer bean 的名稱

{"hints": [
	{
		"name": "spring.jmx.server",
		"providers": [
			{
				"name": "spring-bean-reference",
				"parameters": {
					"target": "javax.management.MBeanServer"
				}
			}
		]
	}
]}
繫結器不知道元資料。如果您提供該提示，您仍然需要使用 ApplicationContext 將 bean 名稱轉換為實際的 Bean 參考。

Spring 設定檔名稱

spring-profile-name 提供者自動完成目前專案組態中定義的 Spring 設定檔。

以下元資料程式碼片段對應於標準 spring.profiles.active 屬性，該屬性定義要啟用的 Spring 設定檔名稱

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