知識庫 / Spring / Spring Cloud RSS 訂閱

1. 概述

在本教程中，我們將學習如何編寫自定義 Spring Cloud Gateway 過濾器。

我們在之前的文章《探索新的 Spring Cloud Gateway》中介紹了這個框架，並對許多內置過濾器進行了瞭解。

在本場合，我們將深入探討，編寫自定義過濾器以充分發揮我們的 API Gateway 的作用。

首先，我們將瞭解如何創建全局過濾器，這些過濾器將影響 Gateway 處理的每個請求。然後，我們將編寫 Gateway 過濾器工廠，這些工廠可以針對特定路由和請求進行精細應用。

最後，我們將處理更高級的場景，學習如何修改請求或響應，甚至如何以反應式方式將請求與調用其他服務鏈接起來。

2. 項目設置

我們將首先設置一個基本的應用程序，該應用程序將用作我們的 API 網關。

2.1. Maven 配置

在使用 Spring Cloud 庫時，設置依賴管理配置以管理依賴項通常是一個不錯的選擇：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

現在我們可以添加我們的 Spring Cloud 庫，而無需指定我們實際使用的版本。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

最新 Spring Cloud Release Train 版本 可以通過 Maven Central 搜索引擎找到。當然，我們應該始終檢查該版本是否與我們正在使用的 Spring Boot 版本兼容，請參考 Spring Cloud 文檔。

2.2 API 網關配置

假設本地運行着一個應用程序，該應用程序在端口 8081 上提供一個資源（為了簡化起見，只是一個簡單的 String），當訪問 /resource 時。

考慮到這一點，我們將配置網關以將請求轉發到該服務。 簡單來説，當我們通過帶有 /service 前綴的 URI 路徑向網關發送請求時，我們將將調用轉發到該服務。

因此，當我們通過網關調用 /service/resource 時，我們應該收到 String 響應。

要實現這一點，我們將使用 應用程序屬性 配置此路由：

