提供手動提示

為了改善使用者體驗並進一步幫助使用者配置給定的屬性，你可以提供額外的元資料，這些元資料可以

  • 描述屬性的潛在值列表。

  • 關聯一個提供者（provider），以便為屬性附加明確定義的語義，這樣工具就可以根據專案的上下文發現潛在值的列表。

值提示

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

如果你的屬性是 Map 型別，你可以為鍵和值提供提示（但不能為 Map 本身提供）。特殊的 .keys 和 .values 字尾必須分別指代鍵和值。

假設一個 my.contexts 將神奇的 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;
	}

}

這些神奇值（在本例中）是 sample1 和 sample2。為了為鍵提供額外的上下文輔助，你可以將以下 JSON 新增到該模組的手動元資料中

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

值提供者

提供者（Provider）是為屬性附加語義的強大方式。在本節中，我們定義了你可以用於自己提示的官方提供者。但是，你喜歡的 IDE 可能實現其中一些或全部，也可能最終提供它自己的提供者。

由於這是一個新特性，IDE 供應商必須跟上它的工作方式。採用時間自然會有所不同。

下表總結了支援的提供者列表

名稱 描述

any

允許提供任何額外的值。

class-reference

自動完成專案中可用的類。通常受到 target 引數指定的基類的限制。

handle-as

將屬性視為由強制的 target 引數定義的型別所定義。

logger-name

自動完成有效的記錄器名稱和記錄器組。通常，當前專案中可用的包名和類名以及已定義的組都可以自動完成。

spring-bean-reference

自動完成當前專案中可用的 Bean 名稱。通常受到 target 引數指定的基類的限制。

spring-profile-name

自動完成專案中可用的 Spring profile 名稱。
對於給定的屬性，只有一個提供者可以處於活動狀態，但是如果它們都可以 以某種方式 管理該屬性，你可以指定多個提供者。請確保將最強大的提供者放在首位，因為 IDE 必須使用 JSON 部分中它能處理的第一個。如果給定的屬性不支援任何提供者，則也不會提供特殊的上下文輔助。

Any

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

如果你有一個值列表，並且任何額外的值都應被視為有效，通常使用此提供者。

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

{"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 屬性，該屬性定義了要使用的類名必須是 HttpServlet

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

Handle As

handle-as 提供者允許你將屬性的型別替換為更高級別的型別。這通常發生在屬性具有 String 型別時，因為你不希望你的配置類依賴於可能不在類路徑上的類。此提供者支援以下引數

引數 型別 預設值 描述

target

String (Class)

無

要考慮用於屬性的型別的完全限定名。此引數是強制性的。

可以使用以下型別

  • 任何 Enum：列出屬性的可能值。（我們建議使用 Enum 型別定義屬性，因為 IDE 自動完成值時無需額外提示）

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

  • Locale：自動完成區域設定（例如 en_US）

  • MimeType：支援自動完成內容型別值（例如 text/plain）

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

如果可以提供多個值，請使用 Collection 或 Array 型別來告知 IDE。

以下元資料片段對應於標準 spring.liquibase.change-log 屬性，該屬性定義了要使用的變更日誌（changelog）的路徑。它實際上在內部用作 Resource，但不能以這種方式暴露，因為我們需要保留原始的 String 值以將其傳遞給 Liquibase API。

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

記錄器名稱

logger-name 提供者自動完成有效的記錄器名稱和記錄器組。通常，當前專案中可用的包名和類名可以自動完成。如果啟用了組（預設），並且在配置中識別出了自定義記錄器組，則應為其提供自動完成。特定的框架也可能有一些額外的特殊記錄器名稱可以得到支援。

此提供者支援以下引數

引數 型別 預設值 描述

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 類的完全限定名。通常用於過濾掉非候選 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 Profile 名稱

spring-profile-name 提供者自動完成當前專案配置中定義的 Spring profile。

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

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