1. Introduction
1.绪论
In this tutorial, we’ll look at how we use Spring Cloud Gateway to inspect and/or modify the response body before sending it back to a client.
在本教程中，我们将看看如何使用Spring Cloud Gateway来检查和/或修改响应体，然后再将其发回给客户端。
2. Spring Cloud Gateway Quick Recap
2.Spring的云网关快速回顾
Spring Cloud Gateway, or SCG for short, is a sub-project from the Spring Cloud family that provides an API gateway built on top of a reactive web stack. We’ve already covered its basic usage in earlier tutorials, so we won’t get into those aspects here.
Spring Cloud Gateway，简称SCG，是Spring Cloud系列的一个子项目，它提供了一个建立在反应式Web栈之上的API网关。我们已经在早期的教程中介绍了它的基本用法，因此我们在此不再讨论这些方面了。
Instead, this time we’ll focus on a particular usage scenario that arises from time to time when designing a solution around an API Gateway: how to process a backend response payload before sending it back to the client?
相反，这次我们将重点关注在围绕API网关设计解决方案时不时出现的特定使用场景：在将后端响应有效载荷送回客户端之前，如何处理它？
Here’s a list of some cases where we might use this capability:
以下是我们可能使用这种能力的一些情况。
- Keep compatibility with existing clients while allowing the backend to evolve
- Masking some fields from the responsibility to comply with regulations like PCI or GDPR
In more practical terms, fulfilling those requirements mean that we need to implement a filter to process backend responses. As filters are a core concept in SCG, all we need to do to support response processing is to implement a custom one that applies the desired transformation.
从更实际的角度来看，满足这些要求意味着我们需要实现一个过滤器来处理后端响应。由于过滤器是SCG的一个核心概念，我们需要做的就是实现一个自定义的过滤器来支持响应处理，以应用所需的转换。
Moreover, once we’ve created our filter component, we can apply it to any declared route.
此外，一旦我们创建了我们的过滤器组件，我们就可以把它应用到任何声明的路由。
3. Implementing a Data Scrubbing Filter
3.实施数据清洗过滤器
To better illustrate how response body manipulation works, let’s create a simple filter that masks values in a JSON-based response. For instance, given a JSON having a field named “ssn”:
为了更好地说明响应体的操作，让我们创建一个简单的过滤器，掩盖基于JSON的响应中的值。例如，给定一个JSON，有一个名为 “ssn “的字段。
{
"name" : "John Doe",
"ssn" : "123-45-9999",
"account" : "9999888877770000"
}We want to replace their values with a fixed one, thus preventing data leakage:
我们想用一个固定的值来替换它们的值，从而防止数据泄漏。
{
"name" : "John Doe",
"ssn" : "****",
"account" : "9999888877770000"
}3.1. Implementing the GatewayFilterFactory
3.1.实现GatewayFilterFactory
A GatewayFilterFactory is, as the name implies, a factory for filters of a given time. At startup, Spring looks for any @Component-annotated class that implements this interface. It then builds a registry of available filters that we can use when declaring routes:
顾名思义，GatewayFilterFactory是一个给定时间的过滤器工厂。在启动时，Spring会寻找任何@Component-注释的实现该接口的类。然后它建立了一个可用过滤器的注册表，我们可以在声明路由时使用。
spring:
cloud:
gateway:
routes:
- id: rewrite_with_scrub
uri: ${rewrite.backend.uri:http://example.com}
predicates:
- Path=/v1/customer/**
filters:
- RewritePath=/v1/customer/(?<segment>.*),/api/$\{segment}
- ScrubResponse=ssn,***
Notice that, when using this configuration-based approach to define routes, it is important to name our factory according to SCG’s expected naming convention: FilterNameGatewayFilterFactory. With that in mind, we’ll name our factory ScrubResponseGatewayFilterFactory.
注意，当使用这种基于配置的方法来定义路由时，必须根据SCG预期的命名惯例来命名我们的工厂。FilterNameGatewayFilterFactory。考虑到这一点，我们将把我们的工厂命名为ScrubResponseGatewayFilterFactory.。
SCG already has several utility classes that we can use to implement this factory. Here, we’ll use one that’s commonly used by the out-of-the-box filters: AbstractGatewayFilterFactory<T>, a templated base class, where T stands for the configuration class associated with our filter instances. In our case, we only need two configuration properties:
SCG已经有几个实用类，我们可以用它们来实现这个工厂。在这里，我们将使用一个常用的开箱即用的过滤器。AbstractGatewayFilterFactory<T>，一个模板化的基类，其中T代表与我们的过滤器实例相关的配置类。在我们的案例中，我们只需要两个配置属性。
- fields: a regular expression used to match against field names
- replacement: the string that will replace the original value
The key method we must implement is apply(). SCG calls this method for every route definition that uses our filter. For instance, in the configuration above, apply() will be called only once since there’s just a single route definition.
我们必须实现的关键方法是apply()。SCG为每个使用我们的过滤器的路由定义调用这个方法。例如，在上面的配置中，apply()将只被调用一次，因为只有一个路由定义。
In our case, the implementation is trivial:
在我们的案例中，实现是微不足道的。
@Override
public GatewayFilter apply(Config config) {
return modifyResponseBodyFilterFactory
.apply(c -> c.setRewriteFunction(JsonNode.class, JsonNode.class, new Scrubber(config)));
}
It is so simple in this case because we’re using another built-in filter, ModifyResponseBodyGatewayFilterFactory, to which we delegate all the grunt work related to body parsing and type conversion. We use constructor injection to get an instance of this factory, and in apply(), we delegate to it the task of creating a GatewayFilter instance.
在这种情况下，它是如此简单，因为我们使用了另一个内置的过滤器，ModifyResponseBodyGatewayFilterFactory，我们将所有与body解析和类型转换相关的grunt工作委托给它。我们使用构造函数注入来获得这个工厂的实例，并在apply()中，我们委托它创建一个GatewayFilter实例的任务。
The key point here is to use the apply() method variant that, instead of taking a configuration object, expects a Consumer for the configuration. Also important is the fact that this configuration is a ModifyResponseBodyGatewayFilterFactory one. This configuration object provides the setRewriteFunction() method we’re calling in our code.
这里的关键点是使用apply()方法的变体，该方法不是接受一个配置对象，而是期待一个配置的Consumer。同样重要的是，这个配置是一个ModifyResponseBodyGatewayFilterFactory。这个配置对象提供了我们在代码中调用的setRewriteFunction()方法。
3.2. Using setRewriteFunction()
3.2.使用setRewriteFunction()
Now, let’s get a little deeper on setRewriteFunction().
现在，让我们深入了解一下setRewriteFunction().。
This method takes three arguments: two classes (in and out) and a function that can transform from the incoming type to the outgoing. In our case, we’re not converting types, so both input and output use the same class: JsonNode. This class comes from the Jackson library and is at the very top of the hierarchy of classes used to represent different node types in JSON, such as object nodes, array nodes, and so forth. Using JsonNode as the input/output type allows us to process any valid JSON payload, which we want in this case.
这个方法需要三个参数：两个类（输入和输出）和一个可以从输入类型转换到输出的函数。在我们的例子中，我们没有转换类型，所以输入和输出都使用同一个类。JsonNode。这个类来自Jackson库，是用于表示JSON中不同节点类型（如对象节点、数组节点等）的层次结构的最顶端。使用JsonNode作为输入/输出类型允许我们处理任何有效的JSON有效载荷，在这种情况下，我们希望如此。
For the transformer class, we pass an instance of our Scrubber, which implements the required RewriteFunction interface in its apply() method:
对于转化器类，我们传递一个Scrubber的实例，它在apply()方法中实现了所需的RewriteFunction接口。
public static class Scrubber implements RewriteFunction<JsonNode,JsonNode> {
// ... fields and constructor omitted
@Override
public Publisher<JsonNode> apply(ServerWebExchange t, JsonNode u) {
return Mono.just(scrubRecursively(u));
}
// ... scrub implementation omitted
}
The first argument passed to apply() is the current ServerWebExchange, which gives us access to the request processing context so far. We won’t use it here, but it’s good to know we have this capability. The next argument is the received body, already converted to the informed in-class.
传递给apply()的第一个参数是当前的ServerWebExchange，它使我们能够访问到目前为止的请求处理上下文。我们不会在这里使用它，但知道我们有这种能力是很好的。下一个参数是接收到的主体，已经转换为类中的通知。
The expected return is a Publisher of instances of the informed out-class. So, as long we don’t do any kind of blocking I/O operation, we can do some complex work inside the rewrite function.
预期的返回是一个Publisher的被告知的out-class的实例。所以，只要我们不做任何形式的阻塞性I/O操作，我们就可以在重写函数中做一些复杂的工作。
3.3. Scrubber Implementation
3.3.洗涤器实施
So, now that we know the contract for a rewrite function, let’s finally implement our scrubber logic. Here, we’ll assume that payloads are relatively small, so we don’t have to worry about the memory requirements to store the received object.
所以，现在我们知道了重写函数的契约，最后让我们来实现我们的洗涤器逻辑。在这里，我们将假设有效载荷相对较小，所以我们不必担心存储接收对象的内存要求。
Its implementation just walks recursively over all nodes, looking for attributes that match the configured pattern and replacing the corresponding value for the mask:
它的实现只是在所有节点上递归行走，寻找符合配置模式的属性，并为掩码替换相应的值。
public static class Scrubber implements RewriteFunction<JsonNode,JsonNode> {
// ... fields and constructor omitted
private JsonNode scrubRecursively(JsonNode u) {
if ( !u.isContainerNode()) {
return u;
}
if (u.isObject()) {
ObjectNode node = (ObjectNode)u;
node.fields().forEachRemaining((f) -> {
if ( fields.matcher(f.getKey()).matches() && f.getValue().isTextual()) {
f.setValue(TextNode.valueOf(replacement));
}
else {
f.setValue(scrubRecursively(f.getValue()));
}
});
}
else if (u.isArray()) {
ArrayNode array = (ArrayNode)u;
for ( int i = 0 ; i < array.size() ; i++ ) {
array.set(i, scrubRecursively(array.get(i)));
}
}
return u;
}
}
4. Testing
4.测试
We’ve included two tests in the example code: a simple unit test and an integration one. The first is just a regular JUnit test used as a sanity check for the scrubber. The integration test is more interesting as it illustrates useful techniques in the context of SCG development.
我们在示例代码中包括两个测试：一个简单的单元测试和一个集成测试。第一个测试只是一个普通的JUnit测试，用作洗涤器的理智检查。集成测试更为有趣，因为它说明了在SCG开发中的有用技术。
Firstly, there’s the issue of providing an actual backend where messages can be sent. One possibility is to use an external tool like Postman or equivalent, which poses some issues for typical CI/CD scenarios. Instead, we’ll use JDK’s little-known HttpServer class, which implements a simple HTTP server.
首先，有一个问题是提供一个可以发送消息的实际后端。一种可能性是使用外部工具，如Postman或类似的工具，这对典型的CI/CD方案带来了一些问题。相反，我们将使用JDK中鲜为人知的HttpServer类，它实现了一个简单的HTTP服务器。
@Bean
public HttpServer mockServer() throws IOException {
HttpServer server = HttpServer.create(new InetSocketAddress(0),0);
server.createContext("/customer", (exchange) -> {
exchange.getResponseHeaders().set("Content-Type", "application/json");
byte[] response = JSON_WITH_FIELDS_TO_SCRUB.getBytes("UTF-8");
exchange.sendResponseHeaders(200,response.length);
exchange.getResponseBody().write(response);
});
server.setExecutor(null);
server.start();
return server;
}
This server will handle the request at /customer and return a fixed JSON response used in our tests. Notice that the returned server is already started and will listen to incoming requests at a random port. We’re also instructing the server to create a new default Executor to manage threads used to handle requests
这个服务器将处理/customer的请求，并返回我们测试中使用的固定JSON响应。注意，返回的服务器已经启动，并将在一个随机端口监听传入的请求。我们还指示服务器创建一个新的默认Executor来管理用于处理请求的线程
Secondly, we programmatically create a route @Bean that includes our filter. This is equivalent to building a route using configuration properties but allows us to have full control of all aspects of the test route:
其次，我们以编程方式创建一个包含我们的过滤器的路由@Bean。这相当于使用配置属性建立一个路由，但允许我们完全控制测试路由的所有方面。
@Bean
public RouteLocator scrubSsnRoute(
RouteLocatorBuilder builder,
ScrubResponseGatewayFilterFactory scrubFilterFactory,
SetPathGatewayFilterFactory pathFilterFactory,
HttpServer server) {
int mockServerPort = server.getAddress().getPort();
ScrubResponseGatewayFilterFactory.Config config = new ScrubResponseGatewayFilterFactory.Config();
config.setFields("ssn");
config.setReplacement("*");
SetPathGatewayFilterFactory.Config pathConfig = new SetPathGatewayFilterFactory.Config();
pathConfig.setTemplate("/customer");
return builder.routes()
.route("scrub_ssn",
r -> r.path("/scrub")
.filters(
f -> f
.filter(scrubFilterFactory.apply(config))
.filter(pathFilterFactory.apply(pathConfig)))
.uri("http://localhost:" + mockServerPort ))
.build();
}
Finally, with those beans now part of a @TestConfiguration, we can inject them into the actual test, together with a WebTestClient. The actual test uses this WebTestClient to drive both the spun SCG and the backend:
最后，由于这些Bean现在是@TestConfiguration的一部分，我们可以把它们和WebTestClient一起注入实际测试。实际测试使用这个WebTestClient来驱动旋转的SCG和后端。
@Test
public void givenRequestToScrubRoute_thenResponseScrubbed() {
client.get()
.uri("/scrub")
.accept(MediaType.APPLICATION_JSON)
.exchange()
.expectStatus()
.is2xxSuccessful()
.expectHeader()
.contentType(MediaType.APPLICATION_JSON)
.expectBody()
.json(JSON_WITH_SCRUBBED_FIELDS);
}
5. Conclusion
5.总结
In this article, we’ve shown how to access the response body of a backend service and modify it using the Spring Cloud Gateway library. As usual, all code is available over on GitHub.
在这篇文章中，我们展示了如何使用Spring Cloud Gateway库访问后端服务的响应体并对其进行修改。像往常一样，所有的代码都可以在GitHub上找到。