如何在 YAML 中为 POJO 定义 Map 配置

1. 概述

本文将演示如何通过 YAML 配置文件，为 Java 的 POJO 类中的 Map 字段注入配置值。这在 Spring Boot 项目中非常常见，尤其适用于多环境、多区域的配置管理。

核心机制依赖于 @ConfigurationProperties 注解，它能自动将 YAML 中的层级结构绑定到 Java 对象的 Map 字段中，简单粗暴又实用。

2. POJO 与 YAML 配置映射

POJO（Plain Old Java Object）是标准的 Java 配置类。YAML 是一种结构清晰、可读性强的配置格式，通过缩进表示层级关系，广泛用于 Spring Boot 的 application.yml 文件。

2.1 简单 Map 示例

假设我们正在开发一个服装电商系统，需要支持尺码映射。初期只面向英国市场，我们要将“S”、“M”、“L”等标签映射为具体的 UK 尺码数值。

定义配置类如下：

@ConfigurationProperties(prefix = "t-shirt-size")
public class TshirtSizeConfig {

    private Map<String, Integer> simpleMapping;

    public TshirtSizeConfig(Map<String, Integer> simpleMapping) {
        this.simpleMapping = simpleMapping;
    }

    // getters and setters...
}

⚠️ 注意：

@ConfigurationProperties 的 prefix 指定了 YAML 中的配置前缀。
必须在主应用类上启用该功能，否则不会生效。

启用方式如下：

@EnableConfigurationProperties(TshirtSizeConfig.class)
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

✅ 推荐做法：也可以使用 @ConfigurationPropertiesScan 替代，更简洁。

2.2 YAML 配置写法

在 application.yml 中添加对应配置：

t-shirt-size:
  simple-mapping:
    XS: 6
    S:  8
    M:  10
    L:  12
    XL: 14

关键细节：

缩进必须使用空格（推荐 2 个），不能用 Tab
simple-mapping 是 kebab-case（短横线命名），会自动映射到 Java 中的 simpleMapping（驼峰命名）
YAML 的键值对结构天然适合 Map 的 key-value 形式

踩坑提醒：缩进错误是 YAML 最常见的报错原因，务必检查空格一致性。

2.3 复杂嵌套 Map 示例

随着业务扩展，我们需要支持多国尺码转换，比如同一个“S”在英国是 8，在法国是 36，在美国是 4。此时需要二维映射结构。

更新 application.yml：

t-shirt-size:
  complex-mapping:
    XS:
      uk: 6
      fr: 34
      us: 2
    S:
      uk: 8
      fr: 36
      us: 4
    M:
      uk: 10
      fr: 38
      us: 6
    L:
      uk: 12
      fr: 40
      us: 8
    XL:
      uk: 14
      fr: 42
      us: 10

对应的 POJO 字段应声明为 Map<String, Map<String, Integer>>：

private Map<String, Map<String, Integer>> complexMapping;

结构解析：

外层 key：衣服尺码标签（如 "S"）
内层 key：国家代码（如 "uk", "fr"）
值：对应国家的具体尺码数值

✅ 这种结构非常适合做国际化配置、多区域映射等场景。

3. 总结

本文展示了如何在 Spring Boot 中通过 YAML 文件为 POJO 配置 Map 类型字段，涵盖：

✅ 简单 Map 映射（String → Integer）
✅ 嵌套 Map 映射（String → Map<String, Integer>）
✅ YAML 缩进与命名转换规则（kebab-case → camelCase）
✅ 必要的注解启用（@EnableConfigurationProperties）

示例代码已托管至 GitHub：https://github.com/baeldung/tutorials/tree/master/spring-boot-modules/spring-boot-properties-3

Persistence

REST

Security