Spring Boot 3.0.6中@RefreshScope配置刷新不生效问题排查

检查核心依赖匹配 #

Spring Boot 3.0.6必须搭配**Spring Cloud 2022.0.x（Kilburn）**版本，版本不兼容会直接导致刷新逻辑失效。在pom.xml（或build.gradle）中确认Spring Cloud依赖版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2022.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

同时确保引入spring-cloud-starter-config依赖，仅靠spring-cloud-starter-bootstrap不足以完成配置刷新全流程：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

修正Actuator端点配置 #

Spring Boot 3.x对Actuator端点的配置优先级和格式有调整，确保以下配置正确（建议放在application.yml中，避免bootstrap加载顺序导致的问题）：

management:
  endpoints:
    web:
      exposure:
        include: "*"  # 暴露所有端点，包括refresh
  endpoint:
    refresh:
      enabled: true  # 显式启用refresh端点

如果项目引入了Spring Security，需额外配置允许无认证访问refresh端点，否则调用时会返回401：

@Configuration
public class ActuatorSecurityConfig {
    @Bean
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
        return http.build();
    }
}

确保@RefreshScope正确使用 #

检查OpenAPIConfig类的实现，满足以下要求：

• @RefreshScope直接标注在类上，而非方法上
• @Value注入的配置字段在OpenAPI Bean创建时直接使用，未被内部缓存或静态变量持有
  示例正确写法：

@Configuration
@RefreshScope
public class OpenAPIConfig {

    @Value("${openapi.title}")
    private String title;

    @Value("${openapi.version}")
    private String version;

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title(title).version(version));
    }
}

若配置被静态变量缓存，即使触发刷新，静态变量值也不会更新，需避免此类写法。

验证配置刷新触发流程 #

1. 调用POST http://localhost:8888/actuator/refresh（注意必须是POST请求，GET请求无效）
2. 触发刷新后，检查应用日志，确认是否出现Refreshing beans in scope 'refresh'类日志，验证刷新逻辑已执行
3. 若日志无刷新记录，显式声明配置同步开关：在客户端配置中添加spring.cloud.config.refresh.enabled=true（默认开启，显式声明可规避隐式配置问题）

排查bootstrap配置加载问题 #

Spring Boot 3.x中，spring-cloud-starter-bootstrap需要显式启用bootstrap配置，在application.yml中添加：

spring:
  cloud:
    bootstrap:
      enabled: true

避免因bootstrap配置未加载，导致客户端无法感知Config Server的配置变化。

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