在Spring Boot JHipster中启用CORS时出现“Failed to bind properties”错误

问题场景 #

为启用CORS，取消了application.yml中相关配置的注释，配置内容如下：

jhipster:
  clientApp:
    name: 'modelDfApp'
  # By default CORS is disabled. Uncomment to enable.
    cors:
      allowed-origins: "*"
  #   allowed-methods: "*"
  #   allowed-headers: "*"
  #   exposed-headers: "Authorization,Link,X-Total-Count,X-${jhipster.clientApp.name}-alert,X-${jhipster.clientApp.name}-error,X-${jhipster.clientApp.name}-params"
  #   allow-credentials: true
  #   max-age: 1800

注：注释部分行以缩短示例。

IntelliJ无语法报错，Maven可成功编译为Docker容器，但启动容器时出现配置绑定失败错误：

2023-06-28 13:54:19 2023-06-28T12:54:19.799Z  WARN 1 --- [           main] ConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt:
 org.springframework.context.ApplicationContextException: Unable to start web server; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'undertowServletWebServerFactory' defined in class path resource [org/springframework/boot/autoconfigure/web/servlet/ServletWebServerFactoryConfiguration$EmbeddedUndertow.class]: Initialization of bean failed; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'webConfigurer' defined in file [/app/classes/uk/modeldrivers/modeldf/config/WebConfigurer.class]: Unsatisfied dependency expressed through constructor parameter 1; nested exception is org.springframework.boot.context.properties.ConfigurationPropertiesBindException: Error creating bean with name 'jhipster-tech.jhipster.config.JHipsterProperties': Could not bind properties to 'JHipsterProperties' : prefix=jhipster, ignoreInvalidFields=false, ignoreUnknownFields=false; nested exception is org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'jhipster' to tech.jhipster.config.JHipsterProperties 
2023-06-28 13:54:19 2023-06-28T12:54:19.899Z ERROR 1 --- [           main] o.s.b.d.LoggingFailureAnalysisReporter   : ***************************APPLICATION FAILED TO START***************************
Description:
Binding to target [Bindable@6f930e0 type = tech.jhipster.config.JHipsterProperties, value = 'provided', annotations = array<Annotation>
[@org.springframework.boot.context.properties.ConfigurationProperties(ignoreInvalidFields=false, ignoreUnknownFields=false, prefix="jhipster", value="jhipster")]] failed:    

Property: jhipster.clientapp.cors.allowed-origins
    Value: "*"
    Origin: class path resource [config/application.yml] - 193:24    
Reason: The elements [jhipster.clientapp.cors.allowed-origins] were left unbound.

Action:
Update your application's configuration

解决方案 #

问题根源是YAML配置缩进错误：cors节点的缩进层级错误，它应该是clientApp的子节点，而非与clientApp同级。修正后的正确配置如下：

jhipster:
  clientApp:
    name: 'modelDfApp'
    # By default CORS is disabled. Uncomment to enable.
    cors:
      allowed-origins: "*"
      allowed-methods: "*"
      allowed-headers: "*"
      exposed-headers: "Authorization,Link,X-Total-Count,X-${jhipster.clientApp.name}-alert,X-${jhipster.clientApp.name}-error,X-${jhipster.clientApp.name}-params"
      allow-credentials: true
      max-age: 1800

修正后重启容器即可正常启动。

调试此类问题的思路 #

• 聚焦错误日志核心提示：重点关注Reason: The elements [jhipster.clientapp.cors.allowed-origins] were left unbound，这直接说明配置路径与JHipsterProperties类的属性结构不匹配
• 核对配置类结构：查看tech.jhipster.config.JHipsterProperties的源码，确认clientApp是一个内部类，包含cors属性，因此配置中cors必须嵌套在clientApp节点下
• 严格检查YAML缩进：YAML依赖缩进表示层级关系，通常用2个空格作为缩进单位，确保子节点与父节点的缩进层级正确
• 利用IDE辅助提示：添加spring-boot-configuration-processor依赖，IDE会自动生成配置元数据，提示合法的配置节点和层级
• 启用调试日志：启动应用时添加--debug参数，查看Spring Boot配置绑定的详细过程，精准定位不匹配的配置字段

内容的提问来源于stack exchange，提问作者Harper2021