Spring 注入 Map 集合详解

一、什么是 Map 注入？

Map 注入是指将一个 Map 类型的集合注入到 Bean 的属性中。Map 以键值对的形式存储数据，键和值都可以是简单类型或对象。在 Spring 中，Map 注入常用于：

根据名称动态选择策略或处理器
从配置文件中读取一组键值对配置
收集容器中所有同类型的 Bean，以 Bean 名称为键

java 复制代码

@Component
public class MyBean {
    private Map<String, String> configs;          // 简单键值对
    private Map<String, DataSource> dataSources;  // Bean Map
    private Map<String, PaymentStrategy> strategies; // 策略 Map
}

二、XML 配置中注入 Map

2.1 注入简单键值对

xml 复制代码

<bean id="myBean" class="com.example.MyBean">
    <property name="configs">
        <map>
            <entry key="timeout" value="30"/>
            <entry key="retry" value="3"/>
            <entry key="debug" value="true"/>
        </map>
    </property>
</bean>

Spring 会自动将字符串值转换为目标类型（如 Integer、Boolean）。

2.2 注入 Bean 作为值

xml 复制代码

<bean id="myBean" class="com.example.MyBean">
    <property name="dataSources">
        <map>
            <entry key="primary" value-ref="primaryDataSource"/>
            <entry key="secondary" value-ref="secondaryDataSource"/>
        </map>
    </property>
</bean>

2.3 注入 Bean 作为键

xml 复制代码

<bean id="myBean" class="com.example.MyBean">
    <property name="handlerMap">
        <map>
            <entry key-ref="keyBean1" value-ref="handler1"/>
            <entry key-ref="keyBean2" value-ref="handler2"/>
        </map>
    </property>
</bean>

2.4 注入嵌套对象

xml 复制代码

<bean id="myBean" class="com.example.MyBean">
    <property name="users">
        <map>
            <entry key="zhangsan">
                <bean class="com.example.User">
                    <property name="age" value="25"/>
                </bean>
            </entry>
            <entry key="lisi">
                <bean class="com.example.User">
                    <property name="age" value="30"/>
                </bean>
            </entry>
        </map>
    </property>
</bean>

2.5 使用 `<props>` 简化 String 到 String 的 Map

如果 Map 的键和值都是 String，可以使用 <props> 标签：

xml 复制代码

<bean id="myBean" class="com.example.MyBean">
    <property name="configs">
        <props>
            <prop key="timeout">30</prop>
            <prop key="retry">3</prop>
        </props>
    </property>
</bean>

<props> 底层使用 Properties 类，本质上是 Map<Object, Object>，但键和值都必须是 String。

三、@Value 注入 Map

@Value 注入 Map 需要使用 SpEL 表达式，因为默认的属性占位符 ${} 不支持 Map 结构。

3.1 从配置文件读取（内联格式）

配置文件：

yaml 复制代码

app:
  configs: {timeout: 30, retry: 3, debug: true}

Java：

java 复制代码

@Value("#{${app.configs}}")
private Map<String, String> configs;

注意：${app.configs} 会被解析为字符串 {timeout: 30, retry: 3, debug: true}，然后由 SpEL 的 #{} 解析为 Map。

3.2 使用 SpEL 直接定义

java 复制代码

@Value("#{{'timeout': 30, 'retry': 3, 'debug': true}}")
private Map<String, Object> configs;

3.3 带默认值

java 复制代码

@Value("#{${app.configs:{timeout:30, retry:3}}}")
private Map<String, String> configs;

3.4 注意事项

@Value 注入 Map 需要 SpEL，语法相对复杂，容易出错。
配置值中的逗号和冒号需要正确处理。
对于复杂的 Map 结构，推荐使用 @ConfigurationProperties。

四、@ConfigurationProperties 绑定 Map

@ConfigurationProperties 是绑定 Map 的最佳方式，支持各种复杂结构。

4.1 简单 Map

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
@Getter
@Setter
public class AppProperties {
    private Map<String, String> configs;
}

yaml 复制代码

app:
  configs:
    timeout: 30
    retry: 3
    debug: true

4.2 Map 的值是对象

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
@Getter
@Setter
public class AppProperties {
    private Map<String, DataSourceConfig> datasources;
    
    @Getter
    @Setter
    public static class DataSourceConfig {
        private String url;
        private String username;
        private String password;
    }
}

yaml 复制代码

