元数据格式

DeepSeek V3 中英对照 Metadata Format

配置元数据文件位于 META-INF/spring-configuration-metadata.json 路径下的 jar 包中。它们使用 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."
            }
        ]
    }
]}

json

每个“属性”都是用户使用给定值指定的配置项。例如，在您的 application.properties/application.yaml 中可能会指定 server.port 和 server.address，如下所示：

Properties

server.port=9090
server.address=127.0.0.1

properties

YAML

server:
  port: 9090
  address: 127.0.0.1

yaml

“groups”是较高层次的项目，它们本身并不指定值，而是为属性提供上下文分组。例如，server.port 和 server.address 属性就是 server 组的一部分。

备注

并非每个“属性”都必须属于一个“组”。某些属性可能独立存在。

最后，“hints”是用于帮助用户配置特定属性的附加信息。例如，当开发者在配置 spring.jpa.hibernate.ddl-auto 属性时，工具可以利用 hints 为 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	字符串	属性的数据类型的完整签名（例如，String），也可以是一个完整的泛型类型（例如 java.util.Map<java.lang.String,com.example.MyEnum>）。你可以使用此属性来指导用户可以输入的值类型。为了保持一致性，基本类型的类型通过使用其包装类来指定（例如，boolean 变为 Boolean）。请注意，此类可能是一个复杂类型，随着值的绑定，它从 String 转换而来。如果类型未知，则可以省略。
description	字符串	属性的简短描述，可以显示给用户。如果没有可用的描述，则可以省略。建议描述为简短的段落，第一行提供简洁的摘要。描述的最后一行应以句号（.）结尾。
sourceType	字符串	提供此属性的来源的类名。例如，如果该属性来自一个带有 @ConfigurationProperties 注解的类，则此属性将包含该类的完全限定名。如果来源类型未知，则可以省略。
defaultValue	对象	默认值，如果未指定属性，则使用此值。如果属性的类型是数组，则它可以是值的数组。如果默认值未知，则可以省略。
deprecation	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。以下示例展示了如何处理这种情况：

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;
    }

}

java

备注

无法设置 level。由于代码仍在处理该属性，因此始终假定为 warning。

前面的代码确保已弃用的属性仍然有效（在幕后委托给 name 属性）。一旦 getTarget 和 setTarget 方法可以从你的公共 API 中移除，元数据中的自动弃用提示也会消失。如果你想保留提示，添加带有 error 弃用级别的手动元数据可以确保用户仍然能获知该属性。当提供了 replacement 时，这样做尤其有用。

提示属性

hints 数组中包含的 JSON 对象可以包含下表中所示的属性：

名称	类型	用途
name	字符串	该提示所指向的属性的全名。名称采用小写点分隔形式（例如 spring.mvc.servlet.path）。如果属性引用的是一个映射（例如 system.contexts），则该提示要么应用于映射的键（system.contexts.keys），要么应用于映射的值（system.contexts.values）。此属性是必填的。
values	值提示[]	由 ValueHint 对象定义的有效值列表（将在下一个表格中描述）。每个条目定义了该值，并可能包含描述。
providers	值提供者[]	由 ValueProvider 对象定义的提供者列表（将在本文档后面描述）。每个条目定义了提供者的名称及其参数（如果有）。

hint 元素的 values 属性中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
value	对象	提示所指向元素的有效值。如果属性类型是数组，它也可以是值的数组。该属性是必填的。
description	字符串	值的简短描述，可以显示给用户。如果没有可用的描述，可以省略。建议描述为简短的段落，第一行提供简洁的摘要。描述的最后一行应以句号（.）结尾。

每个 hint 元素的 providers 属性中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
name	字符串	用于为提示所指向的元素提供额外内容辅助的提供者名称。
parameters	JSON 对象	提供者支持的任何额外参数（更多详情请查看提供者文档）。

重复的元数据项

在元数据文件中，具有相同“property”和“group”名称的对象可以多次出现。例如，您可以将两个独立的类绑定到相同的前缀，每个类可能会有重叠的属性名称。虽然相同的名称在元数据中多次出现并不常见，但元数据的使用者应注意确保他们支持这种情况。