Spring Boot 中的 YAML 完全指南一、YAML 是什么YAML 是一种人类可读的数据序列化格式全称是 “YAML Ain’t Markup Language”。它比 properties 和 XML 更适合作为配置文件因为它使用缩进表示层级关系结构更清晰表达力更强而且支持更丰富的数据类型。Spring Boot 默认支持 YAML 格式的配置文件文件名通常是application.yml。它的设计理念是让配置文件既容易阅读也容易编写尤其适合现代微服务应用中复杂的配置场景。二、YAML 基础语法YAML 的基本结构是 key-value 对用:分隔键和值。冒号后面必须有一个空格这是 YAML 的硬性语法要求。2.1 键值对name:myappport:8080enabled:true这对应 properties 写法namemyapp port8080 enabledtrue2.2 层级结构YAML 使用缩进表示层级关系缩进必须使用空格不能使用 Tab建议统一使用 2 个空格。相同层级的元素必须左对齐。server:port:8080context-path:/apitomcat:max-threads:200uri-encoding:UTF-8对应 propertiesserver.port8080 server.context-path/api server.tomcat.max-threads200 server.tomcat.uri-encodingUTF-82.3 注释使用#表示注释# 服务器配置server:port:8080# 启动端口2.4 字符串值字符串通常不需要加引号但如果包含特殊字符如:、#、%、\n、{、}等需要用单引号或双引号包裹。# 普通字符串name:myappdescription:This is my application# 需要引号的字符串message:Hello: World# 包含冒号path:C:\Users\admin# 包含反斜杠单引号和双引号的区别单引号原样输出不转义特殊字符双引号支持转义可以使用\n、\t等single:Hello \n World# 输出Hello \n Worlddouble:Hello \n World# 输出Hello 换行 World2.5 配置重复项在 YAML 中重复的键会导致后面的值覆盖前面的值。Spring Boot 不会报错但会有日志警告。因此编写配置时要保证键的唯一性。三、YAML 支持的数据类型3.1 基本类型string-value:Hellointeger-value:100float-value:3.14boolean-value:truenull-value:null# 或 ~3.2 列表/数组方式一-列表项servers:-server1.example.com-server2.example.com-server3.example.com方式二内联写法servers:[server1.example.com,server2.example.com,server3.example.com]对应 JavaValue(${servers})privateListStringservers;3.3 Map / 对象features:cache:truelogging:falseaudit:true对应 JavaValue(#{${features}})privateMapString,Booleanfeatures;或者使用ConfigurationPropertiesComponentConfigurationProperties(prefixfeatures)publicclassFeaturesProperties{privatebooleancache;privatebooleanlogging;privatebooleanaudit;}3.4 对象列表users:-name:zhangsanage:25email:zhangsanexample.com-name:lisiage:30email:lisiexample.com对应 JavaComponentConfigurationProperties(prefixusers)publicclassUserProperties{privateListUserusers;DatapublicstaticclassUser{privateStringname;privateintage;privateStringemail;}}3.5 复杂嵌套database:primary:url:jdbc:mysql://localhost:3306/mainusername:rootpassword:123456pool:max-active:20min-idle:5secondary:url:jdbc:mysql://localhost:3306/backupusername:backuppassword:654321pool:max-active:10min-idle:2四、Spring Boot 对 YAML 的增强4.1 多文档块Profile 支持YAML 支持在一个文件中使用---分隔多个文档块每个文档块可以定义不同的 Profile 配置。# 默认配置第一个文档块server:port:8080---# 开发环境配置spring:config:activate:on-profile:devserver:port:8080logging:level:root:DEBUG---# 生产环境配置spring:config:activate:on-profile:prodserver:port:80logging:level:root:WARN上面的配置定义了三个文档块默认配置、开发环境配置Profiledev生效、生产环境配置Profileprod生效。当激活devProfile 时默认配置中的server.port会被 dev 块覆盖。4.2 占位符引用app:name:myappversion:1.0description:${app.name}-${app.version}4.3 属性引用spring:datasource:url:jdbc:mysql://localhost:3306/mydbusername:rootpassword:${spring.datasource.username}_123# 引用自身4.4 默认值和随机值app:timeout:${TIMEOUT:30}secret:${random.value}uuid:${random.uuid}五、YAML 与 properties 对比维度YAMLproperties可读性树形结构清晰易读扁平结构重复前缀多层级表达通过缩进通过.分隔列表支持原生支持-列表项使用[0]索引或逗号分隔Map 支持原生支持缩进层级支持但层级深时难以阅读多文档支持支持---分隔需要多个文件注释支持##字符串转义支持\n、\t等不支持类型推断根据值自动推断类型全部是字符串与 Spring Boot 兼容性完全兼容完全兼容适用场景复杂层级配置简单配置六、常见问题与避坑指南6.1 缩进问题YAML 对缩进非常敏感缩进不正确会导致配置解析失败或行为异常。# 错误缩进不一致server:port:8080# 4 个空格context-path:/api# 2 个空格层级错乱# 正确相同层级对齐server:port:8080context-path:/api6.2 Tab 与空格YAML 不允许使用 Tab 缩进必须使用空格。IDEA 默认将 Tab 转换为空格通常不会出问题。如果从其他地方复制配置需要检查缩进字符。6.3 列表与 Map 的解析陷阱features:cache:truelogging:false如果使用Value注入 Map必须使用 SpELValue(#{${features}})privateMapString,Booleanfeatures;如果使用ConfigurationProperties可以直接绑定。6.4 配置覆盖行为在 Spring Boot 中多个application-{profile}.yml文件共存时后加载的 profile 配置会覆盖前面的。同一个文件中的重复键也会被覆盖后面的覆盖前面的。6.5 对象列表的索引陷阱使用 properties 格式定义对象列表时必须用数字索引。而 YAML 中可以用-列表项更直观。users[0].namezhangsan users[0].age25 users[1].namelisi users[1].age30七、最佳实践优先使用 YAML 格式在配置项较多时优势明显保持缩进一致2 个空格使用ConfigurationProperties绑定复杂配置而不是用Value分散注入合理使用 Profile 管理多环境配置避免在配置文件中硬编码环境信息不要在生产配置中使用${random.value}这会破坏幂等性敏感信息使用环境变量占位符避免硬编码在 YAML 中为自定义配置添加spring-boot-configuration-processor获得 IDEA 自动补全提示八、总结YAML 是 Spring Boot 推荐的配置文件格式它让配置表达更清晰、更接近人的阅读习惯。缩进表示层级是多层配置的天然表达方式列表和对象结构比 properties 更容易书写和维护。与 properties 相比YAML 让配置文件从“扁平键值对”变为“结构化文档”更适合管理大型应用中的复杂配置。当配置层级超过两层或包含列表结构时YAML 的价值会明显体现出来。无论是小规模应用还是大规模微服务项目掌握 YAML 的语法和 Spring Boot 对其的增强特性都是必要的技能。