Spring Boot @ConfigurationProperties 配置键值异常问题解决

问题重现 #

配置文件application.yml内容：

widget-proxy-route:
  /my/**:
    stripPrefix: 1
    targetUri: bbbbbbbbb

对应的@ConfigurationProperties类：

import jakarta.annotation.PostConstruct;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import java.util.HashMap;

@Configuration
@ConfigurationProperties(prefix = "widget-proxy-route")
public class RouteProperties extends HashMap<Object, RouteProperties.ProxyRoute> {
    @PostConstruct
    public void init() {
        for(Object key : keySet()) {
            System.out.println("key:" + key + ", ProxyRoute:" + this.get(key));
        }
    }

    @Data
    public static class ProxyRoute {
        private String targetUri;
        private Integer stripPrefix;
    }
}

运行后读取到的键为my，而非预期的/my/**，尝试添加引号、转义斜杠均无效。

原因分析 #

Spring Boot默认启用宽松绑定（Relaxed Binding），绑定Map类型配置时会自动处理键：

• 移除斜杠、点号等分隔符
• 将键转换为小写
• 忽略特殊字符的原始格式

这导致/my/**被自动解析为my。

解决方案 #

方案1：启用严格绑定+修正Map键类型 #

1. 修改RouteProperties类，将Map键类型改为String，并启用严格绑定：

@Configuration
@ConfigurationProperties(prefix = "widget-proxy-route", bindingMode = ConfigurationProperties.BindingMode.STRICT)
public class RouteProperties extends HashMap<String, RouteProperties.ProxyRoute> {
    // 原有代码不变
}

2. 在application.yml中用双引号包裹带特殊字符的键：

widget-proxy-route:
  "/my/**":
    stripPrefix: 1
    targetUri: bbbbbbbbb

方案2：全局关闭宽松绑定 #

在application.yml中添加全局配置关闭宽松绑定：

spring:
  main:
    relaxed-binding-enabled: false

同时将RouteProperties的Map键类型改为String，配置文件中用双引号包裹键即可。

验证 #

启动应用后，控制台输出将显示：

key:/my/**, ProxyRoute:ProxyRoute(targetUri=bbbbbbbbb, stripPrefix=1)

内容的提问来源于stack exchange，提问作者Seil Suh