bigywater.tech
Spring · 179

Failed to bind properties:@ConfigurationProperties 的几种绑定报错,以及 ignoreUnknownFields = false 为什么对 -D 参数没反应

Failed to bind properties under … 的几种报错各长什么样?枚举写错会不会列出合法值?拼错属性名怎么发现?ignoreUnknownFields = false 对哪些来源有效?这篇在 Spring Boot 4.0.8 上逐个触发。

left unbound
ignoreUnknownFields = false 时,配置文件里的 strict.hots 启动失败(The elements [strict.hots] were left unbound.)
-D 没反应
同样的拼错 key 通过 -D 系统属性传入,StrictProps 启动成功、没有报错
5 种写法
max-size、maxSize、max_size、APP_MAXSIZE、APP_MAX_SIZE 都能绑到 maxSize

基线

实测 · 本机执行输出
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=10, tags=null]

只给 app.name,其余用默认值。

类型转换

实测 · 本机执行输出
  启动失败:BindException
    报告:Failed to bind properties under 'app.port' to int:
    报告:Property: app.port
    报告:Value: "abc"
    报告:Origin: "app.port" from property source "systemProperties"
    报告:Reason: failed to convert java.lang.String to @org.springframework.boot.context.properties.bind.DefaultValue int (caused by java.lang.NumberFormatException: For input string: "abc")
    报告:Action:
    报告:Update your application's configuration

int 字段给 abc,报告给出属性名、值与来源。

枚举

实测 · 本机执行输出
  启动失败:BindException
    报告:Failed to bind properties under 'app.color' to demo.Color:
    报告:Property: app.color
    报告:Value: "PURPLE"
    报告:Origin: "app.color" from property source "systemProperties"
    报告:Reason: failed to convert java.lang.String to @org.springframework.boot.context.properties.bind.DefaultValue demo.Color (caused by java.lang.IllegalArgumentException: No enum constant demo.Color.PURPL
    报告:Action:
    报告:Update your application's configuration. The following values are valid:
    报告:GREEN
    报告:RED

报告列出合法取值。

Duration

实测 · 本机执行输出
  启动失败:BindException
    报告:Failed to bind properties under 'app.timeout' to java.time.Duration:
    报告:Property: app.timeout
    报告:Value: "10x"
    报告:Origin: "app.timeout" from property source "systemProperties"
    报告:Reason: failed to convert java.lang.String to @org.springframework.boot.context.properties.bind.DefaultValue java.time.Duration (caused by java.lang.IllegalArgumentException: Unknown unit 'x')
    报告:Action:
    报告:Update your application's configuration

只指出 Unknown unit。

校验

实测 · 本机执行输出
  启动失败:BindException
    报告:Binding to target demo.AppProps failed:
    报告:Property: app.maxSize
    报告:Value: "0"
    报告:Origin: "app.max-size" from property source "systemProperties"
    报告:Reason: must be greater than or equal to 1
    报告:Action:
    报告:Update your application's configuration
  -- 同一节的另一组
  启动失败:BindException
    报告:Binding to target demo.AppProps failed:
    报告:Property: app.name
    报告:Value: ""
    报告:Origin: "app.name" from property source "systemProperties"
    报告:Reason: must not be blank
    报告:Action:
    报告:Update your application's configuration

@Min 与 @NotBlank 的报告。

拼错属性名

实测 · 本机执行输出
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=10, tags=null]
  -- 同一节的另一组
  启动失败:BindException
    报告:Binding to target [Bindable@… type = demo.StrictProps, value = 'none', annotations = array<Annotation>[@org.springframework.boot.context.properties.ConfigurationProperties(ignoreInvalidFields=false, i
    报告:Property: strict.hots
    报告:Value: "h"
    报告:Origin: URL [file:<源码> - 1:13
    报告:Reason: The elements [strict.hots] were left unbound.
    报告:Action:
    报告:Update your application's configuration
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=10, tags=null]

默认静默忽略;strict 对配置文件有效,对 -D 无效。

宽松绑定

实测 · 本机执行输出
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=21, tags=null]
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=22, tags=null]
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=23, tags=null]
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=24, tags=null]
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=25, tags=null]

五种写法都行。

列表

实测 · 本机执行输出
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=10, tags=[a, b]]
  -- 同一节的另一组
  启动成功:AppProps[port=8080, name=demo, timeout=PT5S, color=RED, maxSize=10, tags=[x, y]]

下标写法与逗号写法。

分步演示

BindError
本步的对象

    本文用到的工具与边界

    • 本机 macOS 27 arm64 / OpenJDK 21.0.12(Homebrew) / Spring Boot 4.0.8(Spring Framework 7.0.9、Tomcat 11.0.24) / Spring Cloud 2025.1.3;用 javac 编译、java 直接运行,依赖由 Maven 从 Maven Central 解析;数字每次运行会有小幅抖动(Spring Boot 4.0.8 的 spring-boot 与 spring-boot-starter-validation,不带 Web;配置类是 record,用 @DefaultValue 给默认值;「配置文件」指通过 spring.config.additional-location 指向的 .properties 文件;其余情形用 -D 系统属性或环境变量;FailureAnalyzer 的报告靠 logback ERROR 级别打印)
    • 没有验证:ignoreUnknownFields = false 对环境变量、命令行参数这些来源是否有效(只试了 -D 与配置文件);@ConfigurationProperties 用 JavaBean setter 绑定与构造器绑定在报错上的差别;嵌套对象缺失时的行为;Map 类型的绑定;YAML 文件里的同类错误;@ConfigurationPropertiesScan;Boot 3.5 下的对照
    京ICP备2026067502号-1京公网安备11010502063487号