LangChain4j Spring Boot Starter 中 ComponentScan 的 SPEL 表达式解析问题分析

问题背景

在 LangChain4j 项目的 Spring Boot Starter 模块中，开发者发现当使用 Spring Expression Language (SPEL) 表达式作为 @ComponentScan 注解的 basePackages 参数时，会导致 AI 服务类无法被正确扫描和注册。这是一个典型的 Spring Boot 自动配置与自定义组件扫描机制之间的兼容性问题。

问题现象

当开发者尝试在项目中通过 SPEL 表达式动态指定组件扫描路径时，例如：

@ComponentScan(basePackages = {"${demo.scan.controller:}"})

然后在该路径下放置带有 @AiService 注解的接口：

@AiService
public interface AiAssistant {
    String chat(String text);
}

应用启动时会报错，提示找不到 AiAssistant 类型的 Bean。这表明 LangChain4j 的自动扫描机制未能正确处理 SPEL 表达式解析后的包路径。

技术原理分析

Spring Boot 的自动配置机制通过 @ComponentScan 注解来扫描和注册组件。当使用 SPEL 表达式时，Spring 会在运行时解析这些表达式并获取实际的包路径。然而，LangChain4j 的自定义扫描器 AiServiceScannerProcessor 在实现时没有考虑到这种动态解析的需求。

在原始的 AiServiceScannerProcessor 实现中，它直接从 @ComponentScan 注解中获取 basePackages 值，但没有对这些值进行 SPEL 表达式解析和环境属性替换。这导致了当包路径包含 ${} 占位符时，扫描器会直接使用未解析的字符串作为包名，自然无法找到对应的类。

解决方案

针对这个问题，开发者提出了一个修复方案，主要修改了 getBasePackages 方法中的处理逻辑：

1. 在获取 @ComponentScan 注解的 basePackages 值时，新增了对 SPEL 表达式的解析处理
2. 使用 Environment 接口的 resolvePlaceholders 方法来解析包路径中的占位符
3. 通过 StringUtils.tokenizeToStringArray 处理可能的多值情况

关键修改点如下：

for (String pkg : componentScan.basePackages()) {
    String[] tokenized = StringUtils.tokenizeToStringArray(
        this.environment.resolvePlaceholders(pkg), 
        ConfigurableApplicationContext.CONFIG_LOCATION_DELIMITERS
    );
    Collections.addAll(basePackages, tokenized);
}

实现细节

完整的修复方案需要 AiServiceScannerProcessor 实现 EnvironmentAware 接口，以便获取 Spring 的环境配置信息。处理器的主要工作流程如下：

1. 从自动配置包中获取基础包路径
2. 扫描所有带有 @ComponentScan 注解的类
3. 对每个 @ComponentScan 注解：
   • 处理 value 属性
   • 处理 basePackages 属性（新增 SPEL 解析）
   • 处理 basePackageClasses 属性
4. 处理 @SpringBootApplication 注解的扫描配置
5. 返回所有收集到的包路径集合

最佳实践建议

对于使用 LangChain4j Spring Boot Starter 的开发者，建议：

1. 如果需要动态配置扫描路径，确保使用标准的 Spring 属性占位符语法
2. 在属性文件中明确定义所有扫描路径，例如：

   demo.scan.controller=com.example.ai
   

3. 考虑将 AI 服务类放在明确的包路径下，而不是完全依赖动态配置
4. 在复杂的扫描场景中，可以自定义 AiServiceScannerProcessor 来满足特定需求

总结

这个问题展示了 Spring Boot 自动配置与自定义组件扫描机制集成时的一个常见陷阱。通过正确处理环境属性和 SPEL 表达式，LangChain4j 能够更好地与 Spring Boot 的配置体系协同工作，为开发者提供更灵活的 AI 服务集成方案。这个修复不仅解决了具体的技术问题，也提升了框架的整体健壮性和配置灵活性。