基於 Spring Cloud Gateway 的全局異常處理

1. 概述

在本教程中，我們將深入探討在 Spring Cloud Gateway 中實施全局異常處理策略的細微之處，深入瞭解其技術細節和最佳實踐。

在現代軟件開發中，尤其是在微服務環境中，API 的高效管理至關重要。這正是 Spring Cloud Gateway 在 Spring 生態系統中發揮重要作用的地方。它就像一個看門人，引導流量和請求到適當的微服務，並提供諸如安全、監控/指標和彈性復原等橫切關注點。

然而，在如此複雜的環境中，由於網絡故障、服務停機或應用程序錯誤導致的確定性異常要求我們採用強大的異常處理機制。 Spring Cloud Gateway 中的全局異常處理確保了所有服務中一致的錯誤處理方法，並增強了整個系統的彈性與可靠性。

2. 全局異常處理的需求

Spring Cloud Gateway 是 Spring 生態系統中的一個項目，旨在作為微服務架構中的 API 網關使用，其主要作用是根據預先確定的規則將請求路由到適當的微服務。Gateway 提供諸如安全（身份驗證和授權）、監控和彈性（斷路器）等功能。通過處理請求並將它們引導到適當的後端服務，它有效地管理諸如安全和流量管理等橫切關注點。

在微服務等分佈式系統中，異常可能來自多個來源，例如網絡問題、服務不可用、下游服務錯誤和應用程序級錯誤，這些都是常見的罪魁禍首。在這種環境中，如果僅在每個服務內部處理異常，則會導致不一致和不連貫的錯誤處理。這種不一致性會使調試變得困難，並降低用户體驗：

全局異常處理解決了這一挑戰，它提供了一個集中式異常管理機制，以確保無論異常的來源如何，都將以一致的方式處理異常，從而提供標準化的錯誤響應。

這種一致性對於系統彈性至關重要，可以簡化錯誤跟蹤和分析。它還可以通過提供精確和一致的錯誤格式來增強用户體驗，幫助用户瞭解發生了什麼問題。

3. 在 Spring Cloud Gateway 中實施全局異常處理

實施在 Spring Cloud Gateway 中全局異常處理涉及多個關鍵步驟，每個步驟都確保了健壯且高效的錯誤管理系統。

3.1. 創建自定義全局異常處理器