app:
  datasources:
    primary:
      url: jdbc:mysql://localhost:3306/main
      username: root
      password: 123456
    secondary:
      url: jdbc:mysql://localhost:3306/backup
      username: backup
      password: 654321

4.3 Map 的值是 List

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
@Getter
@Setter
public class AppProperties {
    private Map<String, List<String>> clusters;
}

yaml 复制代码

app:
  clusters:
    cluster-a:
      - node1
      - node2
    cluster-b:
      - node3
      - node4

4.4 Map 的值是 Map（嵌套）

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
@Getter
@Setter
public class AppProperties {
    private Map<String, Map<String, String>> nested;
}

yaml 复制代码

app:
  nested:
    group1:
      key1: value1
      key2: value2
    group2:
      key3: value3

4.5 Map 的键是枚举

java 复制代码

public enum LogLevel {
    DEBUG, INFO, WARN, ERROR
}

@Component
@ConfigurationProperties(prefix = "app")
@Getter
@Setter
public class AppProperties {
    private Map<LogLevel, String> logConfigs;
}

yaml 复制代码

app:
  log-configs:
    DEBUG: "com.example: DEBUG"
    INFO: "com.example: INFO"

Spring 会自动将配置中的字符串键转换为枚举类型。

五、自动注入 Bean Map（最常用）

Spring 支持将容器中所有同类型的 Bean 自动注入到 Map 中，Bean 的名称作为 key，Bean 实例作为 value。这是策略模式在 Spring 中的经典实现。

5.1 基本用法

java 复制代码

public interface PaymentStrategy {
    void pay(double amount);
}

@Component("alipay")
public class AliPayStrategy implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("支付宝支付：" + amount);
    }
}

@Component("wechat")
public class WechatPayStrategy implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("微信支付：" + amount);
    }
}

@Service
public class PaymentService {
    
    @Autowired
    private Map<String, PaymentStrategy> strategyMap;
    
    public void pay(String type, double amount) {
        PaymentStrategy strategy = strategyMap.get(type);
        if (strategy == null) {
            throw new IllegalArgumentException("不支持的支付方式：" + type);
        }
        strategy.pay(amount);
    }
}

调用 pay("alipay", 100) 时，strategyMap.get("alipay") 会返回 AliPayStrategy 实例。

5.2 构造器注入 Map

java 复制代码

@Service
public class PaymentService {
    private final Map<String, PaymentStrategy> strategyMap;
    
    public PaymentService(Map<String, PaymentStrategy> strategyMap) {
        this.strategyMap = strategyMap;
    }
}

5.3 使用 @Order 控制顺序

自动注入的 Map 默认是 LinkedHashMap，保留 Bean 定义的顺序。可以通过 @Order 注解控制顺序：

java 复制代码

@Component("first")
@Order(1)
public class FirstStrategy implements PaymentStrategy { }

@Component("second")
@Order(2)
public class SecondStrategy implements PaymentStrategy { }

Map 的迭代顺序会按 @Order 的值从小到大排列。

5.4 按类型而不是名称

如果同一个接口有多个实现，但希望按自定义的 key 获取，可以配合 @Qualifier 或自定义注解。或者让每个策略实现一个 getName() 方法，在 @PostConstruct 中构建 Map：

java 复制代码

@Service
public class PaymentService {
    private final Map<String, PaymentStrategy> strategyMap = new HashMap<>();
    
    @Autowired
    private List<PaymentStrategy> strategies;
    
    @PostConstruct
    public void init() {
        for (PaymentStrategy strategy : strategies) {
            strategyMap.put(strategy.getName(), strategy);
        }
    }
}

六、Map 为空时的处理

当容器中没有匹配类型的 Bean 时，@Autowired 注入 Map 不会抛异常，而是注入一个空 Map。

java 复制代码

@Autowired
private Map<String, Handler> handlerMap;  // 没有 Handler 时，注入空 Map（不是 null）

使用 ObjectProvider 可以更灵活地处理：

java 复制代码

@Autowired
private ObjectProvider<Map<String, Handler>> handlerMapProvider;

public void doSomething() {
    Map<String, Handler> handlerMap = handlerMapProvider.getIfAvailable(Collections::emptyMap);
}

在 @PostConstruct 中校验 Map 是否为空：

java 复制代码

@PostConstruct
public void init() {
    if (strategyMap.isEmpty()) {
        throw new IllegalStateException("没有可用的策略实现");
    }
}

