问题解决方案

✅ 解决指南：开发中遇到问题的详细解决步骤和方法

📋 目录

编译和构建问题
运行时错误
数据库连接问题
查询结果异常
工作流问题
性能问题
开发环境问题

编译和构建问题

问题：Maven依赖冲突

症状：编译时出现包冲突、方法不存在等错误

解决步骤：

bash

# 1. 清理项目
mvn clean

# 2. 查看依赖树，找出冲突
mvn dependency:tree

# 3. 排除冲突依赖
# 在pom.xml中添加exclusions
<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-lib</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflict-group</groupId>
            <artifactId>conflict-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

# 4. 重新编译
mvn compile

问题：Java版本不匹配

症状：编译时提示不支持的Java版本

解决方案：

xml

<!-- 确认pom.xml中的Java版本配置 -->
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

bash

# 检查当前Java版本
java -version

# 检查JAVA_HOME环境变量
echo $JAVA_HOME

# 如果版本不对，安装正确的JDK 17

问题：MyBatis-Flex相关编译错误

症状：QueryWrapper、BaseMapper等类找不到

解决方案：

xml

<!-- 确认MyBatis-Flex版本 -->
<dependency>
    <groupId>com.mybatis-flex</groupId>
    <artifactId>mybatis-flex-spring-boot-starter</artifactId>
    <version>1.10.8</version>
</dependency>

<!-- 如果使用代码生成，添加处理器依赖 -->
<dependency>
    <groupId>com.mybatis-flex</groupId>
    <artifactId>mybatis-flex-processor</artifactId>
    <version>1.10.8</version>
    <optional>true</optional>
</dependency>

运行时错误

问题：Bean无法注入

症状：NoSuchBeanDefinitionException、UnsatisfiedDependencyException

解决步骤：

检查组件扫描路径：

java

@SpringBootApplication
@ComponentScan(basePackages = {"jpwise"})  // 确保扫描路径正确
public class JpWiseAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(JpWiseAdminApplication.class, args);
    }
}

检查注解是否正确：

java

// Service类必须有@Service注解
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)
public class BusinessServiceImpl { }

// Mapper接口必须有@Mapper注解
@Mapper
public interface BusinessMapper extends BaseMapper<BusinessEntity> { }

检查循环依赖：

java

// 如果存在循环依赖，使用@Lazy注解
@Service
public class ServiceA {
    
    @Autowired
    @Lazy  // 延迟注入，解决循环依赖
    private ServiceB serviceB;
}

问题：数据源配置错误

症状：DataSourceTransactionManager错误、数据库连接失败

解决方案：

检查数据源注解：

java

// 确保Service类有数据源注解
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)  // 必须指定数据源
public class BusinessServiceImpl { }

检查数据库配置：

yaml

# application.yml
spring:
  datasource:
    jpwise_demo:
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://localhost:3306/jpwise_demo?useUnicode=true&characterEncoding=utf8&useSSL=false
      username: root
      password: password

验证数据库连接：

bash

# 使用MySQL客户端测试连接
mysql -h localhost -u root -p jpwise_demo

问题：Redis连接失败

症状：RedisConnectionFailureException

解决步骤：

检查Redis服务状态：

bash

# Windows
redis-server

# Linux/Mac
sudo service redis-server start
# 或
redis-server /etc/redis/redis.conf

验证Redis连接：

bash

# 使用redis-cli测试
redis-cli ping
# 应该返回 PONG

检查配置：

yaml

# application.yml
spring:
  redis:
    host: localhost
    port: 6379
    password:  # 如果有密码
    timeout: 2000ms
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0

数据库连接问题

问题：MySQL连接超时

症状：CommunicationsException: Communications link failure

解决方案：

检查MySQL服务状态：

bash

# Windows
net start mysql

# Linux
sudo systemctl start mysql
sudo systemctl status mysql

检查防火墙设置：

bash

# 确保3306端口开放
telnet localhost 3306

调整连接参数：

yaml

spring:
  datasource:
    jpwise_demo:
      jdbc-url: jdbc:mysql://localhost:3306/jpwise_demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=GMT%2B8&autoReconnect=true&failOverReadOnly=false&maxReconnects=3
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

问题：SQL语法错误

症状：SQLSyntaxErrorException、BadSqlGrammarException

调试步骤：

开启SQL日志：

yaml

# application.yml
mybatis-flex:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

# 或使用logback
logging:
  level:
    jpwise.base.mapper: DEBUG

检查实体类映射：

java

// 确保表名和字段名正确
@Table("CORRECT_TABLE_NAME")
public class BusinessEntity extends BaseEntity {
    
    @Column("CORRECT_FIELD_NAME")
    @JsonProperty("CORRECT_FIELD_NAME")
    private String FIELD;
}

验证SQL语句：

java

// 在数据库中直接执行生成的SQL，确认语法正确

查询结果异常

问题：分页查询无数据

原因分析和解决：

页码从0开始的问题：

java

// ❌ 错误：页码从0开始
Page<Entity> page = new Page<>(0, 10);

