YAML配置详解：SpringBoot实战指南

一、引言

在之前的三篇文章里，我们从 SpringBoot 快速上手，讲到 SpringMVC 的请求处理，再到 Spring 的 IoC 与 DI。你会发现一个规律：SpringBoot 之所以能「开箱即用」，靠的是「约定大于配置」------但约定归约定，真正让我们能随心所欲控制项目的，是那一份份配置文件。

修改端口号、连接数据库、切换开发/生产环境、注入自定义业务参数......这些高频操作都发生在配置文件里。SpringBoot 同时支持 application.properties 和 application.yml 两种格式，而其中 **YAML（yml）** 凭借其简洁直观的层级结构，已成为事实上的主流选择。

本文将带你系统掌握 SpringBoot 配置文件，重点讲解 yml 的语法与实战用法。

二、配置文件概述

SpringBoot 项目创建后，src/main/resources 目录下默认会有一个 application.properties 文件。它是全局配置文件，名字是固定的，SpringBoot 启动时会自动加载。

我们也可以把它改成 application.yml，两者选其一即可（若同时存在，properties 优先级更高）。

两种格式对比如下：

properties

复制代码

# application.properties
server.port=8080
server.servlet.context-path=/demo
spring.datasource.username=root

yaml

复制代码

# application.yml
server:
  port: 8080
  servlet:
    context-path: /demo
spring:
  datasource:
    username: root

可以明显看到：yml 用缩进表达层级关系，可读性更好，且天然支持对象、数组等复杂结构。接下来我们重点看 yml。

三、YAML 语法详解

3.1 基本语法规则

大小写敏感。
使用缩进表示层级关系，缩进只能用空格，不能用 Tab 键（这是新手最常犯的错误）。
缩进的空格数不强制，但同一层级必须左对齐。
key: value 冒号后面必须有一个空格（同样不能省略）。

yaml

复制代码

# ✅ 正确写法
name: 张三
age: 18
# ❌ 错误写法：冒号后无空格
name:张三

3.2 三种数据结构的写法

**① 字面量（字符串、数字、布尔值等）**

yaml

复制代码

name: tom          # 字符串，可不加引号
age: 25            # 数字
flag: true         # 布尔

注意：字符串默认不需要引号，但若值中包含特殊字符（如 \n 想当作普通字符），可用单引号包裹；双引号则会对特殊字符进行转义。

yaml

复制代码

str1: 'hello \n world'   # 原样输出 hello \n world
str2: "hello \n world"   # 输出时 \n 转义为换行

**② 对象（Map）**

yaml

复制代码

person:
  name: tom
  age: 25

也可以写成行内形式（较少用）：

yaml

复制代码

person: {name: tom, age: 25}

**③ 数组（List）**

yaml

复制代码

hobby:
  - 篮球
  - 足球
  - 羽毛球

或者行内写法：

yaml

复制代码

hobby: [篮球, 足球, 羽毛球]

数组里放对象的组合写法：

yaml

复制代码

students:
  - name: 张三
    age: 18
  - name: 李四
    age: 20

3.3 占位符引用

yml 里可以通过 ${} 引用前面定义的属性，也可以引用系统属性：

yaml

复制代码

app:
  name: demo
  desc: 这是${app.name}项目
  java-home: ${JAVA_HOME}

四、配置文件的加载顺序与优先级

SpringBoot 会按固定顺序扫描配置文件，优先级从高到低大致为：

命令行参数（--server.port=9090，优先级最高）
项目根目录下的 config/application.yml
项目根目录下的 application.yml
classpath:/config/application.yml
classpath:/application.yml（即 resources 下，优先级最低）

简单记：外层的覆盖内层的，config 目录的覆盖非 config 目录的，properties 覆盖 yml。实际开发中，我们最常用的还是 resources 下的那份。

五、读取配置的三种方式

5.1 使用 @Value 注解

适用于读取单个简单值：

yaml

复制代码

# application.yml
user:
  name: tom
  age: 25

java

复制代码

@RestController
public class HelloController {

    @Value("${user.name}")
    private String name;

    @Value("${user.age}")
    private Integer age;

    @GetMapping("/hello")
    public String hello() {
        return "姓名：" + name + "，年龄：" + age;
    }
}

5.2 使用 @ConfigurationProperties

@Value 一个一个取值比较繁琐，@ConfigurationProperties 可以把一组配置批量注入到一个 JavaBean 里，是更推荐的做法。

java

复制代码

@Component
@ConfigurationProperties(prefix = "user")
public class User {
    private String name;
    private Integer age;
    // 省略 getter / setter
}

yaml

复制代码

user:
  name: tom
  age: 25

使用时直接 @Autowired 注入即可：

java

复制代码

@RestController
public class HelloController {

    @Autowired
    private User user;

    @GetMapping("/hello")
    public String hello() {
        return "姓名：" + user.getName() + "，年龄：" + user.getAge();
    }
}

提示：SpringBoot 2.2 之后推荐在配置类上加 @EnableConfigurationProperties 或给类加 @ConfigurationProperties + @Component。若编译期提示需要注解处理器，可在 pom.xml 加入 spring-boot-configuration-processor 依赖，以获得书写提示。

5.3 使用 Environment 对象

适合动态、不确定 key 的场景：

java

复制代码

@RestController
public class HelloController {

    @Autowired
    private Environment environment;

    @GetMapping("/port")
    public String port() {
        return "端口：" + environment.getProperty("server.port");
    }
}

六、多环境配置（Profile）

实际开发中，开发环境、测试环境、生产环境的配置往往不同。SpringBoot 用 profile 机制优雅地解决这个问题。

约定命名：application-{profile}.yml，例如：

application-dev.yml：开发环境
application-test.yml：测试环境
application-prod.yml：生产环境

在主配置 application.yml 里用 spring.profiles.active 指定激活哪个环境：

yaml

复制代码

# application.yml
spring:
  profiles:
    active: dev   # 激活 dev 环境

yaml

复制代码

# application-dev.yml
server:
  port: 8080

yaml

复制代码

# application-prod.yml
server:
  port: 80

切换环境只需改一行 active，非常方便。也可以用命令行临时覆盖：java -jar app.jar --spring.profiles.active=prod。

七、常见配置示例

下面给出一份贴合实际开发的配置片段（数据库部分为下一篇 Mybatis 做铺垫）：

yaml

复制代码

server:
  port: 8080
  servlet:
    context-path: /book   # 全局访问前缀

spring:
  application:
    name: book-manager
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/book_db?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
  profiles:
    active: dev

logging:
  level:
    com.example: debug   # 指定包日志级别

八、总结

本文围绕 SpringBoot 配置文件，重点梳理了 yml 的语法规则与数据结构写法 ，并对比了 properties 与 yml 的差异；随后介绍了配置的加载优先级、读取配置的三种方式（@Value、@ConfigurationProperties、Environment），以及多环境 profile 切换的实战用法。

掌握这些后，下一篇我们正式进入持久层框架 Mybatis 的学习，届时数据库连接配置、映射文件等都会用到今天的内容。核心要点回顾：

yml 靠缩进表达层级，冒号后要加空格，不能用 Tab。
批量注入配置优先用 @ConfigurationProperties。
多环境用 application-{profile}.yml + spring.profiles.active 切换。