Spring Boot数据库宕机返回404 如何向调用方返回正确异常

数据库宕机时返回404而非对应JDBC异常的核心原因有两点：

• Eureka实例自动摘除逻辑触发：Spring Boot Actuator默认将数据库健康检查失败判定为整个服务不可用，服务实例会被Eureka标记为DOWN状态并从可用实例列表剔除。客户端调用时负载均衡组件找不到可用实例，直接返回404响应，请求根本没有到达业务服务，自然无法抛出JDBC层的异常。
• 异常链路吞错：少数场景下请求已经到达业务服务，但HikariCP连接获取失败异常、Spring Data JPA抛出的数据访问异常没有被全局异常处理器捕获，被Spring MVC默认的无匹配路由逻辑兜底，错误返回404状态码。

1. 调整健康检查与Eureka摘除规则 #

避免数据库宕机时服务被直接剔除，导致请求无法到达业务层，在application.yml中添加如下配置：

management:
  endpoint:
    health:
      show-details: always
      status:
        http-mapping:
          # 健康检查失败返回503而非直接触发实例下线
          DOWN: 503
  health:
    db:
      enabled: true
eureka:
  instance:
    lease-renewal-interval-in-seconds: 5
    lease-expiration-duration-in-seconds: 15
spring:
  datasource:
    hikari:
      # 连接失败时快速抛出异常，不要长时间重试吞错
      fail-fast: true
      connection-timeout: 1000
      validation-timeout: 500

2. 配置全局异常处理器捕获数据库相关异常 #

添加全局异常拦截逻辑，统一捕获JDBC连接、Spring数据访问层抛出的异常，返回匹配故障的状态码和信息：

import org.springframework.dao.DataAccessResourceFailureException;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.sql.SQLException;
import java.util.Map;

@RestControllerAdvice
public class BizExceptionHandler {

    @ExceptionHandler({DataAccessResourceFailureException.class, SQLException.class})
    @ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE)
    public Map<String, Object> handleDbDownException(Exception e) {
        Throwable cause = e.getCause() != null ? e.getCause() : e;
        return Map.of(
                "code", 503,
                "error", "Database service unavailable",
                "detail", cause.getMessage()
        );
    }
}

3. 修正网关/客户端负载均衡的异常翻译逻辑 #

如果链路中存在Spring Cloud Gateway、Ribbon或LoadBalancer组件，需要修改默认的“无可用实例返回404”规则，将服务实例不可用场景的响应码改为503，避免和资源不存在的404混淆。以Spring Cloud Gateway为例，添加全局异常处理：

import org.springframework.cloud.gateway.support.ServiceUnavailableException;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.Map;

@RestControllerAdvice
public class GatewayExceptionHandler {
    @ExceptionHandler(ServiceUnavailableException.class)
    @ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE)
    public Map<String, Object> handleNoAvailableInstance(Exception e) {
        return Map.of(
                "code", 503,
                "error", "Target service is unavailable, dependency database is down"
        );
    }
}

1. 手动停止MySQL服务，发起业务接口请求
2. 确认响应状态码为503，响应体中包含明确的数据库连接失败信息，而非404 Not Found
3. 检查服务端日志，能看到完整的JDBC连接异常、Spring数据访问异常栈，无异常被吞情况

内容的提问来源于stack exchange，提问作者Ravi