在 JPA 中使用 @Query 编写原生 UPDATE 语句时，必须同时添加 @Modifying 注解并设置 nativeQuery = true，否则操作不会生效且可能抛出异常；还需显式指定 WHERE 条件以避免全表更新，并注意事务管理。
在 jpa 中使用 `@query` 编写原生 update 语句时，必须同时添加 `@modifying` 注解并设置 `nativequery = true`，否则操作不会生效且可能抛出异常；还需显式指定 where 条件以避免全表更新，并注意事务管理。
在 Spring Data JPA 中，原生 SQL 的 UPDATE 操作与普通查询有本质区别：它属于数据修改操作（DML），而默认的 @Query 仅支持 SELECT 类型的查询（DQL）。若未正确配置，JPA 会忽略该语句或抛出 InvalidDataAccessResourceUsageException 等异常，导致“无响应”或“返回无关结果”的现象。
✅ 正确写法要点
-
必须添加
@Modifying注解：告知 Spring 这是一个修改数据库的操作； -
必须设置
nativeQuery = true：明确声明为原生 SQL（非 JPQL）； -
必须包含
WHERE子句：防止误更新整张表（如原示例缺失条件，将批量修改所有客户）； -
推荐返回
void或int（影响行数）：JPA 不支持原生 UPDATE 直接映射为实体返回；若需获取更新后的数据，应另发一次SELECT查询； -
确保方法运行在事务中：
@Modifying方法默认不自动开启事务，需由调用方（如 Service 层）使用@Transactional包裹。
✅ 示例代码
@Repository
public interface CustomerRepository extends JpaRepository<Customer, Long> {
@Modifying
@Query(value = "UPDATE CUSTOMER SET NAME = :name, PHONE = :phone WHERE CUSTOMER_ID = :customerId", nativeQuery = true)
int updateCustomerWithNameAndPhone(
@Param("name") String name,
@Param("phone") String phone,
@Param("customerId") Long customerId
);
}? 返回类型建议使用
int（表示实际更新的行数），便于校验执行结果。例如：@Transactional public void updateCustomer(Long id, String name, String phone) { int updated = customerRepository.updateCustomerWithNameAndPhone(name, phone, id); if (updated == 0) { throw new EntityNotFoundException("Customer not found with id: " + id); } }
⚠️ 常见错误与注意事项
- ❌ 错误：遗漏
@Modifying→ 报错org.springframework.dao.InvalidDataAccessResourceUsageException: Modifying queries can only use void or int/Integer as return type! - ❌ 错误：未加
nativeQuery = true→ JPA 尝试解析为 JPQL，导致语法错误（如CUSTOMER表名不被识别） - ❌ 错误：缺少
WHERE条件 → 全表更新，数据严重损坏 - ⚠️ 注意：
@Modifying(clearAutomatically = true)可选参数，用于清空一级缓存，避免后续查询读到脏数据（适用于长事务场景） - ⚠️ 注意：H2、MySQL 等数据库对
UPDATE ... RETURNING支持不同，JPA 原生查询不支持自动返回更新后实体；如需最新数据，请单独调用findById()或使用@Query+SELECT组合实现。
通过规范使用 @Modifying 与 nativeQuery = true，并配合事务控制和安全条件约束，即可在 JPA 中安全、高效地执行原生 UPDATE 操作。
