Spring Boot 属性前缀必须采用规范形式

教程

1、概览

在教程中，我们将仔细研究 Spring Boot 中出现的错误：Reason: Canonical names should be kebab-case (’-’ separated), lowercase alpha-numeric characters, and must start with a letter。

首先，我们将阐明 Spring Boot 中出现此错误的主要原因。然后，我们将通过一个实际示例深入探讨如何重现和解决这个问题。

2、问题说明

首先，让我们了解一下错误信息的含义。“Canonical names should be kebab-case” 意思是“规范名称应使用短横线命名法（kebab-case）”。

为确保一致性，@ConfigurationProperties 注解的 prefix 参数中使用的命名约定应遵循短横线命名格式。

例如：

@ConfigurationProperties(prefix = "my-example")

3、Maven 依赖

在 pom.xml 中添加必要的依赖：

<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter</artifactId> 
    <version>3.0.5</version>
</dependency>

spring-boot-starter 是重现问题的唯一依赖。

4、重现问题

4.1、应用配置

注册所需的组件：

@Configuration
@ConfigurationProperties(prefix = "customProperties")
public class MainConfiguration {
    String name;
 
    // get/set 方法省略
}

然后，我们需要在 application.properties 文件中添加一个自定义属性：

custom-properties.name="Baeldung"

application.properties 位于 src/main/resources 下：

|   pom.xml
+---src
|   +---main
|   |   +---java
|   |   |   \---com
|   |   |       \---baeldung
|   |   |           ...
|   |   |           ...
|   |   \---resources
|   |           application.properties

现在，让我们在项目根目录下执行 mvn spring-boot:run 命令，运行 Spring Boot 示例应用，看看会发生什么：

$ mvn spring-boot:run
...
...
***************************
APPLICATION FAILED TO START
***************************

Description:

Configuration property name 'customProperties' is not valid:

    Invalid characters: 'P'
    Bean: mainConfiguration
    Reason: Canonical names should be kebab-case ('-' separated), lowercase alpha-numeric characters and must start with a letter

Action:

Modify 'customProperties' so that it conforms to the canonical names requirements.

如上所示，我们收到了一条错误信息：“Modify ‘customProperties’ so that it conforms to the canonical names requirements.”。这条错误信息表明，customProperties 当前使用的命名约定不符合 Spring 规定的命名约定。换句话说，需要更改 customProperties 命名，使其符合 Spring 对属性命名的要求。

5、修复异常

我们需要将属性 prefix 从：

@ConfigurationProperties(prefix = "customProperties")

改为短横线命名法：

@ConfigurationProperties(prefix = "custom-properties")

在 properties 中，我们可以保留任何命名样式，这样就可以很好地访问它们。

6、短横线命名的优点

使用短横线命名的主要优势在于我们可以使用以下任何一种命名方式在 properties 文件中定义属性：

  • 小写驼峰：camelCaseLikeThis
  • 大写驼峰：PascalCaseLikeThis
  • 下划线命名：snake_case_like_this
  • 短横线命名：kebab-case-like-this
@ConfigurationProperties(prefix = "custom-properties")

上面的 prefix 配置可以正确地访问如下 properties：

customProperties.name="Baeldung"

CustomProperties.name="Baeldung"

custom_properties.name="Baeldung"

custom-properties.name="Baeldung"

7、总结

在本教程中，我们了解到 Spring Boot 支持多种格式的属性名称，包括大小写驼峰、下划线命名和短横线命名，但鼓励我们以短横线命名的规范地访问它们，从而减少因命名约定不一致而导致错误或混淆的可能性。

参考：https://www.baeldung.com/spring-boot-properties-canonical-form