SpringCloud/spring-cloud-gateway
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from master to gh-pages

Browse Source
This commit is contained in:
buildmaster
2018-05-02 13:07:27 +00:00
parent a32bb83d00
commit a96f673385
5 changed files with 71 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
multi/multi__building_a_simple_gateway_using_spring_mvc_or_webflux.html Normal file
View File

@@ -0,0 +1,31 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="up" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="prev" href="multi__developer_guide.html" title="9.&nbsp;Developer Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__developer_guide.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;</td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_building_a_simple_gateway_using_spring_mvc_or_webflux" href="#_building_a_simple_gateway_using_spring_mvc_or_webflux"></a>10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux</h1></div></div></div><p>Spring Cloud Gateway provides a utility object called <code class="literal">ProxyExchange</code> which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the <code class="literal">forward()</code> method. To use the <code class="literal">ProxyExchange</code> just include the right module in your classpath (either <code class="literal">spring-cloud-gateway-mvc</code> or <code class="literal">spring-cloud-gateway-webflux</code>).</p><p>MVC example (proxying a request to "/test" downstream to a remote server):</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RestController</span></em>
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GatewaySampleApplication {
<em><span class="hl-annotation" style="color: gray">@Value("${remote.home}")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> URI home;
<em><span class="hl-annotation" style="color: gray">@GetMapping("/test")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity&lt;?&gt; proxy(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/png"</span>).get();
}
}</pre><p>The same thing with Webflux:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RestController</span></em>
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GatewaySampleApplication {
<em><span class="hl-annotation" style="color: gray">@Value("${remote.home}")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> URI home;
<em><span class="hl-annotation" style="color: gray">@GetMapping("/test")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Mono&lt;ResponseEntity&lt;?&gt;&gt; proxy(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/png"</span>).get();
}
}</pre><p>There are convenience methods on the <code class="literal">ProxyExchange</code> to 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:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@GetMapping("/proxy/path/**")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity&lt;?&gt; proxyPath(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
String path = proxy.path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/proxy/path/"</span>);
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/foos/"</span> + path).get();
}</pre><p>All the features of Spring MVC or Webflux are available to Gateway handler methods. So 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 <code class="literal">@RequestMapping</code> in Spring MVC for more details of those features.</p><p>Headers can be added to the downstream response using the <code class="literal">header()</code> methods on <code class="literal">ProxyExchange</code>.</p><p>You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the <code class="literal">get()</code> etc. method. The mapper is a <code class="literal">Function</code> that takes the incoming <code class="literal">ResponseEntity</code> and converts it to an outgoing one.</p><p>First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (<code class="literal">x-forwarded-*</code>).</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__developer_guide.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;</td></tr><tr><td width="40%" align="left" valign="top">9.&nbsp;Developer Guide&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-gateway.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;</td></tr></table></div></body></html>

2
multi/multi__developer_guide.html
View File

@@ -1,3 +1,3 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>9.&nbsp;Developer Guide</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="up" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="prev" href="multi__actuator_api.html" title="8.&nbsp;Actuator API"><link rel="next" href="multi__building_a_simple_gateway_using_spring_mvc.html" title="10.&nbsp;Building a Simple Gateway Using Spring MVC"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">9.&nbsp;Developer Guide</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__actuator_api.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="multi__building_a_simple_gateway_using_spring_mvc.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_developer_guide" href="#_developer_guide"></a>9.&nbsp;Developer Guide</h1></div></div></div><p>TODO: overview of writing custom integrations</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_predicate_factories" href="#_writing_custom_route_predicate_factories"></a>9.1&nbsp;Writing Custom Route Predicate Factories</h2></div></div></div><p>TODO: document writing Custom Route Predicate Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_gatewayfilter_factories" href="#_writing_custom_gatewayfilter_factories"></a>9.2&nbsp;Writing Custom GatewayFilter Factories</h2></div></div></div><p>TODO: document writing Custom GatewayFilter Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_global_filters" href="#_writing_custom_global_filters"></a>9.3&nbsp;Writing Custom Global Filters</h2></div></div></div><p>TODO: document writing Custom Global Filters</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_locators_and_writers" href="#_writing_custom_route_locators_and_writers"></a>9.4&nbsp;Writing Custom Route Locators and Writers</h2></div></div></div><p>TODO: document writing Custom Route Locators and Writers</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__actuator_api.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="multi__building_a_simple_gateway_using_spring_mvc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.&nbsp;Actuator API&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-gateway.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;10.&nbsp;Building a Simple Gateway Using Spring MVC</td></tr></table></div></body></html>
<title>9.&nbsp;Developer Guide</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="up" href="multi_spring-cloud-gateway.html" title="Spring Cloud Gateway"><link rel="prev" href="multi__actuator_api.html" title="8.&nbsp;Actuator API"><link rel="next" href="multi__building_a_simple_gateway_using_spring_mvc_or_webflux.html" title="10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">9.&nbsp;Developer Guide</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__actuator_api.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="multi__building_a_simple_gateway_using_spring_mvc_or_webflux.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_developer_guide" href="#_developer_guide"></a>9.&nbsp;Developer Guide</h1></div></div></div><p>TODO: overview of writing custom integrations</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_predicate_factories" href="#_writing_custom_route_predicate_factories"></a>9.1&nbsp;Writing Custom Route Predicate Factories</h2></div></div></div><p>TODO: document writing Custom Route Predicate Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_gatewayfilter_factories" href="#_writing_custom_gatewayfilter_factories"></a>9.2&nbsp;Writing Custom GatewayFilter Factories</h2></div></div></div><p>TODO: document writing Custom GatewayFilter Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_global_filters" href="#_writing_custom_global_filters"></a>9.3&nbsp;Writing Custom Global Filters</h2></div></div></div><p>TODO: document writing Custom Global Filters</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_locators_and_writers" href="#_writing_custom_route_locators_and_writers"></a>9.4&nbsp;Writing Custom Route Locators and Writers</h2></div></div></div><p>TODO: document writing Custom Route Locators and Writers</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__actuator_api.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="multi__building_a_simple_gateway_using_spring_mvc_or_webflux.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.&nbsp;Actuator API&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-gateway.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux</td></tr></table></div></body></html>

