深入解析Spring Boot中的@ConfigurationProperties注解

深入解析Spring Boot中的@ConfigurationProperties注解

在Spring Boot框架中，配置管理是一个核心功能。Spring Boot提供了多种方式来处理外部配置，其中@ConfigurationProperties注解是一个非常强大且灵活的工具。本文将深入探讨@ConfigurationProperties注解的概念、用法、工作原理、配置绑定、类型安全以及如何在实际开发中应用它。

什么是@ConfigurationProperties？

@ConfigurationProperties是Spring Boot提供的一个注解，用于将外部配置属性绑定到Java对象上。通过使用这个注解，开发者可以将配置文件（如application.properties或application.yml）中的属性值自动映射到Java类的字段上，从而实现配置的集中管理和类型安全。

@ConfigurationProperties的作用

1. 配置绑定：将配置文件中的属性值绑定到Java类的字段上，实现配置的自动映射。
2. 类型安全：提供类型安全的配置绑定，避免类型转换错误。
3. 复杂配置：支持复杂配置结构的绑定，如嵌套对象、集合、Map等。
4. 配置校验：结合@Valid注解，实现配置属性的校验。

@ConfigurationProperties的基本用法

1. 定义配置类

首先，定义一个Java类，用于绑定配置属性。使用@ConfigurationProperties注解标记该类，并指定前缀（prefix）。

示例代码：

package com.yicrm.biz.config;


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

/**
 * <p>
 * uops-service配置
 * </p>
 *
 * @author zhaozhijun
 * @since 2026-01-07
 */

@Data
@Component
@ConfigurationProperties(prefix = "media-service")
public class MediaServiceConfig {

    //短视频路径
    private String path;

    //短视频路径-特殊租户
    private String path2;

    //直播路径
    private String broadcastPath;
    private String broadcastPath2;
    //token
    private String token;

    private String userId;

    private String companyId;
}

解释：

• @ConfigurationProperties(prefix = "app")：指定配置属性的前缀为app。
• @Component：将该类注册为Spring Bean，使其可以被Spring容器管理。

2. 配置文件

在application.properties或application.yml文件中定义配置属性。

示例代码（application.properties）：

media-service:
  path: https://***.ai/media-service/internal/dataApi/video/getCompanyCoreMetrics
  token: a5a6ae52b97f08e6847bbaf9bc054c13af797525
  userId: 3569
  companyId: 311

3. 启用配置属性支持

在Spring Boot应用的主类或配置类上，使用@EnableConfigurationProperties注解启用配置属性支持。

package com.yicrm;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

/**
 * 启动程序
 */
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
@EnableConfigurationProperties(AppProperties.class)
public class YiCrmApplication {
    public static void main(String[] args) {
        // System.setProperty("spring.devtools.restart.enabled", "false");
        // 关闭 PageHelper banner
        System.setProperty("pagehelper.banner", "false");
//        // 设置无头模式，避免在无图形界面的服务器环境中出现 X11FontManager 初始化错误
//        System.setProperty("java.awt.headless", "true");
        SpringApplication.run(YiCrmApplication.class, args);
        System.out.println("(♥◠‿◠)ﾉﾞ  YI-CRM启动成功   ლ(´ڡ`ლ)ﾞ");
    }
}