常见错误和解决方案

❌ 故障排除：快速定位和解决开发中的常见问题

📋 目录

注解使用错误
实体字段命名错误
查询无数据问题
工具类方法错误
数据源配置错误
异常处理错误
导入包错误
其他常见问题

注解使用错误

@BuildQuery注解位置错误

java

// ❌ 错误：注解放在参数上
public ActionResult getList(@BuildQuery QueryBuilder pagination) {
    // 不会生效
}

// ✅ 正确：注解放在方法上
@BuildQuery
public ActionResult getList(QueryBuilder pagination) {
    // 正确生效
}

@UseDataSource缺失

java

// ❌ 错误：Service实现类没有指定数据源
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity> {
    // 会导致数据库连接错误
}

// ✅ 正确：必须指定数据源
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)
public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity> {
    // 正确连接到指定数据库
}

@Mapper注解缺失

java

// ❌ 错误：Mapper接口没有@Mapper注解
public interface UserMapper extends BasicMapper<UserEntity> {
    // Spring无法扫描到这个Mapper
}

// ✅ 正确：必须添加@Mapper注解
@Mapper
public interface UserMapper extends BasicMapper<UserEntity> {
    // Spring能正确扫描和注入
}

实体字段命名错误

业务实体字段命名

java

// ❌ 错误：业务实体使用驼峰或下划线
public class BusinessEntity extends BaseEntity {
    private String userName;      // 错误：驼峰
    private String user_name;     // 错误：下划线
    private String real_Name;     // 错误：混合
}

// ✅ 正确：业务实体全大写无下划线
public class BusinessEntity extends BaseEntity {
    private String USERNAME;      // 正确
    private String REALNAME;      // 正确
    private String PHONENUMBER;   // 正确
}

系统实体字段命名

java

// ❌ 错误：系统实体使用大写
public class SysMenuEntity extends SysBaseEntity {
    private String MENUNAME;      // 错误：不应该大写
    private String MENU_URL;      // 错误：不应该有下划线
}

// ✅ 正确：系统实体使用驼峰
public class SysMenuEntity extends SysBaseEntity {
    private String menuName;      // 正确
    private String menuUrl;       // 正确
}

查询无数据问题

QueryWrapper分页查询无数据

java

// ❌ 可能的原因1：分页参数错误
Page&lt;Entity&gt; page = new Page&lt;&gt;(0, 10);  // 页码从0开始是错误的

// ✅ 正确：页码从1开始
Page&lt;Entity&gt; page = new Page&lt;&gt;(1, 10);  // 第1页，每页10条
Page&lt;Entity&gt; page = new Page&lt;&gt;(pagination.getCurrentPage(), pagination.getPageSize());

java

// ❌ 可能的原因2：过滤条件太严格
QueryWrapper queryWrapper = new QueryWrapper();
queryWrapper.eq(Entity::getSTATUS, "1")
           .eq(Entity::getDELETEUSER, "");  // 错误：应该用isNull

// ✅ 正确：使用isNull判断空值
queryWrapper.eq(Entity::getENABLEDMARK, "1")
           .isNull(Entity::getDELETEUSER);

排序方法错误

java

// ❌ 错误：使用不存在的方法
queryWrapper.orderByDesc(Entity::getCREATORTIME);  // 方法不存在
queryWrapper.orderByAsc(Entity::getCREATORTIME);   // 方法不存在

// ✅ 正确：使用orderBy方法
queryWrapper.orderBy(Entity::getCREATORTIME, false);  // false = DESC 降序
queryWrapper.orderBy(Entity::getCREATORTIME, true);   // true = ASC 升序

OR条件查询错误

java

// ❌ 错误：直接调用or()
queryWrapper.like(Entity::getTITLE, keyword)
           .or()
           .like(Entity::getCODE, keyword);  // 编译错误

// ✅ 正确：使用Consumer并显式转换类型
import java.util.function.Consumer;

queryWrapper.and((Consumer&lt;QueryWrapper&gt;) w -> {
    w.like(Entity::getTITLE, keyword)
     .or((Consumer&lt;QueryWrapper&gt;) ww -> ww.like(Entity::getCODE, keyword))
     .or((Consumer&lt;QueryWrapper&gt;) ww -> ww.like(Entity::getNAME, keyword));
});

工具类方法错误

JsonUtil方法错误

java

// ❌ 错误：使用原生ObjectMapper
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(entity);

// ✅ 正确：使用JsonUtil
String json = JsonUtil.getObjectToString(entity);

DateUtil方法错误

java

// ❌ 错误：getNow()返回String不是Date
Date now = DateUtil.getNow();                    // 类型错误
entity.setCREATORTIME(DateUtil.getNow());        // 类型不匹配