全局異常處理器對於捕獲和處理 Gateway 內發生的任何異常至關重要。為此，我們需要擴展 `AbstractErrorWebExceptionHandler 並將其添加到 Spring 上下文中。這樣做將創建一個集中化的處理程序，用於攔截所有異常。

@Component
public class CustomGlobalExceptionHandler extends AbstractErrorWebExceptionHandler {
    // Constructor and methods
}

本類應該設計用於處理各種類型的異常，從通用的異常，如NullPointerException，到更具體的異常，如HttpClientErrorException。目標是覆蓋可能出現的各種錯誤範圍。此類中的主方法如下所示。

@Override
protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
    return RouterFunctions.route(RequestPredicates.all(), this::renderErrorResponse);
}

// other methods

通過這種方法，我們可以根據當前請求對錯誤應用一個處理函數，並妥善處理它們。請注意，全局異常處理程序僅處理在網關上下文中拋出的異常。這意味着像 5xx 或 4xx 這樣的響應代碼不包含在全局異常處理程序的上下文中，這些代碼應該使用路由或全局過濾器進行處理。

AbstractErrorWebExceptionHandler 提供了許多方法，幫助我們處理請求處理過程中拋出的異常。

private Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
    ErrorAttributeOptions options = ErrorAttributeOptions.of(ErrorAttributeOptions.Include.MESSAGE);
    Map<String, Object> errorPropertiesMap = getErrorAttributes(request, options);
    Throwable throwable = getError(request);
    HttpStatusCode httpStatus = determineHttpStatus(throwable);

    errorPropertiesMap.put("status", httpStatus.value());
    errorPropertiesMap.remove("error");

    return ServerResponse.status(httpStatus)
      .contentType(MediaType.APPLICATION_JSON_UTF8)
      .body(BodyInserters.fromObject(errorPropertiesMap));
}

private HttpStatusCode determineHttpStatus(Throwable throwable) {
    if (throwable instanceof ResponseStatusException) {
        return ((ResponseStatusException) throwable).getStatusCode();
    } else if (throwable instanceof CustomRequestAuthException) {
        return HttpStatus.UNAUTHORIZED;
    } else if (throwable instanceof RateLimitRequestException) {
        return HttpStatus.TOO_MANY_REQUESTS;
    } else {
        return HttpStatus.INTERNAL_SERVER_ERROR;
    }
}

查看上述代碼，Spring 團隊提供了兩種相關方法。它們分別是 getErrorAttributes() 和 getError()，這些方法提供上下文信息以及錯誤信息，對於正確處理異常至關重要。

最後，這些方法收集了 Spring 上下文提供的數據，隱藏了一些細節，並根據異常類型調整狀態碼和響應。 CustomRequestAuthException 和 RateLimitRequestException 是將在稍後進一步探索的自定義異常。

3.2. 配置 GatewayFilter

<a href="https://docs.spring.io/spring-cloud-gateway/docs/current/reference/html/#gateway-starter">網關過濾器</a> 是攔截所有傳入請求和傳出響應的組件：

通過實現 GatewayFilter 或 GlobalFilter 並將其添加到 Spring 上下文中，我們可以確保請求得到一致和正確的處理。

public class MyCustomFilter implements GatewayFilter {
    // Implementation details
}

此過濾器可用於記錄傳入的請求，這對於調試非常有用。如果發生異常，過濾器應將流程重定向到 GlobalExceptionHandler。它們之間的區別在於，GlobalFilter 針對所有即將來的請求，而 GatewayFilter 針對在 RouteLocator 中定義的特定路由。

接下來，讓我們看一下兩個過濾器的實現示例：

public class MyCustomFilter implements GatewayFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        if (isAuthRoute(exchange) && !isAuthorization(exchange)) {
            throw new CustomRequestAuthException("Not authorized");
        }

        return chain.filter(exchange);
    }

    private static boolean isAuthorization(ServerWebExchange exchange) {
        return exchange.getRequest().getHeaders().containsKey("Authorization");
    }

    private static boolean isAuthRoute(ServerWebExchange exchange) {
        return exchange.getRequest().getURI().getPath().equals("/test/custom_auth");
    }
}

在我們的示例中，MyCustomFilter 模擬了一個網關驗證。其目的是在缺少授權標頭時失敗並阻止請求。如果發生這種情況，異常將被拋出，並將錯誤傳遞給全局異常處理程序。

@Component
class MyGlobalFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        if (hasReachedRateLimit(exchange)) {
            throw new RateLimitRequestException("Too many requests");
        }

        return chain.filter(exchange);
    }

    private boolean hasReachedRateLimit(ServerWebExchange exchange) {
        // Simulates the rate limit being reached
        return exchange.getRequest().getURI().getPath().equals("/test/custom_rate_limit") && 
          (!exchange.getRequest().getHeaders().containsKey("X-RateLimit-Remaining") || 
            Integer.parseInt(exchange.getRequest().getHeaders().getFirst("X-RateLimit-Remaining")) <= 0);
    }
}

最後，在 MyGlobalFilter 中，過濾器會檢查所有請求，但僅在特定路由上失敗。它通過檢查 HTTP 頭部模擬了速率限制的驗證。由於這是一個 GlobalFilter，因此需要將其添加到 Spring 上下文中。

再次強調，一旦發生異常，全局異常處理器會負責響應管理。

3.3. 統一異常處理

在異常處理中保持一致性至關重要。 這包括建立標準錯誤響應格式，包括 HTTP 狀態碼、錯誤消息（響應體）以及任何可能對調試或用户理解有幫助的額外信息。

private Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
    // Define our error response structure here
}

使用這種方法，我們可以根據異常類型來調整響應。例如，500 Internal Server 錯誤表明服務器端異常，400 Bad Request 錯誤表明客户端問題，以此類推。正如我們在示例中看到的，Spring 上下文已經提供了一些數據，但響應可以進行自定義。

4. 高級考量

高級考量包括為所有異常情況實施增強的日誌記錄。這可能涉及集成外部監控和日誌工具，例如 Splunk、ELK Stack 等。此外，對異常進行分類並根據這些類別自定義錯誤消息，可以顯著幫助故障排除和改善用户溝通。

測試對於確保全局異常處理程序的有效性至關重要。這涉及編寫單元測試和集成測試，以模擬各種異常場景。 JUnit 和 Mockito 等工具在這一過程中發揮着重要作用，允許您模擬服務並測試異常處理程序對不同異常的響應。

5. 結論

實施全局異常處理的最佳實踐包括保持錯誤處理邏輯簡潔且全面。重要的是記錄每種異常以供未來分析，並定期更新處理邏輯，因為新的異常會被識別出來。 定期審查異常處理機制也有助於跟上微服務架構的演變。

在 Spring Cloud Gateway 中實施全局異常處理至關重要，可以幫助構建健壯的微服務架構。它確保了所有服務之間的一致的錯誤處理策略，並顯著提高了系統的彈性與可靠性。遵循本文的實施策略和最佳實踐，開發者可以構建一個更用户友好且易於維護的系統。

知識庫 / Spring / Spring Cloud RSS 訂閱