七、Map 注入 vs List/Set/数组注入

对比维度	Map	List	Set	数组
获取方式	按 key 获取	按索引或遍历	遍历	按索引
是否去重	key 唯一	允许重复	自动去重	允许重复
默认实现	`LinkedHashMap`	`ArrayList`	`LinkedHashSet`	无
找不到 Bean 时	注入空 Map	注入空 List	注入空 Set	抛异常
自动注入 Bean	key 为 Bean 名称	所有 Bean	所有 Bean	所有 Bean
排序	默认保留插入顺序	`@Order`	`@Order`（LinkedHashSet）	`@Order`
适用场景	按名称查找	顺序遍历	去重收集	固定长度

选择建议：

需要按名称动态选择 → Map
需要顺序遍历 → List
需要去重 → Set
固定长度、性能敏感 → 数组

八、常见问题

8.1 @Value 注入 Map 失败

原因：@Value 默认不支持 Map 结构，必须使用 SpEL 表达式 #{}。

解决：

java 复制代码

@Value("#{${app.configs}}")
private Map<String, String> configs;

配置文件中必须使用内联格式：app.configs={key1:value1, key2:value2}。

8.2 YAML 中 Map 格式错误

正确格式：

yaml 复制代码

app:
  configs:
    key1: value1
    key2: value2

错误格式：

yaml 复制代码

app:
  configs: {key1: value1, key2: value2}  # 也可以，但容易出错

推荐使用缩进格式，可读性更好。

8.3 自动注入 Bean Map 时 key 不符合预期

原因：key 默认是 Bean 的名称，如果 Bean 没有指定名称，则使用类名首字母小写。

解决：在 @Component 或 @Service 中显式指定 Bean 名称，如 @Component("alipay")。

8.4 Map 的泛型丢失

原因：Java 运行时泛型擦除，Spring 绑定 Map 时可能无法确定值类型。

解决：使用 @ConfigurationProperties 绑定，Spring 会通过 setter 方法的参数类型推断泛型。如果仍有问题，可以使用 @NestedConfigurationProperty 注解辅助。

8.5 Map 中的元素顺序不固定

原因：如果使用 HashMap，顺序不固定。Spring 自动注入时默认使用 LinkedHashMap，保留插入顺序。

解决：声明为 Map 即可（Spring 默认注入 LinkedHashMap），或使用 @Order 控制 Bean 定义顺序。

九、最佳实践

优先使用 @ConfigurationProperties 绑定 Map。 对于配置文件中的 Map 结构，@ConfigurationProperties 比 @Value 更类型安全、更易维护。

自动注入 Bean Map 用于策略模式。 当需要根据名称动态选择策略时，@Autowired Map<String, Strategy> 是最简洁的方式，key 为 Bean 名称。

显式指定 Bean 名称。 在策略实现类上使用 @Component("alipay") 明确指定名称，避免依赖默认的类名首字母小写规则。

处理空 Map。 在 @PostConstruct 中校验 Map 是否为空，避免业务逻辑出错。

使用 @Order 控制顺序。 如果 Map 的迭代顺序重要，使用 @Order 注解控制 Bean 定义顺序。

避免过深的嵌套。 Map 嵌套层级过深会降低可读性，考虑用对象代替。

十、总结

维度	核心要点
XML 注入	使用 `<map>` 和 `<entry>`，支持简单值、Bean 引用、嵌套对象
@Value 注入	需要 SpEL 表达式 `#{${app.configs}}`，配置需内联格式
@ConfigurationProperties	原生支持复杂 Map 绑定，推荐用于配置文件
自动注入 Bean Map	key 为 Bean 名称，value 为 Bean 实例，策略模式首选
默认实现	`LinkedHashMap`，保留插入顺序
顺序控制	`@Order` 注解
空 Map 处理	默认注入空 Map，需要时用 `@PostConstruct` 校验
Map vs List	Map 按名称查找，List 按顺序遍历
最佳实践	配置绑定用 `@ConfigurationProperties`，策略模式用自动注入 Map

Map 注入是 Spring 集合注入中最灵活的形式。它通过键值对的方式，让"按名称获取"变得极其简单。特别是在策略模式中，@Autowired Map<String, Strategy> 几乎是标配用法。掌握 Map 注入的各种方式，能让你在业务开发中更加得心应手。

Spring 注入 Map 集合详解