// ✅ 正确：getNowDate()返回Date，getNow()返回String
Date now = DateUtil.getNowDate();                // 返回Date
entity.setCREATORTIME(DateUtil.getNowDate());    // 正确
String nowStr = DateUtil.getNow();               // 返回String

RedisUtil方法错误

java

// ❌ 错误：方法名错误
redisUtil.removeString("key");     // 方法不存在
redisUtil.delete("key");          // 方法不存在

// ✅ 正确：使用remove方法
redisUtil.remove("key");          // 正确方法名

加密工具方法错误

java

// ❌ 错误：方法名错误
String md5 = Md5Util.getMd5(text);           // 方法不存在
String encrypted = DesUtil.encrypt(text);     // 方法不存在

// ✅ 正确：使用正确的方法名
String md5 = Md5Util.getStringMd5(text);     // 正确
String encrypted = DesUtil.desEncode(text);   // 正确

数据源配置错误

数据源常量使用错误

java

// ❌ 错误：硬编码数据源名称
@UseDataSource("jpwise_demo")
@UseDataSource("demo")

// ✅ 正确：使用常量
@UseDataSource(DbNameConst.JPWISE_DEMO)      // 测试项目
@UseDataSource(DbNameConst.JPWISE_BASE)      // 基础数据库
@UseDataSource(DbNameConst.JPWISE_HR)        // 人力资源

模块数据源对应关系

java

// 各模块必须使用对应的数据源
jpwise-extend   → DbNameConst.JPWISE_DEMO
jpwise-system   → DbNameConst.JPWISE_BASE
jpwise-hr       → DbNameConst.JPWISE_HR
jpwise-affair   → DbNameConst.JPWISE_AFFAIR

异常处理错误

throws声明不一致

java

// ❌ 错误：钩子方法throws声明与基类不一致
@Override
public Map&lt;String, Object&gt; beforeSave(Map&lt;String, Object&gt; dic, Boolean isNew) 
       throws Exception {  // 错误：应该是BusinessException, DataException
    // 实现
}

// ✅ 正确：与基类保持一致
@Override
public Map&lt;String, Object&gt; beforeSave(Map&lt;String, Object&gt; dic, Boolean isNew) 
       throws BusinessException, DataException {
    // 实现
}

使用错误的异常类型

java

// ❌ 错误：使用通用异常
throw new Exception("错误");
throw new RuntimeException("错误");

// ✅ 正确：使用项目定义的异常
throw new BusinessException("业务异常");
throw new DataException("数据异常");

导入包错误

工具类导入错误

java

// ❌ 错误的导入路径
import jpwise.util.FileUtil;                     // 错误：FileUtil在子包中
import jpwise.base.TreeUtil;                     // 错误：TreeUtil在util.treeutil包
import jpwise.system.service.MessageService;     // 错误：MessageService在message包

// ✅ 正确的导入路径
import jpwise.util.file.FileUtil;                // 正确
import jpwise.util.treeutil.TreeUtil;            // 正确
import jpwise.message.service.MessageService;    // 正确

工作流相关导入错误

java

// ✅ 正确的导入路径
import jpwise.engine.model.flowengine.FlowModel;
import jpwise.model.flow.FlowTaskEntity;
import jpwise.base.enums.FlowRecordEnum;

其他常见问题

ActionResult原始类型警告

java

// ❌ 错误：没有泛型参数
public ActionResult getList() {
    return ActionResult.success(data);  // 警告：使用原始类型
}

// ✅ 正确：添加泛型参数
public ActionResult&lt;List&lt;Entity&gt;&gt; getList() {
    return ActionResult.success(data);
}

public ActionResult&lt;PageListVO&lt;Entity&gt;&gt; getPage(QueryBuilder pagination) {
    PaginationVO paginationVO = JsonUtil.getJsonToBean(pagination, PaginationVO.class);
    return ActionResult.page(data, paginationVO);
}

依赖注入方式不统一

java

// ❌ 错误：混用@Resource和@Autowired
@Resource
private UserService userService;

@Autowired
private RedisUtil redisUtil;

// ✅ 正确：统一使用@Autowired
@Autowired
private UserService userService;

@Autowired
private RedisUtil redisUtil;

接口方法使用错误

java

// ❌ 错误：使用PUT/DELETE/PATCH
@PutMapping("/{id}")
@DeleteMapping("/{id}")
@PatchMapping("/{id}")

// ✅ 正确：只使用GET和POST
@GetMapping("/{id}")           // 查询
@PostMapping                   // 创建
@PostMapping("/update/{id}")   // 更新
@PostMapping("/{id}")          // 删除

