Spring Boot 配置文件深度解析：Properties 与 YAML 实战

运行效果：

3.3 properties 缺点

properties 配置是以 key-value 的形式配置的，如下图所示：

从上述配置 key 看出，properties 配置文件中会有很多的冗余的信息，比如这些：

想要解决这个问题，就得使用 yml 配置文件的格式化。

4. YAML (YML) 进阶指南

YAML 是一种树形结构的标记语言，通过缩进表示层级。

4.1 核心语法规范

1. 冒号空格：key 和 value 之间必须有 英文冒号 + 空格，空格不可省略。
2. 数据类型支持：支持字符串、布尔值、整数、浮点数以及 null（用 ~ 表示）。

单层级与多层级的表示规则

多层级的 key 前面要空两个格，且同级需对齐！

4.2 yaml 语法与读取示例

yaml 文件配置如下

Java 代码读取配置信息

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/yaml")
@RestController
public class YamlController {
    @Value("${yaml}")
    private String yaml;
    
    @Value("${spring.datasource.username}")
    private String username;
    
    @Value("${spring.datasource.password}")
    private String password;

    @RequestMapping("/read")
    public String read() {
        System.out.println(yaml);
        System.out.println(username);
        System.out.println(password);
        return "success";
    }
}

运行结果

打印配置

4.3 字符串的引号差异

YAML 中字符串默认不加引号，但单双引号有本质区别：

• 单引号 ('')：会转义特殊字符，使其变为普通字符串（如 \n 输出为字符 \n）
• 双引号 ("")：不会转义特殊字符，保留其本身含义（如 \n 输出为换行）

4.4 对象、集合与 Map 的读取

配置对象

YML 配置示例：

student:
  id: 1
  name: Java
  age: 18

Java 实体类映射： 对于复杂数据形态，建议使用 @ConfigurationProperties 注解。

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@ConfigurationProperties(prefix = "student") // 会从配置文件中找到 student 的前缀
@Component
public class Student {
    private Integer id;
    private String name;
    private Integer age;
}

运行打印结果

配置集合

YML 配置示例：

dbtypes:
  name:
    - mysql
    - sqlserver
    - db2
  map:
    k1: kk1
    k2: kk2
    k3: kk3

Java 实体类映射： 对于复杂数据形态，建议使用 @ConfigurationProperties 注解。

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.Map;

@Data
@ConfigurationProperties(prefix = "dbtypes")
@Component
public class DbTypeConfig {
    private List<String> name;
    private Map<String, String> map;
}

运行打印结果

5. 综合性练习：验证码案例实战

本案例基于 Hutool 第三方工具包实现一个后端生成、校验验证码的功能。

5.1 需求分析

1. 后端生成验证码图片并返回流。
2. 将验证码及其生成时间存入 Session。
3. 用户提交验证码，后端校验一致性及有效期（1 分钟内有效）。

5.2 约定前后端交互接口

接口定义

1. 生成验证码 请求 URL:/captcha/getCaptcha 响应：验证码图片内容

校验验证码是否正确 请求:/captcha/check

请求 URL:/captcha/check 请求参数：captcha=xn8d 

响应:true 根据用户输入的验证码，校验验证码是否正确。true:验证成功.false:验证失败.

配置文件定义 (解决硬编码问题)

在 application.yml 中定义验证码的尺寸及 Session 的 Key：

spring:
  application:
    name: spring-captcha-demo
  captcha:
    width: 100
    height: 40
  session:
    code: SESSION_CODE_KEY
    date: SESSION_DATE_KEY

验证码相关接口

import cn.hutool.captcha.CaptchaUtil;
import cn.hutool.captcha.LineCaptcha;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpSession;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.IOException;

@RestController
@RequestMapping("/captcha")
public class CaptchaController {
    @Autowired
    private CaptchaProperties captchaProperties;

    private static long VALID_MILLIS_TIME = 5 * 60 * 1000;

    @RequestMapping("/getCaptcha")
    public void genCaptcha(HttpServletRequest request, HttpServletResponse response) {
        // 定义图形验证码的长和宽
        LineCaptcha lineCaptcha = CaptchaUtil.createLineCaptcha(captchaProperties.getWidth(), captchaProperties.getHeight());
        String code = lineCaptcha.getCode();
        System.out.println(code);
        // 图形验证码写出，可以写出到文件，也可以写出到流
        try {
            response.setContentType("image/jpeg");
            response.setHeader("Pragma", "No-cache");
            lineCaptcha.write(response.getOutputStream());
            // 拿到这个请求的 session，并且将 code 写入到 session
            HttpSession session = request.getSession();
            session.setAttribute(captchaProperties.getSession().getCode(), code);
            // 记录时间保持五分钟内有效
            session.setAttribute(captchaProperties.getSession().getDate(), System.currentTimeMillis());
            response.getOutputStream().close();
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    @RequestMapping("/check")
    public Boolean checkCaptcha(String captcha, HttpSession session) {
        // 先判断是否为空
        if (!StringUtils.hasLength(captcha)) {
            return false;
        }
        // 从 session 中获取 code 和时间
        Object codeObj = session.getAttribute(captchaProperties.getSession().getCode());
        if (codeObj == null) return false;
        String code = codeObj.toString();
        long timestamp = (long) session.getAttribute(captchaProperties.getSession().getDate());
        if (captcha.equalsIgnoreCase(code) && (System.currentTimeMillis() - timestamp < VALID_MILLIS_TIME)) {
            return true;
        }
        return false;
    }
}

前端相关代码

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>验证码</title>
    <style>
        #inputCaptcha { height: 30px; vertical-align: middle; }
        #verificationCodeImg { vertical-align: middle; }
        #checkCaptcha { height: 40px; width: 100px; }
    </style>
</head>
<body>
    <h1>输入验证码</h1>
    <div id="confirm">
        <input type="text" name="inputCaptcha" id="inputCaptcha">
        <img id="verificationCodeImg" src="/captcha/getCaptcha" style="cursor: pointer;" title="看不清？换一张"/>
        <input type="button" value="提交" id="checkCaptcha">
    </div>
    <script src="https://cdn.bootcdn.net/ajax/libs/jquery/3.6.4/jquery.min.js"></script>
    <script>
        $("#verificationCodeImg").click(function(){
            $(this).hide().attr('src','/captcha/getCaptcha?dt='+new Date().getTime()).fadeIn();
        });
        $("#checkCaptcha").click(function(){
            $.ajax({
                url:'/captcha/check',
                type:'post',
                data:{ captcha:$('#inputCaptcha').val()},
                success:function(result){
                    if(result){
                        location.href ='success.html';
                    }else{
                        alert("验证码错误！");
                    }
                }
            });
        });
    </script>
</body>
</html>

运行结果

6. 总结

• Properties 语法简单但存在冗余，适用于简单项目。
• YAML 结构清晰、支持类型丰富，是目前 Spring Boot 开发的主流选择。
• 读取技巧：简单配置用 @Value，结构化配置（对象/集合）首选 @ConfigurationProperties。
• 建议：yml 可以和 properties 共存，但一个项目中建议只使用一种配置类型文件

参考链接：

• Spring Boot 官方外部配置文档
• Hutool 第三方工具地址