spring:
  cloud:
    gateway:
      routes:
      - id: service_route
        uri: http://localhost:8081
        predicates:
        - Path=/service/**
        filters:
        - RewritePath=/service(?<segment>/?.*), $\{segment}

為了能夠正確追蹤網關進程，我們還將啓用一些日誌：

logging:
  level:
    org.springframework.cloud.gateway: DEBUG
    reactor.netty.http.client: DEBUG

3. 創建全局過濾器

一旦網關處理程序確定請求與路由匹配，框架會將請求傳遞給過濾器鏈。這些過濾器可以執行邏輯，在請求發送之前或之後。

在本節中，我們將開始編寫簡單的全局過濾器。這意味着它們將影響每個單獨的請求。

首先，我們將看到如何執行在發送代理請求之前執行的邏輯（也稱為“預”過濾器）。

3.1. 編寫全局“預”過濾邏輯

正如我們所説，目前我們將創建簡單的過濾器，因為主要目標只是確保過濾器在正確的時間被執行；僅僅記錄一條簡單的消息就能達到目的。

要創建自定義全局過濾器，只需實現 Spring Cloud Gateway 的 GlobalFilter 接口，並將它作為 Bean 添加到上下文中即可。

@Component
public class LoggingGlobalPreFilter implements GlobalFilter {

    final Logger logger =
      LoggerFactory.getLogger(LoggingGlobalPreFilter.class);

    @Override
    public Mono<Void> filter(
      ServerWebExchange exchange,
      GatewayFilterChain chain) {
        logger.info("Global Pre Filter executed");
        return chain.filter(exchange);
    }
}

我們可以很容易地看到這裏發生了什麼；一旦這個過濾器被調用，我們將記錄一條消息，並繼續執行過濾器鏈。

現在，讓我們定義一個“後置”過濾器，如果對 Reactive 編程模型和 Spring Webflux API 不熟悉，可能會比較複雜。

3.2. 全局“Post”過濾器邏輯

需要注意的是，我們剛才定義的全局過濾器定義了一個 GlobalFilter 接口，其中只定義了一個方法。因此，它可以被表示為 lambda 表達式，從而方便我們定義過濾器。

例如，我們可以將“post”過濾器定義在配置類中：

@Configuration
public class LoggingGlobalFiltersConfigurations {

    final Logger logger =
      LoggerFactory.getLogger(
        LoggingGlobalFiltersConfigurations.class);

    @Bean
    public GlobalFilter postGlobalFilter() {
        return (exchange, chain) -> {
            return chain.filter(exchange)
              .then(Mono.fromRunnable(() -> {
                  logger.info("Global Post Filter executed");
              }));
        };
    }
}

簡單來説，我們在這裏在鏈式執行完成後運行一個新的 Mono 實例。

現在讓我們通過在我們的網關服務中調用 /service/resource URL，並查看日誌控制枱來嘗試一下。

DEBUG --- o.s.c.g.h.RoutePredicateHandlerMapping:
  Route matched: service_route
DEBUG --- o.s.c.g.h.RoutePredicateHandlerMapping:
  Mapping [Exchange: GET http://localhost/service/resource]
  to Route{id='service_route', uri=http://localhost:8081, order=0, predicate=Paths: [/service/**],
  match trailing slash: true, gatewayFilters=[[[RewritePath /service(?<segment>/?.*) = '${segment}'], order = 1]]}
INFO  --- c.b.s.c.f.global.LoggingGlobalPreFilter:
  Global Pre Filter executed
DEBUG --- r.netty.http.client.HttpClientConnect:
  [id: 0x58f7e075, L:/127.0.0.1:57215 - R:localhost/127.0.0.1:8081]
  Handler is being applied: {uri=http://localhost:8081/resource, method=GET}
DEBUG --- r.n.http.client.HttpClientOperations:
  [id: 0x58f7e075, L:/127.0.0.1:57215 - R:localhost/127.0.0.1:8081]
  Received response (auto-read:false) : [Content-Type=text/html;charset=UTF-8, Content-Length=16]
INFO  --- c.f.g.LoggingGlobalFiltersConfigurations:
  Global Post Filter executed
DEBUG --- r.n.http.client.HttpClientOperations:
  [id: 0x58f7e075, L:/127.0.0.1:57215 - R:localhost/127.0.0.1:8081] Received last HTTP packet

如我們所見，過濾器在請求轉發到服務之前和之後都有效地執行。

當然，可以將“前”和“後”邏輯合併到一個過濾器中：

@Component
public class FirstPreLastPostGlobalFilter
  implements GlobalFilter, Ordered {

    final Logger logger =
      LoggerFactory.getLogger(FirstPreLastPostGlobalFilter.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange,
      GatewayFilterChain chain) {
        logger.info("First Pre Global Filter");
        return chain.filter(exchange)
          .then(Mono.fromRunnable(() -> {
              logger.info("Last Post Global Filter");
            }));
    }

    @Override
    public int getOrder() {
        return -1;
    }
}

請注意，我們還可以實現Ordered接口，如果需要對過濾器在鏈中的位置進行管理。

@Component
public class LoggingGatewayFilterFactory extends 
  AbstractGatewayFilterFactory<LoggingGatewayFilterFactory.Config> {

    final Logger logger =
      LoggerFactory.getLogger(LoggingGatewayFilterFactory.class);

    public LoggingGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        // ...
    }

    public static class Config {
        // ...
    }
}

public static class Config {
    private String baseMessage;
    private boolean preLogger;
    private boolean postLogger;

    // contructors, getters and setters...
}

@Override
public GatewayFilter apply(Config config) {
    return (exchange, chain) -> {
        // Pre-processing
        if (config.isPreLogger()) {
            logger.info("Pre GatewayFilter logging: "
              + config.getBaseMessage());
        }
        return chain.filter(exchange)
          .then(Mono.fromRunnable(() -> {
              // Post-processing
              if (config.isPostLogger()) {
                  logger.info("Post GatewayFilter logging: "
                    + config.getBaseMessage());
              }
          }));
    };
}

...
filters:
- RewritePath=/service(?<segment>/?.*), $\{segment}
- name: Logging
  args:
    baseMessage: My Custom Message
    preLogger: true
    postLogger: true

filters:
- RewritePath=/service(?<segment>/?.*), $\{segment}
- Logging=My Custom Message, true, true

@Override
public List<String> shortcutFieldOrder() {
    return Arrays.asList("baseMessage",
      "preLogger",
      "postLogger");
}

@Override
public GatewayFilter apply(Config config) {
    return new OrderedGatewayFilter((exchange, chain) -> {
        // ...
    }, 1);
}

@Bean
public RouteLocator routes(
  RouteLocatorBuilder builder,
  LoggingGatewayFilterFactory loggingFactory) {
    return builder.routes()
      .route("service_route_java_config", r -> r.path("/service/**")
        .filters(f -> 
            f.rewritePath("/service(?<segment>/?.*)", "$\\{segment}")
              .filter(loggingFactory.apply(
              new Config("My Custom Message", true, true))))
            .uri("http://localhost:8081"))
      .build();
}

(exchange, chain) -> {
    if (exchange.getRequest()
      .getHeaders()
      .getAcceptLanguage()
      .isEmpty()) {
        // populate the Accept-Language header...
    }

    // remove the query param...
    return chain.filter(exchange);
};

String queryParamLocale = exchange.getRequest()
  .getQueryParams()
  .getFirst("locale");

Locale requestLocale = Optional.ofNullable(queryParamLocale)
  .map(l -> Locale.forLanguageTag(l))
  .orElse(config.getDefaultLocale());

exchange.getRequest()
  .mutate()
  .headers(h -> h.setAcceptLanguageAsLocales(
    Collections.singletonList(requestLocale)))

ServerWebExchange modifiedExchange = exchange.mutate()
  // Here we'll modify the original request:
  .request(originalRequest -> originalRequest)
  .build();

return chain.filter(modifiedExchange);

originalRequest -> originalRequest.uri(
  UriComponentsBuilder.fromUri(exchange.getRequest()
    .getURI())
  .replaceQueryParams(new LinkedMultiValueMap<String, String>())
  .build()
  .toUri())

(exchange, chain) -> {
    return chain.filter(exchange)
      .then(Mono.fromRunnable(() -> {
          ServerHttpResponse response = exchange.getResponse();

          Optional.ofNullable(exchange.getRequest()
            .getQueryParams()
            .getFirst("locale"))
            .ifPresent(qp -> {
                String responseContentLanguage = response.getHeaders()
                  .getContentLanguage()
                  .getLanguage();

                response.getHeaders()
                  .add("Bael-Custom-Language-Header", responseContentLanguage);
                });
        }));
}

(exchange, chain) -> {
    return WebClient.create().get()
      .uri(config.getLanguageEndpoint())
      .exchange()
      // ...
}

// ...
.flatMap(response -> {
    return (response.statusCode()
      .is2xxSuccessful()) ? response.bodyToMono(String.class) : Mono.just(config.getDefaultLanguage());
}).map(LanguageRange::parse)
// ...

.map(range -> {
    exchange.getRequest()
      .mutate()
      .headers(h -> h.setAcceptLanguage(range))
      .build();

    return exchange;
}).flatMap(chain::filter);