钩子方法返回值错误

java

// ❌ 错误：没有调用super方法
@Override
public Map&lt;String, Object&gt; beforeSave(Map&lt;String, Object&gt; dic, Boolean isNew) {
    // 业务逻辑
    return dic;  // 错误：应该返回super.beforeSave()
}

// ✅ 正确：调用super方法
@Override
public Map&lt;String, Object&gt; beforeSave(Map&lt;String, Object&gt; dic, Boolean isNew) 
       throws BusinessException, DataException {
    // 业务逻辑
    return super.beforeSave(dic, isNew);  // 正确
}

子表注解配置错误

java

// ❌ 错误：缺少必要的注解属性
@SubEntity(targetEntity = DetailEntity.class)
private List&lt;DetailEntity&gt; details;  // 缺少service和foreign

// ✅ 正确：完整的注解配置
@SubEntity(targetEntity = DetailEntity.class,
           service = DetailService.class,
           foreign = "MAINID")
@Column(ignore = true)
@JsonProperty("DETAILLIST")
private List&lt;DetailEntity&gt; DETAILLIST;

调试技巧

1. 检查数据源配置

java

// 在Service实现类上检查
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)  // 确保有这个注解

2. 检查SQL输出

yaml

# application.yml 开启SQL日志
mybatis-flex:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

3. 检查返回数据

java

// 添加日志查看查询结果
log.info("查询条件：{}", queryWrapper.toSQL());
log.info("查询结果数量：{}", result.size());

4. 验证工具类方法

java

// 不确定方法是否存在时，查看源码
// IDEA中：Ctrl+Click 进入工具类源码查看可用方法

错误速查表

错误现象	可能原因	解决方案
查询无数据	分页参数错误	页码从1开始
查询无数据	过滤条件太严格	检查删除标记和启用状态
编译错误	方法不存在	查看工具类源码确认方法名
类型不匹配	DateUtil方法混淆	getNowDate()返回Date，getNow()返回String
数据库连接错误	缺少@UseDataSource	添加数据源注解
Spring注入失败	缺少@Mapper	Mapper接口添加@Mapper注解
@BuildQuery不生效	注解位置错误	注解放在方法上，不是参数上
OR查询编译错误	Lambda类型推断失败	显式转换为Consumer<QueryWrapper>

💡 提示：遇到问题时，先检查这个文档的错误速查表，大部分常见问题都可以快速解决。如果问题persist，查看工具类源码或项目已有的类似实现。

常见错误和解决方案 ​

📋 目录 ​

注解使用错误 ​

@BuildQuery注解位置错误 ​

@UseDataSource缺失 ​

@Mapper注解缺失 ​

实体字段命名错误 ​

业务实体字段命名 ​

系统实体字段命名 ​

查询无数据问题 ​

QueryWrapper分页查询无数据 ​

排序方法错误 ​

OR条件查询错误 ​

工具类方法错误 ​

JsonUtil方法错误 ​

DateUtil方法错误 ​

RedisUtil方法错误 ​

加密工具方法错误 ​

数据源配置错误 ​

数据源常量使用错误 ​

模块数据源对应关系 ​

异常处理错误 ​

throws声明不一致 ​

使用错误的异常类型 ​

导入包错误 ​

工具类导入错误 ​

工作流相关导入错误 ​

其他常见问题 ​

ActionResult原始类型警告 ​

依赖注入方式不统一 ​

接口方法使用错误 ​

钩子方法返回值错误 ​

子表注解配置错误 ​

调试技巧 ​

1. 检查数据源配置 ​

2. 检查SQL输出 ​

3. 检查返回数据 ​

4. 验证工具类方法 ​

错误速查表 ​

常见错误和解决方案

📋 目录

注解使用错误

@BuildQuery注解位置错误

@UseDataSource缺失

@Mapper注解缺失

实体字段命名错误

业务实体字段命名

系统实体字段命名

查询无数据问题

QueryWrapper分页查询无数据

排序方法错误

OR条件查询错误

工具类方法错误

JsonUtil方法错误

DateUtil方法错误

RedisUtil方法错误

加密工具方法错误

数据源配置错误

数据源常量使用错误

模块数据源对应关系

异常处理错误

throws声明不一致

使用错误的异常类型

导入包错误

工具类导入错误

工作流相关导入错误

其他常见问题

ActionResult原始类型警告

依赖注入方式不统一

接口方法使用错误

钩子方法返回值错误

子表注解配置错误

调试技巧

1. 检查数据源配置

2. 检查SQL输出

3. 检查返回数据

4. 验证工具类方法

错误速查表