MyBatis Plus中NULL值查询的陷阱与解决方案

1. 问题现象与背景分析

最近在项目中使用MyBatis Plus的QueryWrapper进行条件查询时，发现一个容易被忽略的坑：当使用ne（不等于）条件判断时，如果数据库字段值为NULL，查询结果会出现不符合预期的情况。这个问题在业务系统中可能导致数据统计错误或逻辑判断失误。

举个例子，假设我们有一个用户表user，其中status字段可能有值1（启用）、0（禁用）或NULL（未设置状态）。当我们想查询所有非启用用户时，直觉上会这样写：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.ne("status", 1);

预期是查出status=0和status=NULL的记录，但实际执行时发现NULL值的记录并没有被包含在结果中。这是因为SQL中NULL值的特殊性质导致的。

2. NULL值在SQL中的特殊性

2.1 三值逻辑与NULL

SQL中的NULL表示"未知"或"不存在"，它与任何值（包括NULL本身）的比较结果都是UNKNOWN，而不是TRUE或FALSE。这与大多数编程语言中的二值逻辑不同。

具体到我们的例子：

• status = 1：当status为1时返回TRUE，为0或NULL时返回FALSE
• status != 1：当status为0时返回TRUE，为1时返回FALSE，为NULL时返回UNKNOWN

2.2 WHERE子句的处理机制

SQL的WHERE子句只会返回条件评估为TRUE的行，而会过滤掉评估为FALSE或UNKNOWN的行。这就是为什么status != 1不会包含NULL记录的原因。

3. MyBatis Plus的QueryWrapper实现解析

3.1 ne方法的底层实现

MyBatis Plus的QueryWrapper.ne()方法最终会生成标准的SQL不等条件。查看源码可以发现：

java复制public Children ne(R column, Object val) {
    return this.doIt(true, column, SqlKeyword.NE, val);
}

它只是简单地生成了column <> value这样的SQL片段，没有对NULL值做特殊处理。

3.3 条件构造器的设计哲学

MyBatis Plus的条件构造器设计初衷是提供简单直观的API来构建SQL条件，而不是处理所有可能的SQL边缘情况。对于NULL值的特殊处理，需要开发者自行注意。

4. 解决方案与最佳实践

4.1 方案一：显式包含NULL条件

最直接的解决方案是额外添加一个OR条件来包含NULL值：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.ne("status", 1).or().isNull("status");

这样生成的SQL是：

sql复制WHERE status <> 1 OR status IS NULL

4.2 方案二：使用条件表达式

对于更复杂的场景，可以使用条件表达式：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.and(w -> w.ne("status", 1).or().isNull("status"));

4.3 方案三：自定义SQL片段

如果业务中频繁需要这种查询，可以封装一个工具方法：

java复制public static <T> QueryWrapper<T> neWithNull(QueryWrapper<T> wrapper, String column, Object value) {
    return wrapper.ne(column, value).or().isNull(column);
}

4.4 方案四：使用COALESCE函数

对于允许NULL但有默认值的字段，可以使用COALESCE：

java复制QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.apply("COALESCE(status, -1) != 1");

5. 实际开发中的注意事项

5.1 索引使用考量

当使用OR条件或函数包装字段时，可能会影响索引使用。建议：

1. 对于高频率查询的字段，考虑设置默认值代替NULL
2. 在复合索引中，将可能为NULL的字段放在后面
3. 使用EXPLAIN分析查询计划

5.2 业务逻辑一致性

在设计数据模型时，应该明确NULL的业务含义：

• 如果NULL表示"未设置"，可以考虑用默认值代替
• 如果NULL有特殊业务含义，应该在查询时显式处理
• 在DTO和Entity中保持NULL处理策略一致

5.3 测试建议

针对NULL值的查询应该包含在单元测试中：

java复制@Test
public void testQueryWithNull() {
    // 准备测试数据
    User user1 = new User().setStatus(1);
    User user2 = new User().setStatus(0);
    User user3 = new User().setStatus(null);
    userMapper.insertBatch(Arrays.asList(user1, user2, user3));
    
    // 测试查询
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.ne("status", 1).or().isNull("status");
    List<User> users = userMapper.selectList(wrapper);
    
    // 验证结果
    assertEquals(2, users.size());
    assertTrue(users.stream().anyMatch(u -> u.getStatus() == 0));
    assertTrue(users.stream().anyMatch(u -> u.getStatus() == null));
}

6. 深入理解NULL处理

6.1 其他受影响的查询方法

