Spring Boot 配置文件实战：从 Properties 到 YAML 的取舍

看上图，spring.datasource 这一大串反复出现，读起来很累：

要解决这个冗余，YAML 的树形结构就舒服多了。

YAML 语法与读取

YAML 靠缩进表达层级，键值对中间必须有英文冒号加空格，忘加空格解析直接失败。基本规则如图：

单层级和多层级的缩进区别：

多层级时每层缩进两个空格，同一级必须对齐。

yml 配置示例：

读取方式同样用 @Value：

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";
    }
}

调用接口后的输出：

控制台打印的配置值：

字符串引号的坑

YAML 字符串默认可以不加引号，但单引号和双引号的行为不一样：

• 单引号 ''：特殊字符会被转义，比如 \n 就当普通字符输出了。
• 双引号 ""：保留特殊字符原意，\n 就是换行。

对象、集合和 Map 的绑定

配置对象

student:
  id: 1
  name: Java
  age: 18

用 @ConfigurationProperties 映射到 bean：

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

@Data
@ConfigurationProperties(prefix = "student")
@Component
public class Student {
    private Integer id;
    private String name;
    private Integer age;
}

绑定后的打印结果：

配置集合

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

绑定类：

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;
}

运行效果：

综合练习：验证码功能

下面通过一个验证码接口演示配置到底怎么用。需求很简单：后端生成图形验证码，存入 session，校验时判断一致性以及是否超时（一分钟）。把宽、高、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 = 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());
            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;
        }
        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>

最终运行效果：

Properties 上手快，但项目一大键名就臃肿；YAML 结构好读，适合复杂配置，只是需要注意空格。取值时，单个参数用 @Value，要是一组相关配置就绑到 @ConfigurationProperties，代码干净很多。

参考链接：

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