# 问题引入

在[SpringBoot自动配置原理](https://zhuanlan.zhihu.com/p/1988997229546053679)我们介绍了SpringBoot怎么自动加载配置类。

自动配置，通常需要读取配置文件，SpringBoot有没有提供什么便捷的方法来获取配置吗？

答案是有的，SpringBoot提供了`@ConfigurationProperties`注解。

可以把@ConfigurationProperties看做是对@Value的增强，可以处理很多复杂的配置，支持复杂类型和全套。

例如，Spring Gateway的路由配置这种比较复杂的配置。

理解属性自动配置，就不用遇到这类问题我们就能轻松搞定。

对于，一些复杂配置，我们也能快速通过源码来看怎么配置。

# 使用模式

定制属性类，通过前缀来避免混淆，也容易分组。

```java
@ConfigurationProperties(prefix = "mybatis")
public class MybatisProperties {

  private String configLocation;

  private String[] mapperLocations;
}
```

还有我们常用的spring.datasource：

```java
@ConfigurationProperties(prefix = "spring.datasource")
public class DataSourceProperties implements BeanClassLoaderAware, InitializingBean {
}
```

在自动配置类中导入配置属性类：

```java
@EnableConfigurationProperties(MybatisProperties.class)
public class MybatisAutoConfiguration implements InitializingBean {

  private final MybatisProperties properties;
} 
```

# @ConfigurationProperties对复杂类型的支持


## 完整示例

先来看完整示例，后面再单独介绍。

配置文件application.yaml：

```yaml
config:
  color: RED
  list:
    - "a"
    - "a"
    - "b"
  set:
    - "a"
    - "b"
    - "b"
  map:
    a: 1
    b: 2
    c: 3
  birthday: 2050-01-01
  nest:
    name: "nest"
    age: 20
  custom-list:
    - Path=/api/normal/**
    - Header=Authorization=Bearer
  complex-nest:
    - name: "c1"
      nodes:
        - name: "node-1"
          port: 8080
          host: "192.168.12.10"
        - name: "node-2"
          port: 8081
          host: "192.168.12.11"
    - name: "c2"
      nodes:
        - name: "node-2"
          port: 8080
          host: "192.168.10.11"
        - name: "node-2"
          port: 8081
          host: "192.168.10.12"
```

配置类：

```java
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import java.util.Set;

@Data
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private Color color;

    private List<String> list;

    private Set<String> set;

    private Map<String, Integer> map;

    private LocalDate birthday;

    private Nest nest;

    private List<NameValue> customList;

    private List<ComplexNest> complexNest;

    public static enum Color {
        RED, BLUE
    }

    @Data
    public static class Nest {
        private String name;
        private Integer age;
    }

    @Data
    public static class Node {
        private String name;
        private Integer port;
        private String host;
    }

    @Data
    public static class ComplexNest {
        private String name;
        private List<Node> nodes;
    }

    @Data
    public static class NameValue{
        private String name;
        private String value;
    }

}
```

## 枚举

```yaml
config:
  color: RED
```

这类为了方便看，枚举定义成了内部类，不是必须为内部类，通常是定义在外部。

```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private Color color;

    public static enum Color {
        RED, BLUE
    }
}
```

## list set

list set配置中用数组就可以：

```yaml
config:
  list:
    - "a"
    - "a"
    - "b"
  set:
    - "a"
    - "b"
    - "b"
```

会自动处理为对应的类型：

```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private List<String> list;

    private Set<String> set;
}
```

## map

注意，map在yaml配置中不是数组，而是对象，使用的是:没有-

```yaml
config:
  map:
    a: 1
    b: 2
    c: 3
```

```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private Map<String, Integer> map;
}
```

## 嵌套类型

对象可以嵌套，例如Spring发现nest是一个对象，就会自动用nest的下一级属性去装配Nest对象的属性

```yaml
config:
  nest:
    name: "nest"
    age: 20
```

```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private Nest nest;

    @Data
    public static class Nest {
        private String name;
        private Integer age;
    }
}
```

![1-Spring属性自动配置嵌套对象.png](https://developer.qcloudimg.com/http-save/yehe-5417028/6784cb4f2897fa189ffa708b8670abb5.png)

## 复杂嵌套

对于复杂的嵌套，清楚它的层级就可以，每个层级的属性对应就没有问题。

```yaml
config:
  complex-nest:
    - name: "c1"
      nodes:
        - name: "node-1"
          port: 8080
          host: "192.168.12.10"
        - name: "node-2"
          port: 8081
          host: "192.168.12.11"
    - name: "c2"
      nodes:
        - name: "node-2"
          port: 8080
          host: "192.168.10.11"
        - name: "node-2"
          port: 8081
          host: "192.168.10.12"
```

complexNest是一个List，每个元素都是ComplexNest

每一个ComplexNest都有一个name和一个Node List

每一个Node层级又有一个name，port，host属性


```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private List<ComplexNest> complexNest;

    @Data
    public static class Node {
        private String name;
        private Integer port;
        private String host;
    }

    @Data
    public static class ComplexNest {
        private String name;
        private List<Node> nodes;
    }
}
```


# @ConfigurationProperties原理

@ConfigurationProperties处理逻辑非常复杂，这里简单说一下关键点：

@ConfigurationProperties的核心处理逻辑在ConfigurationPropertiesBindingPostProcessor中。


ConfigurationPropertiesBindingPostProcessor有Binder(org.springframework.boot.context.properties.bind.Binder),它会可以做格式化话和数据类型转换。

其中数据转换主要有下面几个类型：

1. Converter<S,T>
2. ConverterFactory<S,R>
3. GenericConverter
4. PropertyEditor

实际上是通过多个ConversionService统一管理：

![7-conversionService.png](https://developer.qcloudimg.com/http-save/yehe-5417028/386e108ad13b34bcee06434e9ea3dd21.png)

我们能把配置文件中一个简单的String转换为对应的类型，就是类型转换系统的功劳。

例如:birthday: 2050-01-01(String)-->private LocalDate birthday;

执行String到LocalDate转换的转换器为：org.springframework.format.support.FormattingConversionService.ParserConverter

# 自定义类型转换器

如果有朋友尝试过上面的我们的测试代码，大概率会得到一个如下异常：

```txt
Failed to bind properties under 'config.custom-list[0]' to vip.oschool.property.CustomProperties$NameValue:

Reason: org.springframework.core.convert.ConverterNotFoundException: No converter found capable of converting from type [java.lang.String] to type [vip.oschool.property.CustomProperties$NameValue]
```

为什么呢？

因为Spring默认带有的转换器，不能把Path=/api/normal/**这样的String转换为NameValue类型。

```yaml
config:
  custom-list:
    - Path=/api/normal/**
    - Header=Authorization=Bearer
```

```java
@ConfigurationProperties(prefix = "config")
public class CustomProperties {

    private List<NameValue> customList;

    @Data
    public static class NameValue{
        private String name;
        private String value;
    }
}
```

怎么办呢？

我们可以自定义类型转换器。

这里是一个简单的转换，我们实现Converter就可以：

```java
import org.springframework.boot.context.properties.ConfigurationPropertiesBinding;
import org.springframework.core.convert.converter.Converter;
import org.springframework.stereotype.Component;

@Component
@ConfigurationPropertiesBinding
public class StringToNameValueConverter implements Converter<String, CustomProperties.NameValue> {
    @Override
    public CustomProperties.NameValue convert(String source) {
        String[] split = source.split("=");
        CustomProperties.NameValue nameValue = new CustomProperties.NameValue();
        nameValue.setName(split[0]);
        nameValue.setValue(split[1]);
        return nameValue;
    }
}
```

@ConfigurationPropertiesBinding是说明这个转换器就是用于属性绑定的转换器。

![2-自动配置属性.png](https://developer.qcloudimg.com/http-save/yehe-5417028/c5b313e510513b781683fdd95120983d.png)

注意，如果只有@ConfigurationProperties，需要EnableConfigurationProperties注解，否则无法生效。

```java
@SpringBootApplication
@EnableConfigurationProperties({CustomProperties.class, DataProperties.class})
public class BaseServiceApp {
    public static void main(String[] args) {
        SpringApplication.run(BaseServiceApp.class, args);
    }
}
```

# 属性配置实践

## 查找配置项

因为属性配置非常多，很多时候，我们根本记不完，怎么办呢？

只要我们自动自动配置原理，结合本会的属性自动配置，我们就能轻松的查找配置项。

不清楚自动配置原理的，可以看看：[SpringBoot自动配置原理](https://zhuanlan.zhihu.com/p/1988997229546053679)

找@EnableConfigurationProperties、@ConfigurationProperties

另外通常会有一个自动配置的项目：autoconfigure，去搜索对应的配置项，就能找到对应的配置类。

![3-自动配置配置项.png](https://developer.qcloudimg.com/http-save/yehe-5417028/8376171df0b2e6739763dec9e9f5ee32.png)

## 问题排查

有些自定义的转换，我们不知道规则，试了出错了，怎么排查错误呢？

例如：

```yaml
spring:
  servlet:
    multipart:
      max-file-size: 10M
      max-request-size: 30M
```

```txt
Failed to bind properties under 'spring.servlet.multipart.max-file-size' to org.springframework.util.unit.DataSize:

Property: spring.servlet.multipart.max-file-size
Value: "10M"
Origin: class path resource [application.yaml] - 45:22
Reason: failed to convert java.lang.String to org.springframework.util.unit.DataSize (caused by java.lang.IllegalArgumentException: Unknown data unit suffix 'M')
```

![4-对应包搜索.png](https://developer.qcloudimg.com/http-save/yehe-5417028/babfbe3b8ae4cc4f01ad49ceec62bdd0.png)

找到对应属性类型：

![5-找到对应属性类型.png](https://developer.qcloudimg.com/http-save/yehe-5417028/1247a7bf2c179910cee15c416ee5dd6a.png)

例如，上面，我们知道了是DataSize类型，那么我们就去找对应的转换器


去找Converter<S,T>、GenericConverter等的具体实现类。

![6-具体转换器的实现逻辑.png](https://developer.qcloudimg.com/http-save/yehe-5417028/81946cb467c70be09db97029cb28d97c.png)

看到具体的逻辑org.springframework.util.unit.DataSize#parse(java.lang.CharSequence, org.springframework.util.unit.DataUnit)我们都不用看代码，看一下注释就知道，原来不支持M，只支持MB。

这样，我们就学到了，以后如果我们自己需要数据大小限制就可以不使用long类型，直接使用DataSize类型，这样配置就非常灵活了，Spring直接就帮我们支持了。

在SpringBoot自动配置原理我们介绍了SpringBoot怎么自动加载配置类。

Spring属性自动配置原理与自定义转换

后端

编程语言

架构设计

SpringBoot的@ConfigurationProperties注解详解，支持复杂类型配置绑定，包括枚举、List、Set、Map及嵌套对象。通过prefix前缀分组配置，结合自定义转换器实现灵活配置。掌握该注解可简化SpringBoot应用配置管理，提升开发效率。

数据转换

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Spring属性自动配置原理与自定义转换-腾讯云开发者社区-腾讯云

Spring属性自动配置原理与自定义转换

Spring属性自动配置原理与自定义转换

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