除了ne()方法外，MyBatis Plus中其他比较方法也有类似的NULL处理问题：

• eq()：field = value 不会匹配NULL
• between()：NULL值不会被包含
• in()：NULL值不会被包含在列表中

6.2 数据库差异

不同数据库对NULL的处理有细微差异：

• MySQL：遵循标准SQL的NULL处理
• Oracle：在有些版本中对NULL和空字符串处理不同
• PostgreSQL：严格遵循SQL标准

6.3 NULL的替代方案

在某些场景下，可以考虑避免使用NULL：

1. 使用特殊值代替NULL（如-1、""、"NULL"等）
2. 使用单独的布尔字段标记记录状态
3. 使用关联表表示可选属性

7. 性能优化建议

7.1 索引设计

对于需要频繁查询NULL值的字段：

sql复制-- 普通索引
CREATE INDEX idx_status ON user(status);

-- 对于NULL值较多的字段，可以考虑函数索引
CREATE INDEX idx_status_null ON user((status IS NULL));

7.2 查询重写

某些情况下可以重写查询逻辑：

java复制// 原始查询
wrapper.ne("status", 1).or().isNull("status");

// 可以重写为
wrapper.notIn("status", 1);  // 如果业务允许

7.3 分页查询优化

当使用分页查询包含NULL条件时：

java复制// 不推荐 - 性能较差
Page<User> page = new Page<>(1, 10);
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.ne("status", 1).or().isNull("status");
userMapper.selectPage(page, wrapper);

// 推荐 - 使用JOIN或子查询优化
String sql = "SELECT * FROM user WHERE status <> 1 OR status IS NULL LIMIT 10";
userMapper.selectList(new QueryWrapper<User>().apply(sql));

8. 框架扩展建议

8.1 自定义Wrapper

可以继承QueryWrapper实现更智能的NULL处理：

java复制public class SmartQueryWrapper<T> extends QueryWrapper<T> {
    public SmartQueryWrapper<T> neWithNull(String column, Object val) {
        return (SmartQueryWrapper<T>) this.ne(column, val).or().isNull(column);
    }
}

8.2 AOP处理

通过AOP自动处理NULL条件：

java复制@Aspect
@Component
public class NullQueryAspect {
    @Around("execution(* com..mapper.*Mapper.select*(..)) && args(ew,..)")
    public Object handleNullQuery(ProceedingJoinPoint joinPoint, Wrapper<?> ew) throws Throwable {
        if (ew instanceof QueryWrapper) {
            // 分析并修改QueryWrapper
        }
        return joinPoint.proceed();
    }
}

8.3 自定义方言

对于复杂项目，可以实现数据库方言来处理NULL：

java复制public class NullAwareDialect extends MySqlDialect {
    @Override
    public String buildCondition(String column, String operator, Object value) {
        if ("<>".equals(operator) && value == null) {
            return column + " IS NOT NULL";
        }
        return super.buildCondition(column, operator, value);
    }
}

9. 常见错误排查

9.1 问题现象：查询结果缺少NULL记录

原因：使用了ne()等比较操作但没有显式处理NULL
解决：添加OR IS NULL条件

9.2 问题现象：索引失效

原因：使用了OR条件或函数包装字段
解决：重写查询或创建适当的函数索引

9.3 问题现象：分页总数不准确

原因：COUNT查询与数据查询条件不一致
解决：确保分页查询的wrapper一致

java复制// 错误示例
Page<User> page = new Page<>(1, 10);
QueryWrapper<User> countWrapper = new QueryWrapper<>();
countWrapper.ne("status", 1);  // 缺少NULL条件

// 正确做法
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.ne("status", 1).or().isNull("status");
Page<User> page = userMapper.selectPage(new Page<>(1, 10), wrapper);

10. 实际案例分享

最近在用户管理系统中就遇到了这个问题。我们需要查询所有非活跃用户（status != 1），但发现结果比预期少了很多。经过排查发现：

1. 老系统中的用户记录很多status为NULL
2. 新代码使用wrapper.ne("status", 1)查询
3. 导致营销活动漏掉了大量目标用户

最终解决方案：

java复制public Page<User> getInactiveUsers(PageParam param) {
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.and(w -> w.ne("status", 1).or().isNull("status"))
          .orderByAsc("create_time");
    return userMapper.selectPage(param.toPage(), wrapper);
}

同时我们在用户表中添加了默认值约束，避免新的NULL记录：

sql复制ALTER TABLE user MODIFY status tinyint DEFAULT 0;