2
multi/multi_spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

22
single/spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

28
spring-cloud-gateway.xml
View File

@@ -894,10 +894,10 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate
<simpara>TODO: document writing Custom Route Locators and Writers</simpara>
</section>
</chapter>
<chapter xml:id="_building_a_simple_gateway_using_spring_mvc">
<title>Building a Simple Gateway Using Spring MVC</title>
<simpara>Spring Cloud Gateway provides a utility object called <literal>ProxyExchange</literal> which you can use inside a regular Spring MVC handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs, or forwarding to a local handler via the <literal>forward()</literal> method.</simpara>
<simpara>Example (proxying a request to "/test" downstream to a remote server):</simpara>
<chapter xml:id="_building_a_simple_gateway_using_spring_mvc_or_webflux">
<title>Building a Simple Gateway Using Spring MVC or Webflux</title>
<simpara>Spring Cloud Gateway provides a utility object called <literal>ProxyExchange</literal> which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the <literal>forward()</literal> method. To use the <literal>ProxyExchange</literal> just include the right module in your classpath (either <literal>spring-cloud-gateway-mvc</literal> or <literal>spring-cloud-gateway-webflux</literal>).</simpara>
<simpara>MVC example (proxying a request to "/test" downstream to a remote server):</simpara>
<programlisting language="java" linenumbering="unnumbered">@RestController
@SpringBootApplication
public class GatewaySampleApplication {
@@ -906,18 +906,32 @@ public class GatewaySampleApplication {
private URI home;
@GetMapping("/test")
public ResponseEntity&lt;?&gt; proxy(ProxyExchange&lt;Object&gt; proxy) throws Exception {
public ResponseEntity&lt;?&gt; proxy(ProxyExchange&lt;byte[]&gt; proxy) throws Exception {
return proxy.uri(home.toString() + "/image/png").get();
}
}</programlisting>
<simpara>The same thing with Webflux:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RestController
@SpringBootApplication
public class GatewaySampleApplication {
@Value("${remote.home}")
private URI home;
@GetMapping("/test")
public Mono&lt;ResponseEntity&lt;?&gt;&gt; proxy(ProxyExchange&lt;byte[]&gt; proxy) throws Exception {
return proxy.uri(home.toString() + "/image/png").get();
}
}</programlisting>
<simpara>There are convenience methods on the <literal>ProxyExchange</literal> to 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:</simpara>
<programlisting language="java" linenumbering="unnumbered">@GetMapping("/proxy/path/**")
public ResponseEntity&lt;?&gt; proxyPath(ProxyExchange&lt;?&gt; proxy) throws Exception {
public ResponseEntity&lt;?&gt; proxyPath(ProxyExchange&lt;byte[]&gt; proxy) throws Exception {
String path = proxy.path("/proxy/path/");
return proxy.uri(home.toString() + "/foos/" + path).get();
}</programlisting>
<simpara>All the features of Spring MVC are available to Gateway handler methods. So 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 <literal>@RequestMapping</literal> in Spring MVC for more details of those features.</simpara>
<simpara>All the features of Spring MVC or Webflux are available to Gateway handler methods. So 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 <literal>@RequestMapping</literal> in Spring MVC for more details of those features.</simpara>
<simpara>Headers can be added to the downstream response using the <literal>header()</literal> methods on <literal>ProxyExchange</literal>.</simpara>
<simpara>You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the <literal>get()</literal> etc. method. The mapper is a <literal>Function</literal> that takes the incoming <literal>ResponseEntity</literal> and converts it to an outgoing one.</simpara>
<simpara>First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (<literal>x-forwarded-*</literal>).</simpara>