037abaeb26
* New naming convention using webflux and webmvc
The new suffixes are gateway-server-web{flux|mvc} and gateway-proxyexchange-web{flux|mvc}.
This commit updates the starters to use gateway-server-web{flux|mvc} suffixes.
* Adds new spring-cloud-gateway-server-web{flux|mvc} modules.
These simply depend on the old ones. A warning is logged if not using the new module.
* Adds s-c-g-proxyexchange-{webflux|webmvc} modules
* Updates docs for s-c-g-{proxyexchange|server}-{webflux|webmvc} modules
81 lines
3.8 KiB
Plaintext
81 lines
3.8 KiB
Plaintext
[[proxy-exchange-gateway]]
|
|
= Proxy Exchange Gateway with Spring Web MVC or WebFlux
|
|
|
|
WARNING: The following describes an alternative style gateway. None of the Spring Cloud Gateway Server documentation applies to what follows.
|
|
|
|
== How to Include Spring Cloud Gateway Proxy Exchange
|
|
|
|
To include Spring Cloud Gateway Proxy Exchange in your project, use the artifact with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-gateway-proxyexchange-webmvc` for the MVC Proxy Exchange. For the WebFlux Proxy Exchange use artifact with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-gateway-proxyexchange-webflux`.
|
|
|
|
See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
|
|
|
|
== Using Proxy Exchange
|
|
|
|
Spring Cloud Gateway provides a utility object called `ProxyExchange`.
|
|
You can use it inside a regular Spring web handler as a method parameter.
|
|
It supports basic downstream HTTP exchanges through methods that mirror the HTTP verbs.
|
|
With MVC, it also supports forwarding to a local handler through the `forward()` method.
|
|
To use the `ProxyExchange`, include the right module in your classpath (either `spring-cloud-gateway-proxyexchange-webmvc` or `spring-cloud-gateway-proxyexchange-webflux`).
|
|
|
|
The following MVC example proxies a request to `/test` downstream to a remote server:
|
|
|
|
[source,java]
|
|
----
|
|
@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();
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
The following example does the same thing with Webflux:
|
|
|
|
[source,java]
|
|
----
|
|
@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();
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
Convenience methods on the `ProxyExchange` enable the handler method to discover and enhance the URI path of the incoming request.
|
|
For example, you might want to extract the trailing elements of a path to pass them downstream:
|
|
|
|
[source,java]
|
|
----
|
|
@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();
|
|
}
|
|
----
|
|
|
|
All the features of Spring MVC and Webflux are available to gateway handler methods.
|
|
As a result, you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation.
|
|
See the documentation for `@RequestMapping` in Spring MVC for more details of those features.
|
|
|
|
You can add headers to the downstream response by using the `header()` methods on `ProxyExchange`.
|
|
|
|
You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` method (and other methods).
|
|
The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one.
|
|
|
|
First-class support is provided for "`sensitive`" headers (by default, `cookie` and `authorization`) and "`skipped`" headers (by default, `content-length` and `host`), which are not passed downstream, and for "`proxy`" (`x-forwarded-*`) headers. The idea behind "`skipped`" headers is that they may result in problems when copied over to the downstream request. For example: because of the way that the `ProxyExchange` calls the downstream endpoint the content's length might have changed or even use a `Transfer-Encoding: chunked` instead of a `Content-Length` header.
|
|
|