// ✅ 正确：页码从1开始
Page<Entity> page = new Page<>(1, 10);
Page<Entity> page = new Page<>(pagination.getCurrentPage(), pagination.getPageSize());

过滤条件过于严格：

java

// 检查常见的过滤条件
QueryWrapper queryWrapper = new QueryWrapper();
queryWrapper.eq(Entity::getENABLEDMARK, "1")    // 启用状态
           .isNull(Entity::getDELETEUSER);      // 未删除

// 调试：暂时移除所有条件，查看是否有数据
QueryWrapper debugWrapper = new QueryWrapper();
List<Entity> allData = mapper.selectList(debugWrapper);
System.out.println("总数据量：" + allData.size());

字段名映射错误：

java

// 确保Entity字段名与数据库字段名对应正确
@Column("CORRECT_DB_FIELD_NAME")
private String ENTITY_FIELD_NAME;

问题：OR条件查询编译错误

症状：or()方法调用歧义

解决方案：

java

import java.util.function.Consumer;

// ✅ 正确：显式类型转换
queryWrapper.and((Consumer<QueryWrapper>) w -> {
    w.like(Entity::getTITLE, keyword)
     .or((Consumer<QueryWrapper>) ww -> ww.like(Entity::getCODE, keyword))
     .or((Consumer<QueryWrapper>) ww -> ww.like(Entity::getNAME, keyword));
});

// 或者拆分为多个条件
QueryWrapper titleWrapper = new QueryWrapper();
titleWrapper.like(Entity::getTITLE, keyword);

QueryWrapper codeWrapper = new QueryWrapper();
codeWrapper.like(Entity::getCODE, keyword);

QueryWrapper finalWrapper = new QueryWrapper();
finalWrapper.and(w -> w.apply("(" + titleWrapper.toSQL() + " OR " + codeWrapper.toSQL() + ")"));

工作流问题

问题：工作流提交失败

症状：提交时报错，流程无法启动

检查清单：

实体类工作流字段：

java

// 确保继承BaseEntity（包含工作流字段）
public class BusinessEntity extends BaseEntity {
    // BaseEntity已包含FLOWPHASE、STEPNAME等字段
}

数据表工作流字段：

sql

-- 确保数据表包含工作流字段
ALTER TABLE business_table ADD COLUMN FLOWPHASE VARCHAR(50);
ALTER TABLE business_table ADD COLUMN STEPNAME VARCHAR(200);

工作流模板配置：

java

// 检查工作流模板是否正确配置
// 确保有对应的流程定义

问题：钩子方法不执行

原因和解决：

方法签名错误：

java

// ✅ 确保方法签名完全正确
@Override
public Map<String, Object> beforeSave(Map<String, Object> dic, Boolean isNew) 
       throws BusinessException, DataException {
    // 注意：参数类型、返回类型、异常声明必须与基类一致
    return super.beforeSave(dic, isNew);
}

忘记调用父类方法：

java

// ✅ 必须调用super方法
@Override
public Map<String, Object> beforeSave(Map<String, Object> dic, Boolean isNew) 
       throws BusinessException, DataException {
    // 自定义逻辑...
    return super.beforeSave(dic, isNew);  // 必须调用
}

Service类继承错误：

java

// ✅ 确保继承正确的基类
public class BusinessServiceImpl extends BasicDemoServiceImpl<BusinessMapper, BusinessEntity> 
                                implements BusinessService {
    // 钩子方法才能生效
}

性能问题

问题：查询速度慢

优化步骤：

添加合适的索引：

sql

-- 为常用查询字段添加索引
CREATE INDEX idx_business_status ON business_table(STATUS);
CREATE INDEX idx_business_creator ON business_table(CREATOR_USER);
CREATE INDEX idx_business_time ON business_table(CREATOR_TIME);

-- 复合索引
CREATE INDEX idx_business_status_time ON business_table(STATUS, CREATOR_TIME);

优化查询条件：

java

// ✅ 使用索引字段作为查询条件
queryWrapper.eq(Entity::getID, id)        // 主键，最快
           .eq(Entity::getSTATUS, status)  // 有索引
           .ge(Entity::getCREATORTIME, startDate); // 范围查询

// ❌ 避免在字段上使用函数
queryWrapper.apply("DATE(creator_time) = '2024-08-14'");

分页优化：

java

// 大数据量时不查询总数
Page<Entity> page = new Page<>(currentPage, pageSize, false);

// 或使用游标分页
queryWrapper.gt(Entity::getID, lastId)
           .orderBy(Entity::getID, true)
           .last("LIMIT 10");

问题：内存溢出

解决方案：

批量处理优化：

java

// 分批处理大量数据
@Override
public void batchImport(List<BusinessEntity> entities) {
    int batchSize = 1000;
    for (int i = 0; i < entities.size(); i += batchSize) {
        int end = Math.min(i + batchSize, entities.size());
        List<BusinessEntity> batch = entities.subList(i, end);
        this.saveBatch(batch);
    }
}

