Spring Boot 多模块项目中 IDEA 提示 Cannot resolve symbol 的一次排查记录

背景

在开发 FlashRisk 高并发交易风控与异步结算平台时，项目采用 Maven 多模块结构，包含多个 Spring Boot 微服务：

user-service
campaign-service
order-service
risk-settlement-service
ops-assistant-service
gateway-service

在 IDEA 中启动 ops-assistant-service 时，启动类出现红色报错：

Cannot resolve symbol 'OpsAssistantProperties'
Unused import statement
Typo: In word 'flashrisk'

对应代码如下：

package com.flashrisk.opsassistant;

import com.flashrisk.opsassistant.config.OpsAssistantProperties;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication(scanBasePackages = "com.flashrisk")
@EnableConfigurationProperties(OpsAssistantProperties.class)
public class OpsAssistantServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(OpsAssistantServiceApplication.class, args);
    }
}

现象分析

其他服务都能正常启动，只有 ops-assistant-service 报错。

对比其他服务启动类可以发现，它们通常是这样的：

@SpringBootApplication(scanBasePackages = "com.flashrisk")
public class UserServiceApplication {
}

或者：

@EnableFeignClients(basePackages = "com.flashrisk.order.client")
@MapperScan({"com.flashrisk.order.mapper", "com.flashrisk.order.outbox.mapper"})
@EnableScheduling
@SpringBootApplication(scanBasePackages = "com.flashrisk")
public class OrderServiceApplication {
}

它们没有直接 import 本模块的配置类。

而 ops-assistant-service 原写法中显式引用了：

OpsAssistantProperties.class

所以一旦 IDEA 的 Maven 多模块索引没有刷新，或者模块源码目录没有被正确识别，就会在这里暴露出：

Cannot resolve symbol 'OpsAssistantProperties'

关键判断

这个问题不一定是 Java 代码真的编译失败。

可以通过 Maven 验证：

mvn -q -pl ops-assistant-service -am test

如果 Maven 编译和测试能通过，说明：

OpsAssistantProperties.java 文件真实存在；
包名和路径没有问题；
依赖关系没有问题；
IDEA 的红线更可能是索引或模块识别问题。

Typo: In word 'flashrisk' 也不是编译错误，只是 IDEA 的拼写检查提示，可以忽略。

原因总结

这个问题的核心原因是：

ops-assistant-service 启动类直接 import 并引用了 OpsAssistantProperties，而 IDEA 在多模块 Maven 项目中偶发没有正确索引该类，因此显示 Cannot resolve symbol。

其他服务没有类似报错，是因为它们没有在启动类里直接引用本模块配置类，所以不会触发同样的 IDEA 符号解析问题。

正确修改方式

Spring Boot 对 @ConfigurationProperties 类有两种常见启用方式。

第一种是显式启用：

@EnableConfigurationProperties(OpsAssistantProperties.class)

第二种是扫描配置属性类：

@ConfigurationPropertiesScan("com.flashrisk.opsassistant.config")

在多模块项目中，第二种方式更稳定，也更适合配置类可能继续增加的服务。

修改后的启动类：

package com.flashrisk.opsassistant;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

/**
 * Bootstrap class for the FlashRisk operations assistant.
 */
@SpringBootApplication(scanBasePackages = "com.flashrisk")
@ConfigurationPropertiesScan("com.flashrisk.opsassistant.config")
public class OpsAssistantServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(OpsAssistantServiceApplication.class, args);
    }
}

对应配置类保持不变：

package com.flashrisk.opsassistant.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

import java.time.Duration;
import java.util.List;

@ConfigurationProperties(prefix = "flashrisk.ops-assistant")
public record OpsAssistantProperties(
        boolean aiEnabled,
        Duration requestTimeout,
        List<ServiceEndpoint> services
) {

    public record ServiceEndpoint(
            String name,
            String baseUrl
    ) {
    }
}

修改后的验证

执行：

mvn -q -pl ops-assistant-service -am test

验证通过后，说明配置属性扫描正常，应用上下文可以成功加载。

然后在 IDEA 中执行：

Maven 面板点击 Reload All Maven Projects
如仍有红线，执行 File -> Invalidate Caches / Restart
重新运行 OpsAssistantServiceApplication

经验总结

这次问题本质上不是业务代码错误，而是多模块项目中 IDEA 符号解析和 Spring Boot 配置启用方式叠加导致的误报。

对于 Spring Boot 配置类，推荐：

@ConfigurationPropertiesScan

而不是在启动类中一个个显式写：

@EnableConfigurationProperties(SomeProperties.class)

这样有几个好处：

减少启动类对具体配置类的直接依赖；
配置类新增后不需要修改启动类；
在 Maven 多模块项目中更不容易触发 IDEA 的符号解析红线；
启动类职责更清晰，只负责应用引导。