Spring Boot @ConfigurationProperties 怎样绑定嵌套集合

我在把一组服务配置从零散的 @Value 字段整理成一个配置对象时，最容易出错的不是前缀本身，而是“配置树”和“Java 对象树”没有对齐：列表被写成了 Map，嵌套对象没有实例，或者集合已经初始化却使用了不可变实现。Spring Boot 的 @ConfigurationProperties 适合承载这种结构化配置。

官方地址：https://docs.spring.io/spring-boot/reference/features/external-config.html

绑定嵌套集合的关键是让前缀、字段层级和集合形状保持一致：List 使用数字索引，Map 使用键名；预初始化的集合应当可变，嵌套对象则要让 Binder 有办法创建或接收它。

先把配置树和 Java 对象树对齐

先不要急着加注解，拿一份最小配置把层级画出来。下面的 my.service 是绑定前缀，security 是嵌套对象，roles 是 List，headers 是 Map：

my:
  service:
    endpoint: https://api.example.com
    security:
      roles:
        - reader
        - writer
      headers:
        X-Region: cn-east
        X-Trace: enabled

这棵树对应的重点不是字段名称看起来像不像，而是每一层的形状是否一致。roles[0]、roles[1] 表示列表元素；headers.X-Region、headers.X-Trace 表示 Map 的键和值。

用一个配置对象承载三种嵌套形状

Java 类可以把三种形状明确表达出来。这里保留普通 Java Bean 风格，便于读者看清每一个绑定入口：

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("my.service")
public class MyProperties {
    private String endpoint;
    // 预初始化嵌套对象，避免 Binder 面对 null 时没有可写入的对象。
    private Security security = new Security();

    public String getEndpoint() {
        return endpoint;
    }

    public void setEndpoint(String endpoint) {
        this.endpoint = endpoint;
    }

    public Security getSecurity() {
        return security;
    }

    public void setSecurity(Security security) {
        this.security = security;
    }

    public static class Security {
        // 使用可变实现，Binder 才能把多个列表项写入集合。
        private List roles = new ArrayList();
        // LinkedHashMap 让配置中的键值保持稳定的遍历顺序。
        private Map headers = new LinkedHashMap();

        public List getRoles() {
            return roles;
        }

        public void setRoles(List roles) {
            this.roles = roles;
        }

        public Map getHeaders() {
            return headers;
        }

        public void setHeaders(Map headers) {
            this.headers = headers;
        }
    }
}

如果项目没有使用配置属性扫描，也可以在配置类上用 @EnableConfigurationProperties(MyProperties.class) 注册它。这里的注册方式和集合绑定是两个问题：前者决定类型是否进入容器，后者决定进入容器后的字段能否接住配置。

List 用索引，Map 用键名

我第一次排查“集合为空”时，通常会先把 YAML 展开成两种模型看。List 的每个条目没有业务键，Binder 依靠索引位置写入；Map 的每个条目则需要一个稳定的键。

my:
  service:
    security:
      roles:
        - reader # 列表的第 0 项
        - writer # 列表的第 1 项
      headers:
        X-Region: cn-east # Map 的键是 X-Region
        X-Trace: enabled   # Map 的键是 X-Trace

下面两种改动含义不同：

• 调整 roles 的顺序，改变的是 List 的索引和最终顺序。
• 增加 headers.X-Timeout，增加的是 Map 中一个新的键值对。

如果业务上需要按名称查找，Map 往往比“把名称塞进 List 元素再遍历”更直接；如果业务只关心顺序，List 的配置形状更容易阅读。

集合可变，嵌套对象要能被创建

Spring Boot 文档特别强调了几个容易被忽略的边界：已经初始化的 Map 或 Collection 可以省略 setter，但初始化对象应当是可变实现；预初始化的嵌套 POJO 也可以没有 setter。反过来，如果希望 Binder 通过默认构造器临时创建嵌套对象，setter 就不能缺席。

import java.util.Collections;
import java.util.List;

public class BadSecurity {
    // 不要把需要被绑定的集合预初始化为不可变集合。
    private List roles = Collections.emptyList();

    public List getRoles() {
        return roles;
    }
    // 没有 setter 时，Binder 无法替换这个字段，也不能向不可变集合追加元素。
}

更稳妥的约定是：内部集合使用 ArrayList 或 LinkedHashMap 等可变实现；嵌套对象要么直接创建实例，要么提供可用的 setter 和默认构造器。不要只凭“有 getter”判断字段就一定能绑定。

字段为空时按四层排查

遇到对象已经注入但嵌套字段为空，我会按下面的顺序排查，避免一上来就改 Java 类。

1. 看前缀：注解上的 my.service 必须和配置树的路径一致，少一层或多一层都会让整棵子树落空。
2. 看字段名：配置键应当落到对应的 Java Bean 属性，优先使用清晰的 kebab-case，避免把同一个字段写成多种不必要的拼法。
3. 看集合形状：带 - 的 YAML 是 List，带自定义键的映射是 Map，不要只看最终字符串值。
4. 看注册方式：确认配置属性类已被扫描或通过 @EnableConfigurationProperties 注册；注册缺失时，问题不是集合本身。

这四层能把“前缀错”“字段错”“形状错”和“类型未注册”分开。只有确认前面三层都对齐后，才值得继续看 setter、构造器或集合实现。

什么时候换成构造器绑定

如果配置对象创建后就不希望被修改，可以考虑构造器绑定，但这属于对象生命周期选择，不是解决所有绑定问题的快捷方式。对于需要追加列表项、替换 Map 或在测试里重新注入配置的模型，可变 Bean 更直观；对于启动时一次性读取、字段应当保持稳定的模型，构造器绑定更容易表达不可变意图。

我的经验是先用清晰的 Bean 模型把配置树跑通，再根据对象是否需要变更决定是否收紧为不可变类型。这样能把“绑定失败”和“设计上不允许修改”两个问题分开。

小结：先对齐形状，再处理边界

@ConfigurationProperties 绑定嵌套集合时，可以把规则记成四句话：前缀决定从哪棵配置树开始，字段层级决定对象树怎么展开，List 依赖索引而 Map 依赖键名，预初始化集合必须可变。嵌套对象则要么提前创建，要么让 Binder 通过默认构造器和 setter 创建。

把这几个形状先画清楚，再去处理校验、不可变设计和环境覆盖，排查会比盲目增加注解更快。

相关问题

@ConfigurationProperties 和 @Value 应该怎么选？

单个简单值可以用 @Value；多个相关配置、层级对象和集合更适合 @ConfigurationProperties，因为它们能集中表达结构并配合类型转换。

Map 的键包含连字符怎么办？

把它当作配置键直接写在映射下方，并在 Java 中使用 Map 接收。不要为了迁就键名把整个结构改成 List。

绑定结构正确但仍想阻止缺失值怎么办？

那已经进入配置校验问题，应在结构绑定稳定后再加入 Bean Validation 和针对嵌套对象的校验标记。