Spring Boot 属性配置文件

Spring Boot 属性配置文件

Spring Boot 的属性配置文件是项目配置的核心，支持灵活的文件格式、加载规则和数据类型，本文将从文件类型、加载顺序、配置属性类型、实际使用示例等方面全面介绍。

配置文件类型

Spring Boot 支持两种核心配置文件格式，分别是 properties（传统格式）和 yml（YAML，简洁格式），可根据项目习惯选择。

properties 格式（键值对）

传统的键值对配置方式，语法简单直观，适合简单配置场景。

# 格式：key=value
spring.application.name=springboot
spring.application.version=1.0

yml 格式（层次结构）

以数据为中心，采用缩进表示层次关系，结构清晰，适合复杂配置场景（注意：缩进必须用空格，不能用 Tab）。

spring:
  application:
    name: springboot
    version: 1.0

优先级说明

• 若项目中同时存在 properties 和 yml 文件：
  • 无配置冲突时，两者配置会自动合并；
  • 有配置冲突时，properties 优先级高于 yml（即 properties 中的配置会覆盖 yml 中同名配置）。

配置文件加载顺序

Spring Boot 会按以下顺序加载配置文件（优先级从高到低，高优先级配置会覆盖低优先级）：

1. 当前项目根目录下的 /config 子目录（./config/）
2. 当前项目根目录（./）
3. 类路径（classpath）下的 /config 子目录（classpath:/config/）
4. 类路径（classpath）根目录（classpath:/）

多环境配置

支持通过 profile 区分不同环境（如开发、测试、生产），配置文件命名规则为：application-{profile}.yml（或 properties）。

• 示例：开发环境 application-dev.yml、生产环境 application-prod.yml
• 激活方式：在主配置文件（application.yml）中添加 spring.profiles.active=dev（指定激活 dev 环境）

配置属性类型及语法

Spring Boot 支持多种数据类型的配置，包括基本类型、引用属性、数组/列表等，以下是详细示例（以 yml 格式为主）。

基本类型

支持字符串、数值、布尔型，字符串可选择是否转义。

# 字符串（直接赋值）
name: peppa

# 字符串（单引号 ''：不转义特殊字符）
name2: 'peppa\tfemale\t5'  # 输出结果：peppa\tfemale\t5（\t 不转义为制表符）

# 字符串（双引号 ""：转义特殊字符）
name3: "peppa\tfemale\t5"  # 输出结果：peppa  female  5（\t 转义为制表符）

# 引用其他属性值（通过 ${key} 引用）
intro: hello, everyone, my name is ${name}

# 数值类型（整数、小数均可）
age: 5

# 布尔型（true/false 不区分大小写）
isComputer: false

数组/列表类型

通过 - 元素值 表示数组元素。

hobby:  # 数组类型
  - football
  - basketball
  - swing

map

student:
  name: peppa
  age: 5
  gender: female
  birth: 2018-01-01  # 日期类型（Spring Boot 可自动转换为 LocalDate）
  isComputer: true
  hobby:  # 数组类型
    - football
    - basketball
    - swing

常用项目配置（示例）

server:
  port: 8080  # 配置项目启动端口（默认 8080）
  servlet:
    context-path: /springboot  # 配置项目访问根路径（默认无，访问需加 /springboot）

获取配置文件中的值（实战示例）

场景 1：通过 @Value 注解获取单个属性值

适合获取少量分散的配置属性，步骤如下：

添加 Web 依赖

需在 build.gradle 中添加 spring-boot-starter-web 依赖（支持 HTTP 接口和 Controller）：

dependencies {
    // 其他依赖...
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

编写 Controller 类

通过 @Value("${key}") 注解绑定配置属性：

package com.springboot.controller;

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

import java.util.Map;

@RestController  // 标识为 REST 接口控制器（返回 JSON 数据）
public class PropertyController {

    // 绑定配置文件中的属性（key 需与配置文件一致）
    @Value("${name}")
    private String name;

    @Value("${age}")
    private int age;

    @Value("${name2}")
    private String name2;

    @Value("${name3}")
    private String name3;

    @Value("${isComputer}")
    private boolean isComputer;

    @Value("${intro}")
    private String intro;

    // 定义接口：访问 /property 可获取配置属性
    @RequestMapping("/property")
    public Map<String, Object> getProperties() {
        return Map.of(
            "name", name,
            "age", age,
            "name2", name2,
            "name3", name3,
            "isComputer", isComputer,
            "intro", intro
        );
    }
}

测试接口

启动项目后，访问地址：http://127.0.0.1:8080/property（若配置了 context-path，则访问 http://127.0.0.1:8080/springboot/property），返回结果如下：

场景 2：通过 @ConfigurationProperties 绑定 JavaBean（批量获取）

适合获取一组相关的配置属性（如上述 student 配置），步骤如下：

编写实体类（JavaBean）

使用 @ConfigurationProperties(prefix = "前缀") 批量绑定属性，配合 Lombok 的 @Data 简化代码：

package com.springboot.entity;

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

import java.time.LocalDate;

@Data  // Lombok 注解：自动生成 getter/setter、toString 等方法
@Component  // 注册为 Spring 组件，让 Spring 管理
@ConfigurationProperties(prefix = "student")  // 绑定配置文件中前缀为 student 的属性
public class Student {
    private String name;
    private int age;
    private String gender;
    private LocalDate birth;  // 自动绑定日期格式（yyyy-MM-dd）
    private boolean isComputer;
    private String[] hobby;  // 数组类型，绑定 hobby 数组
}

改造 Controller 类

通过 @Resource 注入 JavaBean，直接返回：

package com.springboot.controller;

import com.springboot.entity.Student;
import jakarta.annotation.Resource;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PropertyController {

    // 注入 Student 组件（Spring 自动绑定配置属性）
    @Resource
    private Student student;

    @RequestMapping("/property")
    public Student getProperties() {
        return student;  // 直接返回 Student 对象（自动转为 JSON）
    }
}

测试接口

启动项目后，访问相同地址，返回结果如下：

关键说明

1. @Value 与 @ConfigurationProperties：
   • @Value：适合单个、零散的属性配置，支持 SpEL 表达式（如 ${name}）；
   • @ConfigurationProperties：适合批量、结构化的属性配置，支持自动类型转换（如日期、数组），配置有误时会有明确提示。
2. 配置文件编码：建议统一使用 UTF-8，避免中文乱码。
3. 日期格式：yml 中配置日期时，推荐使用 yyyy-MM-dd 格式，Spring Boot 可自动转换为 LocalDate 类型。