Spring Boot中@ConfigurationProperties绑定YAML时Map为空问题

配置内容 #

project:
  component:
    users:
      default:
        username: "JohnDoe"
      anotherUser:
        username: "AliceSmith"

代码实现 #

AppProperties类 #

@Getter
@Setter
@Accessors(fluent = false)
@ConfigurationProperties(prefix = "project.component")
@Component
public class AppProperties {
    private UsersConfiguration users = new UsersConfiguration();

    @Bean
    UsersConfiguration users() {
        return users;
    }
}

UsersConfiguration类 #

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class UsersConfiguration {
    private Map<String, User> users = new HashMap<>();
}

User记录类 #

public record User(String username) {}

问题 #

通过AppProperties的users()方法暴露UsersConfiguration Bean，但调试时发现AppProperties中的users字段里的Map为空（size=0），但YAML配置确实包含有效数据。

疑问 #

1. 为何YAML格式看似正确，但AppProperties中的users Map仍为空？
2. 在Spring Boot中将YAML绑定到Map<String, User>是否需要额外步骤或配置？

解答 #

1. Map为空的核心原因 #

问题出在YAML配置层级与Java类结构不匹配：

• AppProperties的prefix是project.component，类内的字段是users（类型UsersConfiguration）
• UsersConfiguration内的字段又是users（类型Map<String, User>）
• 因此正确的YAML绑定路径应该是project.component.users.users，但你当前的YAML只写到project.component.users，少了一层users，导致Spring无法将配置映射到Map上。

2. 绑定Map的要求 #

Spring Boot默认支持YAML到Map<String, T>的绑定，无需额外特殊配置，但要满足几个基础条件：

• 确保绑定类有正确的访问器：User作为记录类自动生成了构造器和访问方法，UsersConfiguration的@Getter@Setter也符合要求
• 如果没有用@Component标注配置类，需要在启动类上添加@ConfigurationPropertiesScan注解扫描配置类（你这里已经加了@Component，无需额外操作）
• 推荐引入spring-boot-configuration-processor依赖，用于生成配置元数据和IDE提示（非强制，但能提升开发体验）

修复方案 #

有两种可选方式：

方式一：调整YAML配置，补全层级

project:
  component:
    users:
      users:
        default:
          username: "JohnDoe"
        anotherUser:
          username: "AliceSmith"

方式二：简化Java类结构，减少层级

直接将Map字段放到AppProperties中，删除UsersConfiguration类：

@Getter
@Setter
@Accessors(fluent = false)
@ConfigurationProperties(prefix = "project.component")
@Component
public class AppProperties {
    private Map<String, User> users = new HashMap<>();

    @Bean
    Map<String, User> usersMap() {
        return users;
    }
}

修改后原YAML配置可直接绑定到AppProperties的users字段。

内容的提问来源于stack exchange，提问作者Fábio Ramalhos