1. Overview
1.概述
In this tutorial, we’ll explore the nuances of implementing a global exception-handling strategy within Spring Cloud Gateway, delving into its technicalities and best practices.
在本教程中，我们将探讨在 Spring Cloud Gateway 中实施全局异常处理策略的细微差别，深入研究其技术细节和最佳实践。
In modern software development, especially in microservices, efficient management of APIs is crucial. This is where Spring Cloud Gateway plays an important role as a key component of the Spring ecosystem. It acts like a gatekeeper, directing traffic and requests to the appropriate microservices and providing cross-cutting concerns, such as security, monitoring/metrics, and resiliency.
在现代软件开发中，尤其是在微服务中，API 的高效管理至关重要。这就是 Spring Cloud Gateway 作为 Spring 生态系统关键组件发挥重要作用的地方。它就像一个守门员，将流量和请求引导到适当的微服务，并提供跨领域的关注，例如安全性、监控/度量和弹性。
However, in such a complex environment, the certainty of exceptions due to network failures, service downtime, or application bugs demands a robust exception-handling mechanism. The global exception handling in Spring Cloud Gateway ensures a consistent approach for error handling across all services and enhances the entire system’s resilience and reliability.
然而，在这样一个复杂的环境中，由于网络故障、服务停机或应用程序错误而导致的异常是肯定会发生的，这就需要一个强大的异常处理机制。Spring云网关中的全局异常处理可确保在所有服务中采用一致的错误处理方法，并增强整个系统的弹性和可靠性。
2. The Need for Global Exception Handling
2.全局异常处理的必要性
Spring Cloud Gateway is a project part of the Spring ecosystem, designed to serve as an API gateway in microservices architectures, and its main role is to route requests to the appropriate microservices based on pre-established rules. The Gateway provides functionalities like security (authentication and authorization), monitoring, and resilience (circuit breakers). By handling requests and directing them to appropriate backend services, it effectively manages cross-cutting concerns like security and traffic management.
Spring Cloud Gateway 是 Spring 生态系统中的一个项目，旨在作为微服务架构中的 API 网关，其主要作用是根据预先制定的规则将请求路由到相应的微服务。网关提供的功能包括安全性（验证和授权）、监控和弹性（断路器）。通过处理请求并将其引导至适当的后端服务，它可以有效管理安全和流量管理等跨领域问题。
In distributed systems like microservices, exceptions may arise from multiple sources, such as network issues, service unavailability, downstream service errors, and application-level bugs, which are common culprits. In such environments, handling exceptions in a localized manner (i.e., within each service) can lead to fragmented and inconsistent error handling. This inconsistency can make debugging cumbersome and degrade the user’s experience:
在微服务等分布式系统中，异常可能来自多个方面，如网络问题、服务不可用、下游服务错误和应用程序级错误，这些都是常见的罪魁祸首。在这种环境下，以本地化的方式（即在每个服务内）处理异常可能会导致零散和不一致的错误处理。这种不一致性会使调试工作变得繁琐，并降低用户体验：
Global exception handling addresses this challenge by providing a centralized exception management mechanism that ensures that all exceptions, regardless of their source, are processed consistently, providing standardized error responses.
全局异常处理通过提供集中的异常管理机制，确保所有异常（无论其来源如何）都能得到一致的处理，并提供标准化的错误响应，从而应对这一挑战。
This consistency is critical for system resilience, simplifying error tracking and analysis. It also enhances the user’s experience by providing a precise and consistent error format, helping users understand what went wrong.
这种一致性对于系统恢复能力、简化错误跟踪和分析至关重要。它还能提供精确一致的错误格式，帮助用户了解出错的原因，从而提升用户体验。
3. Implementing Global Exception Handling in Spring Cloud Gateway
3.在 Spring 云网关中实现全局异常处理
Implementing global exception handling in Spring Cloud Gateway involves several critical steps, each ensuring a robust and efficient error management system.
在 Spring Cloud Gateway 中实施全局异常处理涉及几个关键步骤，每个步骤都能确保建立一个强大而高效的错误管理系统。
3.1. Creating a Custom Global Exception Handler
3.1.创建自定义全局异常处理程序
A global exception handler is essential for catching and handling exceptions that occur anywhere within the Gateway. To do that, we need to extend AbstractErrorWebExceptionHandler and add it to the Spring context. By doing so, we create a centralized handler that intercepts all exceptions.
全局异常处理程序对于捕获和处理网关中任何地方出现的异常至关重要。为此，我们需要扩展 AbstractErrorWebExceptionHandler 并将其添加到 Spring 上下文中。这样，我们就可以创建一个集中式处理程序来拦截所有异常。
@Component
public class CustomGlobalExceptionHandler extends AbstractErrorWebExceptionHandler {
// Constructor and methods
}
This class should be designed to handle various types of exceptions, from general exceptions like NullPointerException to more specific ones like HttpClientErrorException. The goal is to cover a broad spectrum of possible errors. The main method of such a class is shown below.
该类应能处理各种类型的异常，从 NullPointerException 等一般异常到 HttpClientErrorException 等更具体的异常。我们的目标是涵盖各种可能的错误。该类的主方法如下所示。
@Override
protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
return RouterFunctions.route(RequestPredicates.all(), this::renderErrorResponse);
}
// other methods
In this method, we can apply a handler function to the error based on a predicate evaluated using the current request and deal with it properly. It’s important to notice that the global exception handler only deals with exceptions thrown within the gateway context. That means response codes like 5xx or 4xx are not included in the context of the global exception handler, and those should be handled using route or global filters.
在此方法中，我们可以根据使用当前请求评估的 predicate 对错误应用处理函数，并对其进行正确处理。需要注意的是，全局异常处理程序仅处理网关上下文中抛出的异常。这意味着全局异常处理程序的上下文中不包括 5xx 或 4xx 等响应代码，这些代码应使用路由或全局过滤器进行处理。
The AbstractErrorWebExceptionHandler offers many methods that help us deal with the exceptions thrown during the request handling.
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;
}
}Looking at the code above, two methods provided by the Spring team are relevant. These are getErrorAttributes() and getError(), and such methods provide context as well as error information, which are important to handle the exceptions properly.
查看上面的代码，Spring 团队提供了两个相关的方法。这两个方法是 getErrorAttributes() 和 getError()， 这些方法提供了上下文和错误信息，这对于正确处理异常非常重要。
Finally, these methods collect the data provided by Spring context, hide some details, and adjust the status code and response based on the exception type. The CustomRequestAuthException and RateLimitRequestException are custom exceptions that will be further explored soon.
最后，这些方法会收集 Spring 上下文提供的数据，隐藏一些细节，并根据异常类型调整状态代码和响应。CustomRequestAuthException和RateLimitRequestException是自定义异常，我们即将对其进行进一步探讨。
3.2. Configuring the GatewayFilter
3.2.配置网关过滤器</em
The gateway filters are components that intercept all incoming requests and outgoing responses:
网关过滤器是拦截所有传入请求和传出响应的组件：
By implementing GatewayFilter or GlobalFilter and adding it to the Spring context, we ensure that requests are handled uniformly and properly
通过实施GatewayFilter或GlobalFilter并将其添加到 Spring 上下文，我们可以确保请求得到统一和正确的处理。
public class MyCustomFilter implements GatewayFilter {
// Implementation details
}
This filter can be used to log incoming requests, which is helpful for debugging. In the event of an exception, the filter should redirect the flow to the GlobalExceptionHandler. The difference between them is that GlobalFilter targets all upcoming requests, while GatewayFilter targets particular routes defined in the RouteLocator.
该过滤器可用于记录传入的请求，这有助于调试。如果出现异常，过滤器应将流程重定向到 GlobalExceptionHandler。它们之间的区别在于，GlobalFilter 针对所有即将到来的请求，而 GatewayFilter 则针对 RouteLocator 中定义的特定路由。
Next, let’s have a look at two samples of filter implementations:
接下来，让我们看看两个过滤器实现的示例：
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");
}
}The MyCustomFilter in our sample simulates a gateway validation. The idea was to fail and avoid the request if no authorization header is present. If that were the case, the exception would be thrown, handing the error to the global exception handler.
我们示例中的 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);
}
}
Lastly, in MyGlobalFilter, the filter checks all requests but only fails for a particular route. It simulates the validation of a rate limit using headers. As it is a GlobalFilter, we need to add it to the Spring context.
最后，在 MyGlobalFilter 中， 过滤器会检查所有请求，但只对特定路由无效。它使用标头模拟了对速率限制的验证。由于这是一个 GlobalFilter，因此我们需要将其添加到 Spring 上下文中。
Once again, once the exception happens, the global exception handler takes care of response management.
同样，一旦发生异常，全局异常处理程序就会负责响应管理。
3.3. Uniform Exception Handling
3.3.统一异常处理
Consistency in exception handling is vital. This involves setting up a standard error response format, including the HTTP status code, an error message (response body), and any additional information that might be helpful for debugging or user comprehension.
异常处理的一致性至关重要。这包括设置标准的错误响应格式，包括 HTTP 状态代码、错误消息（响应体）以及任何有助于调试或用户理解的附加信息。
private Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
// Define our error response structure here
}
Using this approach, we can adapt the response based on the exception type. For example, a 500 Internal Server problem indicates a server-side exception, a 400 Bad Request indicates a client-side problem, and so on. As we saw in our sample, Spring context already provides some data, but the response can be customized.
使用这种方法，我们可以根据异常类型调整响应。例如，500 Internal Server 问题表示服务器端异常，400 Bad Request 表示客户端问题，等等。正如我们在示例中看到的，Spring 上下文已经提供了一些数据，但响应还可以自定义。
4. Advanced Considerations
4.高级考虑因素
Advanced considerations include implementing enhanced logging for all exceptions. This can involve integrating external monitoring and logging tools like Splunk, ELK Stack, etc. Additionally, categorizing exceptions and customizing error messages based on these categories can significantly aid in troubleshooting and improving user communication.
高级考虑因素包括对所有异常情况实施增强型日志记录。这可能需要集成外部监控和日志记录工具，如 Splunk、ELK Stack 等。此外，对异常情况进行分类，并根据这些类别定制错误信息，可大大有助于故障排除和改善用户沟通。
Testing is crucial to ensure the effectiveness of your global exception handlers. This involves writing unit and integration tests to simulate various exception scenarios. Tools like JUnit and Mockito are instrumental in this process, allowing you to mock services and test how your exception handler responds to different exceptions.
测试对于确保全局异常处理程序的有效性至关重要。这包括编写单元测试和集成测试来模拟各种异常情况。JUnit 和 Mockito 等工具在此过程中发挥了重要作用，让您可以模拟服务并测试异常处理程序如何响应不同的异常。
5. Conclusion
5.结论
Best practices in implementing global exception handling include keeping the error-handling logic simple and comprehensive. It’s important to log every exception for future analysis and periodically update the handling logic as new exceptions are identified. Regularly reviewing the exception-handling mechanisms also helps keep up with the evolving microservices architecture.
实施全局异常处理的最佳实践包括保持错误处理逻辑简单而全面。重要的是记录每个异常，以便将来进行分析，并在发现新异常时定期更新处理逻辑。定期审查异常处理机制还有助于跟上不断发展的微服务架构。
Implementing global exception handling in Spring Cloud Gateway is crucial to developing robust microservices architecture. It ensures a consistent error-handling strategy across all services and significantly improves the system’s resilience and reliability. Developers can build a more user-friendly and maintainable system by following this article’s implementation strategies and best practices.
在 Spring Cloud Gateway 中实施全局异常处理对于开发稳健的微服务架构至关重要。它可确保所有服务采用一致的错误处理策略，并显著提高系统的弹性和可靠性。开发人员可以按照本文的实施策略和最佳实践，构建一个更易于使用和维护的系统。
As usual, all code samples used in this article are available over on GitHub.
与往常一样，本文中使用的所有代码示例均可在 GitHub 上获取。