如何修復 JPA NoResultException：查詢未找到實體

1. 概述

在使用 JPA 時，我們可能會遇到NoResultException異常，這是一個執行時間錯誤，當預期傳回單一結果的查詢沒有回傳任何結果時就會拋出。這種情況通常發生在對未找到符合實體的查詢使用getSingleResult()方法時。由於該異常是未檢查異常，如果未正確處理缺失數據，容易導致意外失敗。

在本文中，我們將探討為什麼會出現這種異常，並探索防止這種異常發生的實用策略，以確保我們的應用程式保持健壯，並能優雅地處理空查詢結果。

2. 理解`NoResultException`

NoResultException繼承自PersistenceException ，當對一個沒有回傳任何結果的查詢呼叫Query.getSingleResult()時，JPA 提供者會拋出此例外。問題的核心在於getSingleResult()嚴格假設只有一個結果，而當這個假設不成立時，它會立即失敗。

我們可以在以下範例中看到這種脆弱的模式。此方法僅在存在具有給定使用者名稱的使用者時才有效；否則，它會拋出異常：

// Problematic pattern that leads to NoResultException

 public User findUserProblematic(EntityManager em, String username) {

 String jpql = "SELECT u FROM User u WHERE u.username = :username";

 TypedQuery<User> query = em.createQuery(jpql, User.class);

 query.setParameter("username", username);



 // This line throws NoResultException if no user is found

 return query.getSingleResult();

 }

這種行為與getResultList()形成對比，getResultList() 在沒有找到結果時會優雅地傳回一個空列表，提供了更安全的替代方案，我們接下來將對此進行探討。

3. 導致`NoResultException`常見場景

了解NoResultException何時何地發生是預防它的第一步。讓我們來看看在實際應用中觸發此異常的最常見場景。

3.1. 直接對空結果使用`getSingleResult()`

最簡單的情況是，開發者明確呼叫getSingleResult()而沒有驗證結果是否存在：

public User findUserByEmail(String email) {

 // This will throw NoResultException if no user with this email exists

 return entityManager

 .createQuery("SELECT u FROM User u WHERE u.email = :email", User.class)

 .setParameter("email", email)

 .getSingleResult();

 }

當資料存在時，這種方法完全有效；但當資料不存在時，則會導致意外失敗。在生產應用中，資料缺失是一種正常現象，應該優雅地處理，而不是拋出異常。

3.2. 查詢條件與資料假設錯誤

另一種常見情況是查詢依賴並非總是成立的假設。例如，代碼可能假設具有特定標識符的使用者必須始終存在。當此假設不成立時， getSingleResult()會拋出NoResultException ，將正常的無資料情況轉換為執行時間錯誤。

以下是一個此類脆弱模式的實例：

public User findUserById(Long id) {

 // Assumes the user always exists in the database

 return entityManager

 .createQuery("SELECT u FROM User u WHERE u.id = :id", User.class)

 .setParameter("id", id)

 .getSingleResult(); // Throws NoResultException if not found

 }

這些故障通常源自於有缺陷的業務邏輯、缺少驗證或底層資料不一致。

4. 解決方案和最佳實踐

既然我們已經了解了問題所在，讓我們來探討將脆弱的程式碼轉換為強大的資料存取層的實用解決方案。

4.1. 使用`getResultList()`進行大小檢查

防止出現NoResultException可靠方法是依賴getResultList() ，該函數在沒有符合行時絕對不會拋出例外。相反，它只會傳回一個空列表，讓我們能夠完全控制在未找到資料時的處理方式：

public User findUserByUsernameSafe(String username) {

 List<User> users = entityManager

 .createQuery("SELECT u FROM User u WHERE u.username = :username", User.class)

 .setParameter("username", username)

 .getResultList();



 return users.isEmpty() ? null : users.get(0);

 }

這種模式消除了意外異常的風險，並使我們能夠完全控制如何處理缺失資料。我們可以選擇傳回 null、拋出自訂業務異常，或根據應用程式的需求提供預設值。

4.2. 利用 Java `Optional`實現現代 API

Java 8 引入了Optional類，它提供了一種優雅的方式來明確地處理可能缺少的結果。這種方法使我們的 API 更具表現力，並強制呼叫程式碼處理存在和不存在兩種情況：

public Optional<User> findUserByUsernameOptional(String username) {

 List<User> users = entityManager

 .createQuery("SELECT u FROM User u WHERE u.username = :username", User.class)

 .setParameter("username", username)

 .getResultList();



 return users.isEmpty() ? Optional.empty() : Optional.of(users.get(0));

 }

Optional方法透過在方法簽章中明確說明資料缺失的可能性，鼓勵更好的程式設計實踐。它提供了一個豐富的 API 來處理這兩種情況，而無需使用空值檢查或try-catch程式碼區塊。

4.3. 利用 Spring Data JPA 實現自動安全

當我們的專案使用 Spring Data JPA 時，我們可以受益於其內建的NoResultException防護機制。此框架會自動處理空結果，並提供簡潔、安全的抽象：

// Repository interface with Optional return types

 public interface UserRepository extends JpaRepository<User, Long> {

 Optional<User> findByUsername(String username);

 Optional<User> findByEmail(String email);

 }

Spring Data JPA 的儲存庫方法會自然傳回Optional類型，無需手動檢查結果。這種方法與 Spring 生態系統無縫集成，並符合現代 Java 開發實務。

4.4. 實作自訂業務例外

對於資料缺失代表違反業務規則的情況，我們可以建立自訂異常，提供比通用NoResultException更有意義的錯誤訊息：

public class UserNotFoundException extends RuntimeException {

 public UserNotFoundException(String message) {

 super(message);

 }



 public UserNotFoundException(String message, Throwable cause) {

 super(message, cause);

 }

 }

然後，我們可以在服務層中使用此自訂異常，以提供清晰的、特定領域的錯誤處理：

@Service

 public class UserService {

 private final UserRepository userRepository;



 public UserService(UserRepository userRepository) {

 this.userRepository = userRepository;

 }



 public User findUserByUsernameOrThrow(String username) {

 return userRepository.findByUsername(username)

 .orElseThrow(() -> new UserNotFoundException("User not found: " + username));

 }



 public User findUserByEmailOrThrow(String email) {

 return userRepository.findByEmail(email)

 .orElseThrow(() -> new UserNotFoundException("User not found: " + email));

 }

 }

這種方法將技術故障轉化為有意義的業務錯誤，為客戶提供清晰的錯誤訊息、更好的 API 回應和更輕鬆的調試，同時將業務規則與技術問題清晰分離。

5. 結論

NoResultException異常在 JPA 中很常見，通常發生在程式碼假定查詢總是會傳回結果時。一旦我們了解了導致此異常的條件，就可以採用更安全的實踐，使應用程式能夠優雅地處理缺失資料。透過使用getResultList() 、回傳Optional<T> 、實作自訂業務異常或利用 Spring Data JPA 等方法，我們可以建立一個更具彈性和可預測性的資料存取層。

這些技術有助於確保缺少的記錄不會中斷應用程式流程，並使我們的持久化邏輯保持清晰、一致和強壯。

和往常一樣，原始碼可以在 GitHub 上找到。

本作品係原創或者翻譯，採用《署名-非商業性使用-禁止演繹4.0國際》許可協議

如何修復 JPA NoResultException：查詢未找到實體

1. 概述

2. 理解NoResultException

3. 導致NoResultException常見場景

3.1. 直接對空結果使用getSingleResult()