JVM参数调优：

bash

# 启动参数示例
java -Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar app.jar

连接池配置：

yaml

spring:
  datasource:
    jpwise_demo:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000

开发环境问题

问题：热部署不生效

解决方案：

添加开发工具依赖：

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

IDEA配置：

1. File → Settings → Build → Compiler → Build project automatically ☑
2. Help → Find Action → Registry → compiler.automake.allow.when.app.running ☑
3. 重启IDEA

配置热部署范围：

yaml

spring:
  devtools:
    restart:
      enabled: true
      exclude: static/**,public/**

问题：端口占用

症状：Port 30000 was already in use

解决步骤：

bash

# 1. 查找占用端口的进程
# Windows
netstat -ano | findstr :30000
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -i :30000
kill -9 <进程ID>

# 2. 或修改端口配置
# application.yml
server:
  port: 30001

问题：Swagger UI无法访问

症状：访问http://localhost:30000/doc.html显示404

解决方案：

检查Swagger配置：

java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // Swagger配置...
}

检查依赖：

xml

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

检查访问路径：

正确路径：http://localhost:30000/doc.html
错误路径：http://localhost:30000/swagger-ui.html

调试技巧

1. 启用调试日志

yaml

# application.yml
logging:
  level:
    jpwise: DEBUG
    org.springframework: DEBUG
    com.mybatisflex: DEBUG

2. 使用断点调试

java

// 在关键位置设置断点
@Override
public List<BusinessEntity> getList(QueryBuilder pagination) {
    QueryWrapper queryWrapper = new QueryWrapper();
    // 在这里设置断点，检查查询条件
    
    Page<BusinessEntity> result = this.page(page, queryWrapper);
    // 在这里设置断点，检查查询结果
    
    return pagination.setData(result.getRecords(), result.getTotalRow());
}

3. 添加临时日志

java

// 临时添加日志输出
log.info("查询条件：{}", queryWrapper.toSQL());
log.info("查询结果数量：{}", result.size());
log.info("分页信息：当前页={}, 页大小={}, 总数={}", 
         page.getCurrent(), page.getSize(), page.getTotal());

4. 使用Spring Boot Actuator

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

yaml

# 开启健康检查和监控端点
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env
  endpoint:
    health:
      show-details: always

访问：http://localhost:30000/actuator/health

问题报告模板

当遇到无法解决的问题时，请按以下模板整理信息：

markdown

## 问题描述
详细描述遇到的问题和期望的结果

## 环境信息
- Java版本：
- Spring Boot版本：
- MyBatis-Flex版本：
- 数据库类型和版本：
- 操作系统：

## 重现步骤
1. 第一步操作
2. 第二步操作
3. 第三步操作

## 错误信息

完整的错误堆栈信息


## 相关代码
```java
// 问题相关的代码片段

已尝试的解决方案

尝试了xxx方法，结果是...
检查了xxx配置，发现...


---

> 💡 **提示**：大多数问题都有标准的解决模式。遇到问题时，先查看错误信息的关键词，然后按照对应的解决步骤操作。如果问题仍无法解决，请整理详细的问题信息寻求帮助。

问题解决方案 ​

📋 目录 ​

编译和构建问题 ​

问题：Maven依赖冲突 ​

问题：Java版本不匹配 ​

问题：MyBatis-Flex相关编译错误 ​

运行时错误 ​

问题：Bean无法注入 ​

问题：数据源配置错误 ​

问题：Redis连接失败 ​

数据库连接问题 ​

问题：MySQL连接超时 ​

问题：SQL语法错误 ​

查询结果异常 ​

问题：分页查询无数据 ​

问题：OR条件查询编译错误 ​

工作流问题 ​

问题：工作流提交失败 ​

问题：钩子方法不执行 ​

性能问题 ​

问题：查询速度慢 ​

问题：内存溢出 ​

开发环境问题 ​

问题：热部署不生效 ​

问题：端口占用 ​

问题：Swagger UI无法访问 ​

调试技巧 ​

1. 启用调试日志 ​

2. 使用断点调试 ​

3. 添加临时日志 ​

4. 使用Spring Boot Actuator ​

问题报告模板 ​

已尝试的解决方案 ​

问题解决方案

📋 目录

编译和构建问题

问题：Maven依赖冲突

问题：Java版本不匹配

问题：MyBatis-Flex相关编译错误

运行时错误

问题：Bean无法注入

问题：数据源配置错误

问题：Redis连接失败

数据库连接问题

问题：MySQL连接超时

问题：SQL语法错误

查询结果异常

问题：分页查询无数据

问题：OR条件查询编译错误

工作流问题

问题：工作流提交失败

问题：钩子方法不执行

性能问题

问题：查询速度慢

问题：内存溢出

开发环境问题

问题：热部署不生效

问题：端口占用

问题：Swagger UI无法访问

调试技巧

1. 启用调试日志

2. 使用断点调试

3. 添加临时日志

4. 使用Spring Boot Actuator

问题报告模板

已尝试的解决方案