常见问题

关联查询报错：Not unique table/alias: 'sys_xxx'

同一张表关联多次时必须设置不同的别名，例如：

// ❌ 错误：同一张表未设置别名或别名重复
new ModelWrapper<>(User.class)
    .leftJoin(UserThird.class, UserThird::getUserId, User::getId)
    .leftJoin(UserThird.class, UserThird::getUserId, User::getId)

// ✅ 正确：使用不同别名
new ModelWrapper<>(User.class)
    .leftJoin(UserThird.class, "t1", UserThird::getUserId, User::getId)
    .leftJoin(UserThird.class, "t2", UserThird::getUserId, User::getId)

查询结果为空

• 确认条件是否正确：检查 .eq(), .like() 等条件是否匹配数据
• 确认模型是否有 @ModelLogic 注解：默认会过滤已逻辑删除的记录
• 通过 includeSoftDelete() 查看是否被软删除过滤

插入后获取不到自增 ID

• 确认实体主键字段标注了 @ModelId
• 确认数据库表的主键是自增类型（AUTO_INCREMENT）

字段映射不正确

• 确认 Java 字段名与数据库列名的驼峰/下划线对应关系
• 可通过 @ModelField("column_name") 指定自定义列名
• @ModelField(exist = false) 标注的字段会被忽略

更新时某些字段没有更新

• 确认 @ModelField 的 updateFill 策略配置
• update() 只更新通过 .data() 或 setXxx() 修改的字段

分页查询返回总数为 0

• 确认 SQL 语法正确，特别是 JOIN 后的 GROUP BY 和 HAVING
• 复杂查询建议先使用 select() 确认数据存在

关联查询结果中关联对象为空

• 确认 ON 条件正确
• 确认关联表有匹配的数据
• 确认字段选择包含关联表的字段（通过 .field(path, relClass, ...)）

多表关联排序/分组不生效

• 确认排序字段前加了正确的表名前缀
• 关联表排序需要使用 order(RelClass.class, RelClass::getField, direction)