MyBatis-Flex 中 insertOrUpdate 方法的正确使用方式

理解 insertOrUpdate 的工作原理

MyBatis-Flex 是一个基于 MyBatis 的增强框架，提供了许多便捷的 CRUD 操作方法。其中 insertOrUpdate 方法是一个非常有用的功能，它可以根据条件自动决定是执行插入还是更新操作。

常见误解

许多开发者（特别是从其他 ORM 框架如 JPA 转过来的）可能会误以为 insertOrUpdate 的工作逻辑是：

1. 先根据实体对象的主键值查询数据库
2. 如果数据库中存在该主键记录，则执行更新
3. 如果不存在，则执行插入

但实际上 MyBatis-Flex 的实现逻辑完全不同。

实际工作原理

MyBatis-Flex 的 insertOrUpdate 方法判断逻辑是：

1. 仅检查实体对象本身的主键字段是否有值（是否为 null 或默认值）

   • 如果主键有值，则执行更新操作
   • 如果主键无值，则执行插入操作

2. 完全不涉及数据库查询，不会检查数据库中是否已存在该记录

这种设计主要是出于性能考虑，避免了额外的查询操作。

典型问题场景分析

开发者在使用 insertOrUpdate 时常见的问题包括：

1. 期望插入但实际无操作：当手动设置了主键值（但数据库中不存在该记录）时，框架会尝试更新，但由于数据库中没有匹配记录，更新行数为0，最终表现为"无操作"。

2. 期望更新但实际插入：当未设置主键值时，框架会执行插入，即使数据库中可能存在其他字段值相同的记录。

解决方案

方案1：明确区分使用场景

1. 明确需要插入时：直接使用 insert 方法
2. 明确需要更新时：使用 update 方法
3. 不确定主键是否存在时：先查询再决定使用 insert 或 update

方案2：自定义 BaseMapper 实现

对于习惯 JPA save 逻辑的开发者，可以自定义一个增强的 Mapper 接口：

public interface CustomBaseMapper<T> extends BaseMapper<T> {
    @Override
    default int insertOrUpdate(T entity) {
        return insertOrUpdate(entity, false);
    }

    @Override
    default int insertOrUpdate(T entity, boolean ignoreNulls) {
        // 先尝试更新
        int affectedNum = BaseMapper.super.insertOrUpdate(entity, ignoreNulls);
        // 如果更新未影响任何行，则尝试插入
        if (affectedNum <= 0) {
            return BaseMapper.super.insert(entity);
        }
        return affectedNum;
    }

    @Override
    default int insertOrUpdateSelective(T entity) {
        return insertOrUpdate(entity);
    }
}

然后让业务 Mapper 继承这个自定义接口：

@Mapper
public interface AccountMapper extends CustomBaseMapper<Account> {
}

方案3：使用事务+查询组合

对于需要精确控制的场景，可以使用事务包装查询+操作：

@Transactional
public void saveOrUpdate(Account account) {
    Account dbAccount = accountMapper.selectOneById(account.getId());
    if (dbAccount != null) {
        accountMapper.update(account);
    } else {
        accountMapper.insert(account);
    }
}

性能考量

MyBatis-Flex 默认实现不先查询数据库的设计有以下优点：

1. 减少一次数据库查询：提高性能
2. 简化逻辑：代码更简洁
3. 避免竞态条件：在高并发场景下更安全

但同时也带来了需要开发者明确理解其行为的要求。

最佳实践建议

1. 明确操作意图：如果明确知道是插入还是更新，直接使用对应方法
2. 主键生成策略：合理配置主键生成策略（如自增、UUID等）
3. 批量操作处理：批量操作时考虑使用专门的方法
4. 日志记录：关键操作添加适当日志
5. 单元测试：对数据持久化逻辑编写充分的测试用例

理解框架的设计哲学和实现细节，才能更好地利用其提供的功能，避免误用和潜在问题。MyBatis-Flex 的这种设计在大多数场景下能够提供更好的性能，只需要开发者调整使用习惯即可。