SpringBoot-松散绑定/宽松绑定(Relaxed Binding)

一、前言

在 Java 的配置文件中（如 .properties 和 .yml/.yaml），你看到驼峰命名（如 myProperty）和中划线命名（如 my-property）同时有效，主要是因为 Spring Boot 的“宽松绑定”(Relaxed Binding)策略。

以mybatis的属性配置为例

application.yml文件

# mybatis属性配置
mybatis:
  configuration:
    map-underscore-to-camel-case: true  # 开启下划线转驼峰的映射

application.properties文件

# mybatis属性配置
mybatis.configuration.mapUnderscoreToCamelCase: true  # 开启下划线转驼峰的映射

二、宽松绑定

2.1、何为宽松绑定

简单来说，宽松绑定是 Spring Boot 提供的一种智能属性绑定机制。它允许你在配置属性（如 application.properties、application.yml、环境变量、命令行参数）中使用多种不同格式的名称，Spring Boot 都能自动将它们匹配到你的 @ConfigurationProperties 类或 Bean 的对应字段上。

Spring Boot 1.x 版本已初步支持宽松绑定，Spring Boot 2.x 版本进一步强化了宽松绑定的规范性和一致性。新项目建议直接采用 Spring Boot 2.x + @ConfigurationProperties 以保障兼容性。

• @ConfigurationProperties 成为官方推荐方式 ：明确仅通过此注解支持完整的宽松绑定规则（如前缀命名需符合 kebab-case 格式）。
• @Value 的局限性被固化： 虽然部分简单场景下 @Value 可能兼容宽松格式（如环境变量转小写匹配），但官方文档始终强调其不支持正式宽松绑定，未来版本可能调整此行为。

2.2、宽松绑定的规则

Spring Boot 支持以下几种属性命名格式的自动转换：

• 驼峰命名法（myProperty）
• 短横线命名法（my-property）
• 下划线命名法（my_property）
• 大写下划线命名法（MY_PROPERTY）

2.3、宽松绑定规则详解

Spring Boot 在匹配时，会将配置源（文件、环境变量等）中的属性名和 Java Bean 属性名都进行规范化处理：

• 将所有字符转换为小写。
• 移除所有分隔符（-, _, 空格）。
• 比较规范化后的结果。

示例：

重要提示： 对于带 . 的层级属性（如 server.port），使用中划线替代点（server-port）通常不是好主意，也不推荐。 虽然宽松绑定在简单情况下可能“碰巧”工作（规范化后 serverport 与 server.port 的规范化形式 server.port 不同），但它破坏了属性的层次结构，可能导致意外的绑定结果或错误。点 . 是表示配置树层次结构的标准和推荐方式。

总结：

松散绑定就是在进行匹配时，配置中的名称要去掉中划线和下划线后，忽略大小写的情况下去与java代码中的属性名进行忽略大小写的等值匹配

2.4、优先级规则

如果同一属性以不同格式多次配置，Spring Boot 按以下优先级绑定：

1. 精确匹配（字段名与配置名完全一致）。
2. 短横线命名法。
3. 下划线命名法。
4. 大写下划线命名法。

2.5、注意事项

在SpringBoot官方文档中有几个注意点：

• 属性必须要有getter、setter方法；
• 如果属性的类型是集合，要确保集合是不可变的；
• 如果使用Lombok自动生成getter/setter方法，一定不要生成对应的任何构造函数，因为Spring IOC容器会自动使用它来实例化对象。
• 使用JavaBean属性绑定的方式只针对标准 Java Bean 属性，不支持对静态属性的绑定。
• 前缀匹配： @ConfigurationProperties 的 prefix 也支持宽松绑定。例如，prefix = “my-app” 可以匹配 myApp、my_app 等。
• 严格模式： 可以通过 spring.boot.configurationprocessor.strict 启用严格模式，禁用宽松绑定。

三、宽松绑定实例

3.1、@ConfigurationProperties注解与宽松绑定

application.yml

user:
  userName: 张三             #  驼峰命名
  user-age: 11              #  中划线
  user_class: 三年级二班     #  下划线
  USER_SEX: 男              #  大写+下划线

UserConfig.java

package com.demo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "user")
@Data
public class UserConfig {
    private String userName;
    private int userAge;
    private String userClass;
    private String userSex;
}

TestController.java

package com.demo.controller;

import com.demo.config.UserConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "test")
public class TestController {
    @Autowired
    UserConfig userConfig;
    @Value("${user.userage}")
    private String userage;

    @GetMapping("")
    public String test(){
        System.out.println(userConfig);
        return userConfig.toString();
    }
}

四、其他问题

4.1、Spring Boot Configuration Annotation Processor not configured

问题描述： 当我们使用@ConfigurationProperties注解进行属性注入时，配置类上面可能会显示Spring Boot Configuration Annotation Processor not configured

解决方法：

在pom.xml中引入一下依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

该依赖的作用，简单来说就是为自定义的配置类生成元数据信息。然后报错问题解决，文件能够正常使用。

五、总结

注意：

• ConfigurationProperties的prefix的值必须是短横线隔开式，如demo.relaxed-binding
• @ConfigurationProperties注解支持全量的属性 宽松绑定方式；而@Value只推荐使用标准的kebab-case方式（仅使用小写字母和-），例如：@Value(“{demo.item-price}”)可以提取demo.item-price和demo.itemPrice。
• 松散绑定就是在进行匹配时，配置中的名称要去掉中划线和下划线后，忽略大小写的情况下去与java代码中的属性名进行忽略大小写的等值匹配

创作不易，欢迎打赏，你的鼓励将是我创作的最大动力。