故障排查

本页面列出了使用 LCGYL Framework 时的常见问题和解决方案。

启动问题

应用无法启动

症状：应用启动时抛出异常

可能原因：

1. JDK 版本不正确
2. 依赖冲突
3. 配置文件错误

解决方案：

1. 检查 JDK 版本

   java -version
   # 应该显示 21 或更高版本

2. 检查依赖

   gradle dependencies

3. 检查配置文件

   • 确保 application.properties 格式正确
   • 检查配置项是否有拼写错误

ClassNotFoundException

症状：ClassNotFoundException: com.lcgyl.framework.core.Application

原因：依赖未正确添加

解决方案：

dependencies {
    implementation 'com.lcgyl:lcgyl-framework-core:2.2.0'
}

刷新 Gradle 依赖：

gradle clean build

依赖注入问题

组件未找到

症状：NoSuchBeanException: No bean of type 'XXX' found

原因：

1. 组件未添加 @Component 注解
2. 组件不在扫描路径下
3. 组件扫描配置错误

解决方案：

1. 添加 @Component 注解

   @Component  // 确保有这个注解
   public class UserService {
   }

2. 检查包路径

   // 确保组件在主类的包或子包下
   @ComponentScan("com.example")  // 指定扫描路径
   public class Application {
   }

循环依赖

症状：CircularDependencyException

原因：两个或多个组件相互依赖

解决方案：

1. 重构代码，消除循环依赖

   // ❌ 错误：循环依赖
   @Component
   public class ServiceA {
       @Inject
       private ServiceB serviceB;
   }
   
   @Component
   public class ServiceB {
       @Inject
       private ServiceA serviceA;
   }
   
   // ✅ 正确：提取公共接口
   @Component
   public class ServiceA {
       @Inject
       private CommonService commonService;
   }
   
   @Component
   public class ServiceB {
       @Inject
       private CommonService commonService;
   }

2. 使用 Setter 注入

   @Component
   public class ServiceA {
       private ServiceB serviceB;
       
       @Inject
       public void setServiceB(ServiceB serviceB) {
           this.serviceB = serviceB;
       }
   }

配置问题

配置值未注入

症状：配置值为 null 或默认值

原因：

1. 配置文件路径错误
2. 配置项名称错误
3. 配置文件未加载

解决方案：

1. 检查配置文件位置

   • 确保 application.properties 在 src/main/resources 下

2. 检查配置项名称

   # application.properties
   app.name=MyApp

   @Value("app.name")  // 确保名称匹配
   private String name;

3. 启用配置日志

   logging.level.com.lcgyl.framework.core.config=DEBUG

配置文件未找到

症状：ConfigurationException: Configuration file not found

解决方案：

1. 检查文件路径

   src/
   └── main/
       └── resources/
           └── application.properties  ← 确保在这里

2. 指定配置文件路径

   Application app = Application.builder()
       .configLocation("classpath:config/application.properties")
       .run(args);

事件总线问题

事件未被处理

症状：发布事件后，监听器未被调用

原因：

1. 监听器未添加 @Subscribe 注解
2. 监听器未注册为组件
3. 事件类型不匹配

解决方案：

1. 检查监听器注解

   @Component  // 必须是组件
   public class UserEventListener {
       
       @Subscribe  // 必须有这个注解
       public void onUserCreated(UserCreatedEvent event) {
           // 处理事件
       }
   }

2. 检查事件类型

   // 确保事件类型完全匹配
   eventBus.publish(new UserCreatedEvent(user));  // 发布
   
   @Subscribe
   public void onUserCreated(UserCreatedEvent event) {  // 接收
       // 类型必须完全一致
   }

性能问题

应用启动慢

原因：

1. 扫描路径过大
2. 组件过多
3. 初始化逻辑复杂

解决方案：

1. 缩小扫描范围

   @ComponentScan("com.example.app")  // 只扫描必要的包

2. 延迟初始化

   @Component(lazy = true)  // 延迟初始化
   public class HeavyService {
   }

3. 异步初始化

   @Component
   public class AsyncInitService {
       
       @PostConstruct
       public void init() {
           CompletableFuture.runAsync(() -> {
               // 异步初始化
           });
       }
   }

内存占用高

原因：

1. 单例组件过多
2. 缓存未清理
3. 事件监听器泄漏

解决方案：

1. 使用原型作用域

   @Component(scope = Scope.PROTOTYPE)
   public class PrototypeService {
   }

2. 定期清理缓存

   @Scheduled(cron = "0 0 * * * ?")
   public void clearCache() {
       cache.clear();
   }

3. 取消事件订阅

   @PreDestroy
   public void cleanup() {
       eventBus.unsubscribe(this);
   }

日志问题

日志未输出

原因：

1. 日志级别设置过高
2. 日志配置错误
3. 日志框架未正确配置

解决方案：

1. 检查日志级别

   # application.properties
   logging.level.root=INFO
   logging.level.com.example=DEBUG

2. 添加日志依赖

   dependencies {
       implementation 'org.slf4j:slf4j-api:2.0.9'
       runtimeOnly 'ch.qos.logback:logback-classic:1.4.14'
   }

3. 配置 Logback

   <!-- logback.xml -->
   <configuration>
       <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
           <encoder>
               <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
           </encoder>
       </appender>
       
       <root level="INFO">
           <appender-ref ref="CONSOLE" />
       </root>
   </configuration>

获取帮助

如果以上方案都无法解决你的问题：

1. 查看完整文档

   • 常见问题
   • Spring 常见问题

2. 搜索已知问题

   • Gitee Issues
   • Stack Overflow

3. 联系我们

   • 邮箱：lcgylupup@petalmail.com
   • 官网：https://www.lcgylfamily.cn