Spring Boot API设计：空查询结果的异常处理策略

在spring boot应用中，处理空查询结果是常见的挑战。本文探讨了两种主要策略：抛出`entitynotfoundexception`以返回http 404状态码，或直接返回空列表以维持http 200状态码。选择哪种策略取决于api契约、客户端期望及业务语义，旨在帮助开发者根据具体场景做出明智决策，优化api响应。

在构建RESTful API时，当数据库查询未能返回任何数据时，如何向客户端传递这一信息是一个需要深思熟虑的问题。主要有两种常见的处理策略：一是抛出异常，让全局异常处理器捕获并返回错误状态码；二是直接返回一个空的集合。这两种方法各有优劣，适用于不同的业务场景和API设计哲学。

策略一：抛出 EntityNotFoundException

当业务逻辑中查询结果为空，且我们希望明确地向客户端表明“请求的资源不存在”时，抛出EntityNotFoundException是一种有效的方式。这种方法通常与HTTP 404 (Not Found) 状态码相对应，符合RESTful API的语义，即客户端请求了一个不存在的特定资源。

示例代码：业务服务层抛出异常

import org.springframework.data.crossstore.ChangeSetPersister.EntityNotFoundException; // 或者自定义的EntityNotFoundException
import java.util.List;

// 假设 employeeRepo 是一个 JPA Repository
// private EmployeeRepository employeeRepo; 

private List findByName(String name) throws EntityNotFoundException {
    List employees = employeeRepo.findByName(name);

    if (employees.isEmpty()) {
        throw new EntityNotFoundException("未找到任何名为 '" + name + "' 的员工");
    }

    return employees;
}

在上述代码中，如果employeeRepo.findByName(name)返回一个空列表，服务层会立即抛出EntityNotFoundException。

全局异常处理器捕获

为了优雅地处理这类异常并返回统一的错误响应，Spring Boot通常会使用@RestControllerAdvice配合@ExceptionHandler。

import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.exception.ExceptionUtils;
import org.springframework.data.crossstore.ChangeSetPersister.EntityNotFoundException;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@Slf4j(topic = "GLOBAL_EXCEPTION_HANDLER")
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    // ... 其他异常处理方法 ...

    @ExceptionHandler(EntityNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity