在 JPA 中使用 @Query 执行原生 UPDATE 语句时，必须同时添加 @Modifying 注解并设置 nativeQuery = true，否则操作不会生效或抛出异常；还需显式指定 WHERE 条件以避免全表更新，并推荐使用 void 返回类型。
在 jpa 中使用 `@query` 执行原生 update 语句时，必须同时添加 `@modifying` 注解并设置 `nativequery = true`，否则操作不会生效或抛出异常；还需显式指定 where 条件以避免全表更新，并推荐使用 `void` 返回类型。
JPA 默认将 @Query 视为只读查询（SELECT），即使 SQL 语法是 UPDATE，框架也不会执行写操作——除非显式声明其为修改型操作。因此，正确编写原生 UPDATE 查询需满足三个关键条件：
-
启用原生 SQL 支持：通过
nativeQuery = true告知 JPA 当前 SQL 直接面向数据库方言，不经过 JPQL 解析； -
声明修改意图：添加
@Modifying注解，使 Spring Data JPA 启用事务上下文并绕过一级缓存校验； -
确保数据安全性：UPDATE 语句必须包含明确的
WHERE子句（如WHERE CUSTOMER_ID = :customerId），否则将导致全表误更新，且 JPA 不会自动校验该风险。
✅ 正确示例：
@Repository
public interface CustomerRepository extends JpaRepository<customer long> {
@Modifying
@Query(value = "UPDATE CUSTOMER SET NAME = :name, PHONE = :phone WHERE CUSTOMER_ID = :customerId", nativeQuery = true)
void updateCustomerWithNameAndPhone(
@Param("name") String name,
@Param("phone") String phone,
@Param("customerId") Long customerId
);
}</customer>
⚠️ 注意事项：
- 方法必须在
@Transactional边界内调用（通常由服务层方法标注），否则抛出TransactionRequiredException； -
@Modifying默认清空一级缓存（clearAutomatically = true），若需保留缓存可设为false，但需自行处理实体状态一致性； - 不建议返回
Customer对象——原生 UPDATE 不触发实体加载与托管，返回值为空或引发IncorrectResultSizeDataAccessException；如需获取更新后实体，应单独执行findById()； - 若需获取影响行数，可将返回类型改为
int（Spring Data JPA 自动映射UPDATE的rowCount）：@Modifying @Query(value = "UPDATE CUSTOMER SET NAME = :name WHERE CUSTOMER_ID = :id", nativeQuery = true) int updateNameById(@Param("name") String name, @Param("id") Long id);
总结：原生 UPDATE 不是“写完 SQL 就能跑”，而是 JPA 事务、注解契约与 SQL 安全性的协同结果。始终遵循 @Modifying + nativeQuery = true + WHERE + @Transactional 四要素，才能确保更新逻辑可靠、可测、可维护。
