16. Troubleshooting

本部分介绍使用Spring Cloud Gateway时可能出现的常见问题.

16.1. Log Levels

下面的 loggers 可能在DEBUG and TRACE级别包含有价值的故障排除信息:

• org.springframework.cloud.gateway
• org.springframework.http.server.reactive
• org.springframework.web.reactive
• org.springframework.boot.autoconfigure.web
• reactor.netty
• redisratelimiter

16.2. Wiretap

Reactor Netty HttpClient and HttpServer可以启用监听. 与与 reactor.netty 日志级别设置为DEBUG or TRACE结合使用时, 它将启用信息记录, 例如通过网络发送/接收 的 headers 和 bodies . 要启用监听, 请分别为HttpServer 和HttpClient设置 spring.cloud.gateway.httpserver.wiretap=true 或spring.cloud.gateway.httpclient.wiretap=true.

17. Developer Guide

这些是编写网关的某些自定义组件的基本指南.

17.1. Writing Custom Route Predicate Factories

如果想要编写一个Route Predicate，需要实现RoutePredicateFactory借口。 或者继承AbstractRoutePredicateFactory的抽象类。

MyRoutePredicateFactory.java

public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory<HeaderRoutePredicateFactory.Config> {

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

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        // grab configuration from Config object
        return exchange -> {
            //grab the request
            ServerHttpRequest request = exchange.getRequest();
            //take information from the request to see if it
            //matches configuration.
            return matches(config, request);
        };
    }

    public static class Config {
        //Put the configuration properties for your filter here
    }

}

17.2. Writing Custom GatewayFilter Factories

若要自定义 GatewayFilter, 你必须实现 GatewayFilterFactory接口. 或者继承 AbstractGatewayFilterFactory抽象类. 如下所示:

Example 73. PreGatewayFilterFactory.java

public class PreGatewayFilterFactory extends AbstractGatewayFilterFactory<PreGatewayFilterFactory.Config> {

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

    @Override
    public GatewayFilter apply(Config config) {
        // grab configuration from Config object
        return (exchange, chain) -> {
            //If you want to build a "pre" filter you need to manipulate the
            //request before calling chain.filter
            ServerHttpRequest.Builder builder = exchange.getRequest().mutate();
            //use builder to manipulate the request
            return chain.filter(exchange.mutate().request(request).build());
        };
    }

    public static class Config {
        //Put the configuration properties for your filter here
    }

}

PostGatewayFilterFactory.java

public class PostGatewayFilterFactory extends AbstractGatewayFilterFactory<PostGatewayFilterFactory.Config> {

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

    @Override
    public GatewayFilter apply(Config config) {
        // grab configuration from Config object
        return (exchange, chain) -> {
            return chain.filter(exchange).then(Mono.fromRunnable(() -> {
                ServerHttpResponse response = exchange.getResponse();
                //Manipulate the response in some way
            }));
        };
    }

    public static class Config {
        //Put the configuration properties for your filter here
    }

}

17.3. Writing Custom Global Filters

若要自定义 global filter, 你必须实现 GlobalFilter 接口. 这会将filter应用于所有请求.

以下示例说明如何分别设置全局前置和后置过滤器:

@Bean
public GlobalFilter customGlobalFilter() {
    return (exchange, chain) -> exchange.getPrincipal()
        .map(Principal::getName)
        .defaultIfEmpty("Default User")
        .map(userName -> {
          //adds header to proxied request
          exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build();
          return exchange;
        })
        .flatMap(chain::filter);
}

@Bean
public GlobalFilter customGlobalPostFilter() {
    return (exchange, chain) -> chain.filter(exchange)
        .then(Mono.just(exchange))
        .map(serverWebExchange -> {
          //adds header to response
          serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER",
              HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work");
          return serverWebExchange;
        })
        .then();
}

18. Building a Simple Gateway by Using Spring MVC or Webflux

以下描述了替代样式的网关. 先前的文档均不适用于以下内容.

Spring Cloud Gateway 提供了一个名为ProxyExchange的实用程序对象. 你可以在常规的 Spring web handler 中使用它作为方法参数. 它通过镜像HTTP动词的方法支持基本的下游HTTP交换. 使用MVC, 它还支持通过forward()方法转发到本地处理程序. 要使用 ProxyExchange, 请在类路径中包含正确的模块 ( spring-cloud-gateway-mvc 或 spring-cloud-gateway-webflux).

以下MVC示例代理了对/test到远程服务器下游的请求:

@RestController
@SpringBootApplication
public class GatewaySampleApplication {

    @Value("${remote.home}")
    private URI home;

    @GetMapping("/test")
    public ResponseEntity<?> proxy(ProxyExchange<byte[]> proxy) throws Exception {
        return proxy.uri(home.toString() + "/image/png").get();
    }

}

以下示例使用Webflux执行相同的操作:

@RestController
@SpringBootApplication
public class GatewaySampleApplication {

    @Value("${remote.home}")
    private URI home;

    @GetMapping("/test")
    public Mono<ResponseEntity<?>> proxy(ProxyExchange<byte[]> proxy) throws Exception {
        return proxy.uri(home.toString() + "/image/png").get();
    }

}

ProxyExchange 上的便捷方法使处理程序方法能够发现并增强传入请求的URI路径. 例如, 你可能希望提取路径的尾部元素以将它们传递到下游:

@GetMapping("/proxy/path/**")
public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception {
  String path = proxy.path("/proxy/path/");
  return proxy.uri(home.toString() + "/foos/" + path).get();
}

网关处理程序方法可以使用Spring MVC和Webflux的所有功能. 所以, 你可以注入request headers和query parameters, 例如, 你可以使用mapping annotation中的声明来约束传入的请求. 请参见Spring MVC中的@RequestMapping in Spring MVC 文档.

你可以使用ProxyExchange的header()方法将 headers 添加到下游响应中.

你还可以通过将mapper 添加到get()方法（和其他方法）来操作 response headers (以及response中的其他元素) . The mapper 是一种Function类型，它接收传入的 ResponseEntity 并将其转换为传出的.

对不传递到下游的 “sensitive” headers (默认情况下为, cookie 和authorization) 以及 “proxy” (x-forwarded-*) headers提供良好的支持.

19. Configuration properties

可以在application.properties , application.yml 文件内或作为命令行开关指定各种属性. 本附录提供了常见的 Spring Cloud Gateway 属性列表以及对使用它们的基础类的引用.

属性可以来自类路径上的其他jar文件，因此这不是全部的属性列表。 另外，你也可以定义自己的属性。