| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Apache Dubbo – User Documentation</title><link>https://dubbo.apache.org/en/docs/v2.7/user/</link><description>Recent content in User Documentation on Apache Dubbo</description><generator>Hugo -- gohugo.io</generator><language>en</language><atom:link href="https://dubbo.apache.org/en/docs/v2.7/user/index.xml" rel="self" type="application/rss+xml"/><item><title>Docs: Preface</title><link>https://dubbo.apache.org/en/docs/v2.7/user/preface/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/preface/</guid><description/></item><item><title>Docs: Quick start</title><link>https://dubbo.apache.org/en/docs/v2.7/user/quick-start/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/quick-start/</guid><description> |
| <p>The most common way to use Dubbo is to run it in Spring framework. The following content will guide you to develop a Dubbo application with Spring framework&rsquo;s <a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/xsd-configuration.html">XML configuration</a>.</p> |
| <p>If you don&rsquo;t want to rely on Spring, you can try using <a href="../configuration/api">API configuration</a>.</p> |
| <p>First let&rsquo;s create a root directory called dubbo-demo:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>mkdir dubbo-demo |
| </span></span><span style="display:flex;"><span><span style="color:#b58900">cd</span> dubbo-demo |
| </span></span></code></pre></div><p>Next, we are going to create 3 sub-directories under root directory:</p> |
| <ul> |
| <li>dubbo-demo-api: the common service api</li> |
| <li>dubbo-demo-provider: the demo provider codes</li> |
| <li>dubbo-demo-consumer: the demo consumer codes</li> |
| </ul> |
| <h2 id="service-provider">Service provider</h2> |
| <h3 id="defining-service-interfaces">Defining service interfaces</h3> |
| <p>DemoService.java <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> org.apache.dubbo.demo; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">DemoService</span> { |
| </span></span><span style="display:flex;"><span> String <span style="color:#268bd2">sayHello</span>(String name); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>The project structure should look like this:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>. |
| </span></span><span style="display:flex;"><span>├── dubbo-demo-api |
| </span></span><span style="display:flex;"><span>│ ├── pom.xml |
| </span></span><span style="display:flex;"><span>│ └── src |
| </span></span><span style="display:flex;"><span>│ └── main |
| </span></span><span style="display:flex;"><span>│ └── java |
| </span></span><span style="display:flex;"><span>│ └── org |
| </span></span><span style="display:flex;"><span>│ └── apache |
| </span></span><span style="display:flex;"><span>│ └── dubbo |
| </span></span><span style="display:flex;"><span>│ └── demo |
| </span></span><span style="display:flex;"><span>│ └── DemoService.java |
| </span></span></code></pre></div><h3 id="implement-interface-in-service-provider">Implement interface in service provider</h3> |
| <p>DemoServiceImpl.java <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> org.apache.dubbo.demo.provider; |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.demo.DemoService; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">DemoServiceImpl</span> <span style="color:#268bd2">implements</span> DemoService { |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> String <span style="color:#268bd2">sayHello</span>(String name) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> <span style="color:#2aa198">&#34;Hello &#34;</span> <span style="color:#719e07">+</span> name; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="exposing-service-with-spring-configuration">Exposing service with Spring configuration</h3> |
| <p>provider.xml：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;beans</span> xmlns:xsi=<span style="color:#2aa198">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> |
| </span></span><span style="display:flex;"><span> xmlns:dubbo=<span style="color:#2aa198">&#34;http://dubbo.apache.org/schema/dubbo&#34;</span> |
| </span></span><span style="display:flex;"><span> xmlns=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans&#34;</span> |
| </span></span><span style="display:flex;"><span> xsi:schemaLocation=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd |
| </span></span></span><span style="display:flex;"><span><span style="color:#2aa198"> http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- provider&#39;s application name, used for tracing dependency relationship --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;demo-provider&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- use multicast registry center to export service --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:registry</span> address=<span style="color:#2aa198">&#34;multicast://224.5.6.7:1234&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- use dubbo protocol to export service on port 20880 --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20880&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- service implementation, as same as regular local bean --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;demoService&#34;</span> class=<span style="color:#2aa198">&#34;org.apache.dubbo.demo.provider.DemoServiceImpl&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- declare the service interface to be exported --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.demo.DemoService&#34;</span> ref=<span style="color:#2aa198">&#34;demoService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/beans&gt;</span> |
| </span></span></code></pre></div><p>The demo uses multicast as the registry since it is simple and does not require to extra installation. |
| If you prefer a registry like zookeeper, please check out examples <a href="https://github.com/dubbo/dubbo-samples">here</a>.</p> |
| <h3 id="configure-the-logging-system">Configure the logging system</h3> |
| <p>Dubbo use log4j as logging system by default, it also support slf4j, Apache Commons Logging, and JUL logging.</p> |
| <p>Following is a sample configuration:</p> |
| <p>log4j.properties</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-properties" data-lang="properties"><span style="display:flex;"><span><span style="color:#586e75">###set log levels###</span> |
| </span></span><span style="display:flex;"><span>log4j.rootLogger<span style="color:#719e07">=</span><span style="color:#2aa198">info, stdout</span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">###output to the console###</span> |
| </span></span><span style="display:flex;"><span>log4j.appender.stdout<span style="color:#719e07">=</span><span style="color:#2aa198">org.apache.log4j.ConsoleAppender</span> |
| </span></span><span style="display:flex;"><span>log4j.appender.stdout.Target<span style="color:#719e07">=</span><span style="color:#2aa198">System.out</span> |
| </span></span><span style="display:flex;"><span>log4j.appender.stdout.layout<span style="color:#719e07">=</span><span style="color:#2aa198">org.apache.log4j.PatternLayout</span> |
| </span></span><span style="display:flex;"><span>log4j.appender.stdout.layout.ConversionPattern<span style="color:#719e07">=</span><span style="color:#2aa198">[%d{dd/MM/yy hh:mm:ss:sss z}] %t %5p %c{2}: %m%n</span> |
| </span></span></code></pre></div><h3 id="bootstrap-the-service-provider">Bootstrap the service provider</h3> |
| <p>Provider.java</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> org.apache.dubbo.demo.provider; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.springframework.context.support.ClassPathXmlApplicationContext; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">Provider</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">static</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">main</span>(String<span style="color:#719e07">[]</span> args) <span style="color:#268bd2">throws</span> Exception { |
| </span></span><span style="display:flex;"><span> System.setProperty(<span style="color:#2aa198">&#34;java.net.preferIPv4Stack&#34;</span>, <span style="color:#2aa198">&#34;true&#34;</span>); |
| </span></span><span style="display:flex;"><span> ClassPathXmlApplicationContext context <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ClassPathXmlApplicationContext(<span style="color:#719e07">new</span> String<span style="color:#719e07">[]</span>{<span style="color:#2aa198">&#34;META-INF/spring/dubbo-demo-provider.xml&#34;</span>}); |
| </span></span><span style="display:flex;"><span> context.start(); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Provider started.&#34;</span>); |
| </span></span><span style="display:flex;"><span> System.in.read(); <span style="color:#586e75">// press any key to exit</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Finally, the project structure should look like this:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>├── dubbo-demo-provider |
| </span></span><span style="display:flex;"><span>│ ├── pom.xml |
| </span></span><span style="display:flex;"><span>│ └── src |
| </span></span><span style="display:flex;"><span>│ └── main |
| </span></span><span style="display:flex;"><span>│ ├── java |
| </span></span><span style="display:flex;"><span>│ │ └── org |
| </span></span><span style="display:flex;"><span>│ │ └── apache |
| </span></span><span style="display:flex;"><span>│ │ └── dubbo |
| </span></span><span style="display:flex;"><span>│ │ └── demo |
| </span></span><span style="display:flex;"><span>│ │ └── provider |
| </span></span><span style="display:flex;"><span>│ │ ├── DemoServiceImpl.java |
| </span></span><span style="display:flex;"><span>│ │ └── Provider.java |
| </span></span><span style="display:flex;"><span>│ └── resources |
| </span></span><span style="display:flex;"><span>│ ├── META-INF |
| </span></span><span style="display:flex;"><span>│ │ └── spring |
| </span></span><span style="display:flex;"><span>│ │ └── dubbo-demo-provider.xml |
| </span></span><span style="display:flex;"><span>│ └── log4j.properties |
| </span></span></code></pre></div><h2 id="service-consumer">Service consumer</h2> |
| <p>Complete installation steps, see：<a href="../../admin/install/consumer-demo">Consumer demo installation</a></p> |
| <h3 id="using-the-spring-configuration-to-reference-a-remote-service">Using the Spring configuration to reference a remote service</h3> |
| <p>consumer.xml：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#719e07">&lt;?xml version=&#34;1.0&#34; encoding=&#34;UTF-8&#34;?&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;beans</span> xmlns:xsi=<span style="color:#2aa198">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> |
| </span></span><span style="display:flex;"><span> xmlns:dubbo=<span style="color:#2aa198">&#34;http://dubbo.apache.org/schema/dubbo&#34;</span> |
| </span></span><span style="display:flex;"><span> xmlns=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans&#34;</span> |
| </span></span><span style="display:flex;"><span> xsi:schemaLocation=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd |
| </span></span></span><span style="display:flex;"><span><span style="color:#2aa198"> http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- consumer&#39;s application name, used for tracing dependency relationship (not a matching criterion), |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"> don&#39;t set it same as provider --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;demo-consumer&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- use multicast registry center to discover service --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:registry</span> address=<span style="color:#2aa198">&#34;multicast://224.5.6.7:1234&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">&lt;!-- generate proxy for the remote service, then demoService can be used in the same way as the |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"> local regular interface --&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;demoService&#34;</span> check=<span style="color:#2aa198">&#34;false&#34;</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.demo.DemoService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/beans&gt;</span> |
| </span></span></code></pre></div><h3 id="bootstrap-the-consumer">Bootstrap the consumer</h3> |
| <p>Consumer.java <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">import</span> org.springframework.context.support.ClassPathXmlApplicationContext; |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.demo.DemoService; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">Consumer</span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">static</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">main</span>(String<span style="color:#719e07">[]</span> args) <span style="color:#268bd2">throws</span> Exception { |
| </span></span><span style="display:flex;"><span> ClassPathXmlApplicationContext context <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ClassPathXmlApplicationContext(<span style="color:#719e07">new</span> String<span style="color:#719e07">[]</span> {<span style="color:#2aa198">&#34;META-INF/spring/dubbo-demo-consumer.xml&#34;</span>}); |
| </span></span><span style="display:flex;"><span> context.start(); |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// Obtaining a remote service proxy</span> |
| </span></span><span style="display:flex;"><span> DemoService demoService <span style="color:#719e07">=</span> (DemoService)context.getBean(<span style="color:#2aa198">&#34;demoService&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// Executing remote methods</span> |
| </span></span><span style="display:flex;"><span> String hello <span style="color:#719e07">=</span> demoService.sayHello(<span style="color:#2aa198">&#34;world&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// Display the call result</span> |
| </span></span><span style="display:flex;"><span> System.out.println(hello); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="config-the-logging-system">Config the logging system</h3> |
| <p>This is the same as how to config it on provider side.</p> |
| <p>Finally, the project structure should be look like this:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>├── dubbo-demo-consumer |
| </span></span><span style="display:flex;"><span>│ ├── pom.xml |
| </span></span><span style="display:flex;"><span>│ └── src |
| </span></span><span style="display:flex;"><span>│ └── main |
| </span></span><span style="display:flex;"><span>│ ├── java |
| </span></span><span style="display:flex;"><span>│ │ └── org |
| </span></span><span style="display:flex;"><span>│ │ └── apache |
| </span></span><span style="display:flex;"><span>│ │ └── dubbo |
| </span></span><span style="display:flex;"><span>│ │ └── demo |
| </span></span><span style="display:flex;"><span>│ │ └── consumer |
| </span></span><span style="display:flex;"><span>│ │ └── Consumer.java |
| </span></span><span style="display:flex;"><span>│ └── resources |
| </span></span><span style="display:flex;"><span>│ ├── META-INF |
| </span></span><span style="display:flex;"><span>│ │ └── spring |
| </span></span><span style="display:flex;"><span>│ │ └── dubbo-demo-consumer.xml |
| </span></span><span style="display:flex;"><span>│ └── log4j.properties |
| </span></span></code></pre></div><h2 id="start-the-demo">Start the demo</h2> |
| <h3 id="start-service-provider">Start service provider</h3> |
| <p>Run the <code>org.apache.dubbo.demo.provider.Provider</code> class to start the provider.</p> |
| <h3 id="start-service-consumer">Start service consumer</h3> |
| <p>Run the <code>org.apache.dubbo.demo.provider.Consumer</code> class to start the consumer, and you should be able to see the following result:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>Hello world |
| </span></span></code></pre></div><h2 id="complete-example">Complete example</h2> |
| <p>You can find the complete example code in the Github repository.</p> |
| <ul> |
| <li><a href="../../admin/install/provider-demo">Provider demo</a></li> |
| <li><a href="../../admin/install/consumer-demo">Consumer demo</a></li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>The interface needs to be packaged separately, shared by the service provider and the consumer&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>Hidden realization for service consumer&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>IoC injection can also be used&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Dependencies</title><link>https://dubbo.apache.org/en/docs/v2.7/user/dependencies/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/dependencies/</guid><description> |
| <h2 id="necessary-dependencies">Necessary dependencies</h2> |
| <p>JDK 1.6+ <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup></p> |
| <h2 id="default-dependencies">Default dependencies</h2> |
| <p>use <code>mvn dependency:tree &gt; dep.log</code> command to analysis，Dubbo default depends on the following 3rd party libraries：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#719e07">[</span>INFO<span style="color:#719e07">]</span> +- com.alibaba:dubbo:jar:2.5.9-SNAPSHOT:compile |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">[</span>INFO<span style="color:#719e07">]</span> | +- org.springframework:spring-context:jar:4.3.10.RELEASE:compile |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">[</span>INFO<span style="color:#719e07">]</span> | +- org.javassist:javassist:jar:3.21.0-GA:compile |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">[</span>INFO<span style="color:#719e07">]</span> | <span style="color:#cb4b16">\-</span> org.jboss.netty:netty:jar:3.2.5.Final:compile |
| </span></span></code></pre></div><p>All dependencies here are selected for the default configuration of the Dubbo, which are based on stability and performance considerations.</p> |
| <ul> |
| <li>javassist.jar <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>: if <code>&lt;dubbo:provider proxy=&quot;jdk&quot; /&gt;</code> or <code>&lt;dubbo:consumer proxy=&quot;jdk&quot; /&gt;</code>，or <code>&lt;dubbo:application compiler=&quot;jdk&quot; /&gt;</code>， is not required.</li> |
| <li>spring-context.jar <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>: If you are using <code>ServiceConfig</code> and <code>ReferenceConfig</code> API calls, is not required.</li> |
| <li>netty.jar <sup id="fnref:4"><a href="#fn:4" class="footnote-ref" role="doc-noteref">4</a></sup>: if <code>&lt;dubbo:protocol server=&quot;mina&quot;/&gt;</code> or <code>&lt;dubbo:protocol server=&quot;grizzly&quot;/&gt;</code>，Then change to mina.jar or grizzly.jar. If <code>&lt;protocol name=&quot;rmi&quot;/&gt;</code>， is not required.</li> |
| </ul> |
| <h2 id="optional-dependencies">Optional dependencies</h2> |
| <p>These dependencies needs to be added to project manually，when you need them.</p> |
| <ul> |
| <li>netty-all 4.0.35.Final</li> |
| <li>mina: 1.1.7</li> |
| <li>grizzly: 2.1.4</li> |
| <li>httpclient: 4.5.3</li> |
| <li>hessian_lite: 3.2.1-fixed</li> |
| <li>fastjson: 1.2.31</li> |
| <li>zookeeper: 3.4.9</li> |
| <li>jedis: 2.9.0</li> |
| <li>xmemcached: 1.3.6</li> |
| <li>hessian: 4.0.38</li> |
| <li>jetty: 6.1.26</li> |
| <li>hibernate-validator: 5.4.1.Final</li> |
| <li>zkclient: 0.2</li> |
| <li>curator: 2.12.0</li> |
| <li>cxf: 3.0.14</li> |
| <li>thrift: 0.8.0</li> |
| <li>servlet: 3.0 <sup id="fnref:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup></li> |
| <li>validation-api: 1.1.0.GA <sup id="fnref1:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup></li> |
| <li>jcache: 1.0.0 <sup id="fnref2:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup></li> |
| <li>javax.el: 3.0.1-b08 <sup id="fnref3:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup></li> |
| <li>kryo: 4.0.1</li> |
| <li>kryo-serializers: 0.42</li> |
| <li>fst: 2.48-jdk-6</li> |
| <li>resteasy: 3.0.19.Final</li> |
| <li>tomcat-embed-core: 8.0.11</li> |
| <li>slf4j: 1.7.25</li> |
| <li>log4j: 1.2.16</li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>In theory, Dubbo only depend on JDK, not depend on any 3rd party libs, you can finish logic by using JDK.&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>Bytecode generation&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>Configuration parsing&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:4"> |
| <p>Network transmission&#160;<a href="#fnref:4" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:5"> |
| <p>JAVAEE&#160;<a href="#fnref:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a>&#160;<a href="#fnref1:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a>&#160;<a href="#fnref2:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a>&#160;<a href="#fnref3:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Maturity</title><link>https://dubbo.apache.org/en/docs/v2.7/user/maturity/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/maturity/</guid><description> |
| <h2 id="function-maturity">Function maturity</h2> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Concurrency control</td> |
| <td>Tested</td> |
| <td>concurrency control</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Connection control</td> |
| <td>Tested</td> |
| <td>connection number control</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Connecting certain provider straightly</td> |
| <td>Tested</td> |
| <td>Provider service for point-to-point connecting straightly, for test</td> |
| <td></td> |
| <td>Can be used in the test environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Grouping polymerization</td> |
| <td>Tested</td> |
| <td>Return value of grouping polymerization, service for menu aggregation and other services</td> |
| <td>Used in special scenes</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Parameters validator</td> |
| <td>Tested</td> |
| <td>parameters validator, JSR303 validation framework integration</td> |
| <td>Have effect on Performance</td> |
| <td>On trial</td> |
| <td>LaiWang</td> |
| </tr> |
| <tr> |
| <td>Result cache</td> |
| <td>Tested</td> |
| <td>result cache, for accelerating requests</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Generic reference</td> |
| <td>Stable</td> |
| <td>Generic reference, remote call without a business interface class，for test platforms, open api proxy service, and so on</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Generic service</td> |
| <td>Stable</td> |
| <td>Generic service, no interface class is required to implement any interface, for mock platform</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Echo test</td> |
| <td>Tested</td> |
| <td>echo test</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Attachment</td> |
| <td>Stable</td> |
| <td>Attachment</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Asynchronous call</td> |
| <td>Tested</td> |
| <td>Unavailable asynchronous call</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Local call</td> |
| <td>Tested</td> |
| <td>Local call</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Callback parameter</td> |
| <td>Tested</td> |
| <td>Callback parameter</td> |
| <td>Used in special scenes</td> |
| <td>On trial</td> |
| <td>Registry</td> |
| </tr> |
| <tr> |
| <td>Events notify</td> |
| <td>Tested</td> |
| <td>Events notify, triggering before and after the remote call is executed</td> |
| <td></td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Local stub</td> |
| <td>Stable</td> |
| <td>Performing part of the logic on the client side</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Local mock</td> |
| <td>Stable</td> |
| <td>Forged return results, which can be executed when failed or directly executed, for service degradation</td> |
| <td>Need support of registry</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Delay publish</td> |
| <td>Stable</td> |
| <td>Delay publish, used to wait for the application to load warmup data or wait for spring context to load completely</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Lazy connect</td> |
| <td>Tested</td> |
| <td>Delay setting up connections, when invocation is set up</td> |
| <td></td> |
| <td>On trial</td> |
| <td>Registry</td> |
| </tr> |
| <tr> |
| <td>Stickness connections</td> |
| <td>Tested</td> |
| <td>Stickness connections, always make a request to the same provider service unless the service is down, and then switch to another</td> |
| <td></td> |
| <td>On trial</td> |
| <td>Registry</td> |
| </tr> |
| <tr> |
| <td>Token authorization</td> |
| <td>Tested</td> |
| <td>Token authorization, is used for service authorization</td> |
| <td>Need support of registry</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Routing rule</td> |
| <td>Tested</td> |
| <td>Dynamically determining the call relationship</td> |
| <td>Need support of registry</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Configuration rule</td> |
| <td>Tested</td> |
| <td>Distribute the configuration dynamically, is the switch of business logic</td> |
| <td>Need support of registry</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Accesslog</td> |
| <td>Tested</td> |
| <td>Accesslog, used to record call information</td> |
| <td>Local storage, impact performance, limited by disk size</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Distributed transaction</td> |
| <td>Research</td> |
| <td>JTA/XA three phase submission transaction(TCC)</td> |
| <td>Unstable</td> |
| <td>Unavailable</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <h2 id="strategy-maturity">Strategy maturity</h2> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Zookeeper registry</td> |
| <td>Stable</td> |
| <td>Support the cluster, have various of related open source products, dubbo-2.3.3 and above versions are recommended</td> |
| <td>Depended on the stability of zookeeper</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Redis registry</td> |
| <td>Stable</td> |
| <td>Support the client - based double - write clustering method with high performance</td> |
| <td>Please ensure server time synchronization, be used to check the expired dirty data of heartbeat</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Multicast registry</td> |
| <td>Tested</td> |
| <td>Decentration, no registry needs to be installed</td> |
| <td>Depending on the network topology and routing, there is a risk across the server rooms</td> |
| <td>Can be used in a small range, in development/test environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Simple registry</td> |
| <td>Tested</td> |
| <td>Dogfooding, the registry itself is also a standard RPC service</td> |
| <td>No cluster support, may occur single-point failure</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Simple monitor system</td> |
| <td>Stable</td> |
| <td>Support JFreeChart statistics report</td> |
| <td>No cluster support, may occur single-point failure, but the failure does not affect the RPC call</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Dubbo protocol</td> |
| <td>Stable</td> |
| <td>Use NIO to reuse a single long connection and use a thread pool to process requests concurrently, Reduce handshake and increase concurrency efficiency, good performance</td> |
| <td>A single connection will become a bottleneck in the transmission of large files</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Rmi protocol</td> |
| <td>Stable</td> |
| <td>Interoperable with native RMI, based on the TCP protocol</td> |
| <td>Occasionally the connection fails, and the stub needs to be rebuilt</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Hessian protocol</td> |
| <td>Stable</td> |
| <td>Interoperable with native Hessian, based on the HTTP protocol</td> |
| <td>Hessian.jar support is required, and the overhead of HTTP short connections is large</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Netty Transporter</td> |
| <td>Stable</td> |
| <td>The NIO framework of JBoss, has good performance</td> |
| <td>A request sends two events and needs to shield useless events</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Mina Transporter</td> |
| <td>Stable</td> |
| <td>Classic NIO framework，stable</td> |
| <td>The dispatch of the message queue is not timely, under great pressure, there will be FullGC</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Grizzly Transporter</td> |
| <td>Tested</td> |
| <td>The NIO framework of Sun, applied in the GlassFish container</td> |
| <td>The thread pool is not extensible, and Filter can&rsquo;t intercept the next filter</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Hessian Serialization</td> |
| <td>Stable</td> |
| <td>Good performance, multilingual support (recommended)</td> |
| <td>The compatibility of various versions of Hessian is not good, it may be in conflict with the Hessian used in the application, and the Dubbo is embedded with the source code of the hessian3.2.1</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Dubbo Serialization</td> |
| <td>Tested</td> |
| <td>The performance is better in a large number of POJO transmission by not transmitting the class information of POJO.</td> |
| <td>When a field is added to the parameter object, an external file declaration is required</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Json Serialization</td> |
| <td>Tested</td> |
| <td>pure text, can be cross-language parsed, default using FastJson</td> |
| <td>Poor performance</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Java Serialization</td> |
| <td>Stable</td> |
| <td>Java native support</td> |
| <td>Poor performance</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Javassist ProxyFactory</td> |
| <td>Stable</td> |
| <td>Bytecode generation instead of reflection, good performance(recommended)</td> |
| <td>Depending on the javassist.jar and taking up the JVM&rsquo;s Perm memory, the Perm may have to be larger:java -XX:PermSize=128m</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Jdk ProxyFactory</td> |
| <td>Stable</td> |
| <td>JDK native support</td> |
| <td>Poor performance</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Failover Cluster</td> |
| <td>Stable</td> |
| <td>Failure automatically switches, when failure occurs, retries other servers, usually used for read operations.(recommended)</td> |
| <td>Retry will lead to longer delays</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Failfast Cluster</td> |
| <td>Stable</td> |
| <td>Fast failure, only one call, failure to be reported immediately, usually used for non idempotent writing.</td> |
| <td>If a server is being restarted, a call failure may occur</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Failsafe Cluster</td> |
| <td>Stable</td> |
| <td>Failsafe, when abnormal, directly ignored, usually used to write to the audit log and other operations</td> |
| <td>Call information loss</td> |
| <td>Can be used in the production environment</td> |
| <td>Monitor</td> |
| </tr> |
| <tr> |
| <td>Failback Cluster</td> |
| <td>Tested</td> |
| <td>Failure auto recovery, backstage record failure request, regular retransmission, usually used for message notification operations</td> |
| <td>Unreliable, lost when restart the server</td> |
| <td>Can be used in the production environment</td> |
| <td>Registry</td> |
| </tr> |
| <tr> |
| <td>Forking Cluster</td> |
| <td>Tested</td> |
| <td>Multiple servers are invoked in parallel, as long as one success is returned, often used for high real-time reading operations.</td> |
| <td>Need to waste more service resources</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>Broadcast Cluster</td> |
| <td>Tested</td> |
| <td>A broadcast calls all providers, one by one, and any error is wrongly reported, usually used to update the provider&rsquo;s local state</td> |
| <td>The speed is slow, and any false report is wrong.</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Random LoadBalance</td> |
| <td>Stable</td> |
| <td>Random probability, set random probability according to weight(recommended)</td> |
| <td>The probability of a collision on a cross section is high. When retrying, there may be an unequal instantaneous pressure.</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>RoundRobin LoadBalance</td> |
| <td>Stable</td> |
| <td>Round Robin, setting wheel based ratio according to the weight after the Convention</td> |
| <td>There is a slow machine accumulation request problem, and extreme circumstances may cause an avalanche</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>LeastActive LoadBalance</td> |
| <td>Stable</td> |
| <td>The least active call number, the random number of the same active number, the active number is the count difference before and after the call, making the slow machine receive less request.</td> |
| <td>Do not support the weight, in the capacity planning, not to pressure a machine oriented pressure measurement by weight capacity</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>ConsistentHash LoadBalance</td> |
| <td>Stable</td> |
| <td>The consistency hash, the same parameters always request to the same provider, when one provider hung, originally sent to the provider&rsquo;s request, based on virtual nodes, spread to other providers, will not cause dramatic changes</td> |
| <td>Uneven distribution of pressure</td> |
| <td>Can be used in the production environment</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Condition routing rule</td> |
| <td>Stable</td> |
| <td>Routing rules based on conditional expressions, simple and easy to use</td> |
| <td>There are some complex multi branch conditions, and the rules are difficult to describe</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Script routing rules</td> |
| <td>Tested</td> |
| <td>Routing rules based on the script engine, powerful</td> |
| <td>No sandbox is running, scripting ability is too powerful and may be the back door</td> |
| <td>On trial</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <table> |
| <thead> |
| <tr> |
| <th>Feature</th> |
| <th>Maturity</th> |
| <th>Strength</th> |
| <th>Problem</th> |
| <th>Advise</th> |
| <th>User</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Spring Container</td> |
| <td>Stable</td> |
| <td>Automatically load all Spring configurations under the META-INF/spring directory</td> |
| <td></td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Jetty Container</td> |
| <td>Stable</td> |
| <td>Start an embedded Jetty for reporting state</td> |
| <td>When a large number of pages are accessed, the threads and memory of the server are affected</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| <tr> |
| <td>Log4j Container</td> |
| <td>Stable</td> |
| <td>Configuring the configuration of the log4j automatically, automatically subdirecting the log files by process at the startup of multiple processes</td> |
| <td>The user can&rsquo;t control the configuration of log4j, inflexible</td> |
| <td>Can be used in the production environment</td> |
| <td>Alibaba</td> |
| </tr> |
| </tbody> |
| </table></description></item><item><title>Docs: Dubbo Configuration</title><link>https://dubbo.apache.org/en/docs/v2.7/user/configuration/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/configuration/</guid><description/></item><item><title>Docs: Dubbo Examples</title><link>https://dubbo.apache.org/en/docs/v2.7/user/examples/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/examples/</guid><description> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">Tips</h4> |
| <p>To complete run, please see: <a href="../quick-start">quick start</a>, here just lists the configuration of various scenarios.</p> |
| <p>The following examples are all based on Spring configuration: <a href="../configuration/xml">XML configuration</a> for reference, if you do not want to use Spring, but want to be use it via the directly API, please see: <a href="../configuration/api">API configuration</a></p> |
| </div></description></item><item><title>Docs: References</title><link>https://dubbo.apache.org/en/docs/v2.7/user/references/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/references/</guid><description/></item><item><title>Docs: Best practice</title><link>https://dubbo.apache.org/en/docs/v2.7/user/best-practice/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/best-practice/</guid><description> |
| <h2 id="modularization">Modularization</h2> |
| <p>It is recommended to put service interfaces, service models, service exceptions, and so on in the API package,Because the service model and exception are part of the API, it is also in conformity with the modularization principle:Reusing the publish equivalence principle (REP) and the Common Reuse Principle (CRP).</p> |
| <p>If you need, you can also consider placing a spring reference configuration in the API package, so that the user can only use the configuration in the spring loading process, and the configuration suggestion is placed in the package directory of the module, so as not to conflict, eg:<code>com/alibaba/china/xxx/dubbo-reference.xml</code>。</p> |
| <h2 id="granularity">Granularity</h2> |
| <p>The service interface should have large granularity as possible.Each service method should represent a function rather than a step of a function, otherwise it will be faced with distributed transaction problem. Dubbo does not provide distributed transaction support at present.</p> |
| <p>The service interface recommends the division of the business scene as a unit and abstract the similar business to prevent the explosion of the number of interfaces.</p> |
| <p>It is not recommended to use an too abstract universal interface, such as Map query (Map), which has no explicit semantics, which will inconvenience later maintenance.</p> |
| <h2 id="version">Version</h2> |
| <p>Each interface should define a version number to provide possible subsequent incompatible upgrades,eg: <code>&lt;dubbo:service interface=&quot;com.xxx.XxxService&quot; version=&quot;1.0&quot; /&gt;</code>。</p> |
| <p>It is recommended to use a two bit version number, because the third - bit version number is usually compatible with a compatible upgrade, and a change of service version is required only when incompatible.</p> |
| <p>When incompatible, half of the provider is upgraded to a new version, and all the consumers are upgraded to a new version, and the remaining half providers are upgraded to a new version.</p> |
| <h2 id="compatibility">Compatibility</h2> |
| <p>The service interface adds method or the service model adds fields. It can be backward compatible, delete methods or delete fields, and will not be compatible. The new fields of the enumerated type are not compatible, so we need to upgrade by changing the version number.</p> |
| <p>The compatibility of each protocol is different, see: <a href="../references/protocol/">Protocol introduction</a></p> |
| <h2 id="enumeration-type">Enumeration type</h2> |
| <p>If it is a complete set, you can use Enum, eg:<code>ENABLE</code>, <code>DISABLE</code>。</p> |
| <p>If it is the type of business, there will be an obvious type of increase in the future, and it is not recommended to use <code>Enum</code>, and it is not recommended to use Enum and can be replaced by <code>String</code> .</p> |
| <p>If you use<code>Enum</code>in the return value,And add the <code>Enum</code> value,suggestions to upgrade the service consumption, so that the service provider does not return a new value.</p> |
| <p>If the <code>Enum</code> value is used in the incoming parameter,and add the <code>Enum</code> value,it is suggested that the service provider be upgraded first, so that the service consumer will not pass the new value.</p> |
| <h2 id="serialization">Serialization</h2> |
| <p>The service parameters and return values suggest that the POJO object is used, that is, the object of the attribute is represented by the <code>setter</code>, <code>getter</code> method.</p> |
| <p>Service parameters and return values do not recommend the use of interfaces, because data model abstraction is of little significance, and serialization requires interfaces to implement meta information of classes, and can not play the purpose of hiding implementation.</p> |
| <p>Service parameters and return values must be byValue, but not byReference. The reference or return values of consumers and providers are not the same, but the values are the same. Dubbo does not support remote objects.</p> |
| <h2 id="exception">Exception</h2> |
| <p>It is suggested that abnormal reporting errors are used rather than return error codes, and exception information can carry more information and have more semantic friendliness.</p> |
| <p>If you are worried about performance problems, you can use the override () method of fillInStackTrace () out of the exception class as an empty method to make it not a copy of the stack information when necessary.</p> |
| <p>Query method is not recommended throws checked, otherwise the caller in the query will be too much <code>try...catch, and can not be processed.</code></p> |
| <p>Service providers should not throw the exception of DAO or SQL to the consumer side. They should package the exception that consumers do not care about in service implementation, otherwise consumers may not be able to serialize the corresponding exception.</p> |
| <h2 id="call">Call</h2> |
| <p>Not just because it is a Dubbo call, wrap the call logic with <code>try...catch</code>clause. <code>try...catch</code> should be added to the appropriate rollback boundary.</p> |
| <p>The check logic for the input parameters should be available at the Provider side. For performance considerations, the service implementer may consider adding a service Stub class to the API package to complete the test.</p></description></item><item><title>Docs: Recommended usage</title><link>https://dubbo.apache.org/en/docs/v2.7/user/recommend/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/recommend/</guid><description> |
| <h2 id="configuring-the-attributes-of-the-consumer-side-as-much-as-possible-on-the-provider-side">Configuring the attributes of the consumer side as much as possible on the provider side</h2> |
| <p>the reason is：</p> |
| <ul> |
| <li>Service providers are more aware of service performance parameters than service users，Such as the timeout time of the call, the reasonable retry times, and so on.</li> |
| <li>If a attribute is configurated in provider side, not configurated in consumer side, consumer service will use the attribute in provider side. That is to say, the provider side&rsquo;s attribute can be used as consumer&rsquo;s default value <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>. Otherwise, consumer service will use consumer-side&rsquo;s attribute，but can&rsquo;t cnotrol the provider service,it&rsquo;s usually unreasonable.</li> |
| </ul> |
| <p>Configuring the attributes of the consumer side as much as possible on the provider side，Make the provider service developer think more about the characteristics and quality of the provider side service.</p> |
| <p>Examples：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;com.alibaba.hello.api.HelloService&#34;</span> version=<span style="color:#2aa198">&#34;1.0.0&#34;</span> ref=<span style="color:#2aa198">&#34;helloService&#34;</span> |
| </span></span><span style="display:flex;"><span> timeout=<span style="color:#2aa198">&#34;300&#34;</span> retry=<span style="color:#2aa198">&#34;2&#34;</span> loadbalance=<span style="color:#2aa198">&#34;random&#34;</span> actives=<span style="color:#2aa198">&#34;0&#34;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;com.alibaba.hello.api.WorldService&#34;</span> version=<span style="color:#2aa198">&#34;1.0.0&#34;</span> ref=<span style="color:#2aa198">&#34;helloService&#34;</span> |
| </span></span><span style="display:flex;"><span> timeout=<span style="color:#2aa198">&#34;300&#34;</span> retry=<span style="color:#2aa198">&#34;2&#34;</span> loadbalance=<span style="color:#2aa198">&#34;random&#34;</span> actives=<span style="color:#2aa198">&#34;0&#34;</span> <span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:method</span> name=<span style="color:#2aa198">&#34;findAllPerson&#34;</span> timeout=<span style="color:#2aa198">&#34;10000&#34;</span> retries=<span style="color:#2aa198">&#34;9&#34;</span> loadbalance=<span style="color:#2aa198">&#34;leastactive&#34;</span> actives=<span style="color:#2aa198">&#34;5&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service/&gt;</span> |
| </span></span></code></pre></div><p>The consumer side properties that can be configured on provider are：</p> |
| <ol start="0"> |
| <li><code>timeout</code> Method call timeout</li> |
| <li><code>retries</code> The number of failed retries, default value is 1 <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup></li> |
| <li><code>loadbalance</code> Load balance algorithm <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>，default algorithm is random <code>random</code>,and polling <code>roundrobin</code>、least active <sup id="fnref:4"><a href="#fn:4" class="footnote-ref" role="doc-noteref">4</a></sup> <code>leastactive</code></li> |
| <li><code>actives</code> Consumer side, maximum concurrent call limitation. That is , when the concurrent requests of consumer service reach maximum configuration,the new call will wait until to catch a timeout error. |
| Configurated in <code>dubbo:method</code>(method level configuration) , then the concurrent limitation point at method.Configurated in <code>dubbo:service</code>(service level configuration),then the concurrent limitation point at service.</li> |
| </ol> |
| <p>Detailed configuration instructions see：<a href="../references/xml/">Dubbo configuration introduction</a></p> |
| <h2 id="configuring-reasonable-provider-end-properties-on-provider">Configuring reasonable provider end properties on provider</h2> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> threads=<span style="color:#2aa198">&#34;200&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;com.alibaba.hello.api.HelloService&#34;</span> version=<span style="color:#2aa198">&#34;1.0.0&#34;</span> ref=<span style="color:#2aa198">&#34;helloService&#34;</span> |
| </span></span><span style="display:flex;"><span> executes=<span style="color:#2aa198">&#34;200&#34;</span> <span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:method</span> name=<span style="color:#2aa198">&#34;findAllPerson&#34;</span> executes=<span style="color:#2aa198">&#34;50&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dubbo:service&gt;</span> |
| </span></span></code></pre></div><p>The provider side properties that can be configured on provider service are：</p> |
| <ol start="0"> |
| <li><code>threads</code> service thread pool size</li> |
| <li><code>executes</code> If concurrent requests number that a provider service handled reach the maximum thead pool count , the new call will wait,then the consumer call may catch a timeout error. Configurated in <code>dubbo:method</code>(method level configuration) , then the concurrent limitation point at method.Configurated in <code>dubbo:service</code>(service level configuration),then the concurrent limitation point at service.</li> |
| </ol> |
| <h2 id="configuration-management-information">Configuration management information</h2> |
| <p>Now we have the owner information and organization infomation to differentiate the sites。It&rsquo;s easy to contact with the service owners when there is a problem, please write at least two persons for backup. The information of owners and organizations can be seen in the registry.</p> |
| <p>application configuration owners,organizations:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:application</span> owner=<span style="color:#2aa198">”ding.lid,william.liangf”</span> organization=<span style="color:#2aa198">”intl”</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>service configuration owners:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> owner=<span style="color:#2aa198">”ding.lid,william.liangf”</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>reference configuration owners:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> owner=<span style="color:#2aa198">”ding.lid,william.liangf”</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><code>dubbo:service</code>、<code>dubbo:reference</code> have no configuration owner, then use the owner configured in <code>dubbo:application</code>.</p> |
| <h2 id="set-up-the-dubbo-cache-file">Set up the Dubbo cache file</h2> |
| <p>Provider service list caching file:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:registry</span> file=<span style="color:#2aa198">”${user.home}/output/dubbo.cache”</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Notations:</p> |
| <ol start="0"> |
| <li>You can modify the cahe file path of the application according to the needs. Ensure that the file will not be cleared during the release process.</li> |
| <li>If there are more than one application process, do not use the same file path to avoid the content being overwritten.</li> |
| </ol> |
| <p>This file caches the list of the registry and the list of service providers. With this configuration, when the application is restarted , if the Dubbo registry is not available, the application will read the information from the service provider list from the cache file. That can ensure the availability of the application.</p> |
| <h2 id="monitor-configuration">Monitor configuration</h2> |
| <ol start="0"> |
| <li> |
| <p>Expose service with a fixed port, instead of using a random port</p> |
| <p>In this way, when there is a delay in the registry push, the consumer can also call the original provider service address hrough the cache list and succeed。</p> |
| </li> |
| <li> |
| <p>Use Dragoon&rsquo;s HTTP monitoring item to monitor the service provider on the registry</p> |
| <p>The state of Dragoon monitoring service in the registry : <code>http://dubbo-reg1.hst.xyi.cn.alidc.net:8080/status/com.alibaba.morgan.member.MemberService:1.0.5</code> Ensure that the service exists on the registry .</p> |
| </li> |
| <li> |
| <p>Service provider,use Dragoon&rsquo;s telnet mommand or shell monitor command</p> |
| <p>Monitoring service provider port status ：<code>echo status | nc -i 1 20880 | grep OK | wc -l</code>, 20880 is the service port</p> |
| </li> |
| <li> |
| <p>Service consumer side, cast the service to EchoService，and call <code>$echo()</code> to test whether the provider of the service is available</p> |
| <p>eg: <code>assertEqauls(“OK”, ((EchoService)memberService).$echo(“OK”));</code></p> |
| </li> |
| </ol> |
| <h2 id="dont-use-the-configuration-of-dubboproperties-file-suggeset-to-use--the-configuration-of-xml">Don&rsquo;t use the configuration of dubbo.properties file, suggeset to use the configuration of XML</h2> |
| <p>All of the configuration items in the dubbo can be configured in the spring configuration file,and can be configured for a single service.</p> |
| <p>The Dubbo default value is used if completely not set up , please see the instructions in the article <a href="../references/xml/">Dubbo configuration introduction</a> .</p> |
| <h3 id="the-relation-between-attribute-name-of-dubboproperties-and-xml">The relation between attribute name of dubbo.properties and XML</h3> |
| <ol start="0"> |
| <li> |
| <p>application name <code>dubbo.application.name</code></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;myalibaba&#34;</span> <span style="color:#268bd2">&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>registry address <code>dubbo.registry.address</code></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:registry</span> address=<span style="color:#2aa198">&#34;11.22.33.44:9090&#34;</span> <span style="color:#268bd2">&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>call timeout <code>dubbo.service.*.timeout</code></p> |
| <p>Timeout can be set in multiple configuration items <code>timeout</code>,cover from top to bottom （The top one have a higher priority ）<sup id="fnref:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup>，The coverage strategy of other parameters（<code>retries</code>、<code>loadbalance</code>、<code>actives</code> and so on）is：</p> |
| <p>Certain method Configuration of a provider service</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;com.alibaba.xxx.XxxService&#34;</span> <span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo:method</span> name=<span style="color:#2aa198">&#34;findPerson&#34;</span> timeout=<span style="color:#2aa198">&#34;1000&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dubbo:service&gt;</span> |
| </span></span></code></pre></div><p>Configuration of a provider specific interface</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;com.alibaba.xxx.XxxService&#34;</span> timeout=<span style="color:#2aa198">&#34;200&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>Service provider protocol <code>dubbo.service.protocol</code>、Service monitor port <code>dubbo.service.server.port</code></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20880&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>Service thread pool size <code>dubbo.service.max.thread.threads.size</code></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> threads=<span style="color:#2aa198">&#34;100&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>No provider throws exceptions (Fast-Fail) when the consumer is started () |
| <code>alibaba.intl.commons.dubbo.service.allow.no.provider</code></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> interface=<span style="color:#2aa198">&#34;com.alibaba.xxx.XxxService&#34;</span> check=<span style="color:#2aa198">&#34;false&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></li> |
| </ol> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>Overlay rules for configuration: 1) The method level configuration has a higher priority than the interface level, that is to say,small scope have a high priority 2) Consumer side configuration has a higher priority than provider side, better than global configuration, the last one is the Dubbo hard coded configuration value（<a href="https://dubbo.apache.org/en/docs/v2.7/user/configuration/properties/">Dubbo configuration introduction</a>）&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>With the first call, the call will be called 3 times&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>How to select a service to call when there are multiple Provider services&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:4"> |
| <p>It means that consumer service can call the best provider service, and reduce to call the the slow provider service.&#160;<a href="#fnref:4" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:5"> |
| <p><code>timeout</code> Can be set in multiple places, configuration items and overlay rules： <a href="../references/xml/">Dubbo Schema configuration introduction</a>&#160;<a href="#fnref:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Capacity plan</title><link>https://dubbo.apache.org/en/docs/v2.7/user/capacity-plan/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/capacity-plan/</guid><description> |
| <p>The following data for reference：</p> |
| <h2 id="use-member-service-project-of-dubbo">Use member service project of Dubbo</h2> |
| <ul> |
| <li>Receive 400,000,000 remote calls one day</li> |
| <li>Use 12 standard servers to provide services (CPU:8 core, memory: 8G)</li> |
| <li>The average load is less than 1 (For 8 core CPU, the load is very low)</li> |
| <li>The average response time is 2.3 to 2.5 ms，Network cost about 1.5 to 1.6 ms(Related to the size of the packet )</li> |
| </ul> |
| <h2 id="use-product-authorization-service-project-of-dubbo">Use product authorization service project of Dubbo</h2> |
| <ul> |
| <li>Receive 300,000,000 remote calls one day</li> |
| <li>Use 8 standard servers to provide services (CPU:8 core, memory: 8G)</li> |
| <li>The average load is less than 1 (For 8 core CPU, the load is very low)</li> |
| <li>The average response time is 1.4 to 2.8 ms，Network cost about 1.0 to 1.1 ms(Related to the size of the packet )</li> |
| </ul></description></item><item><title>Docs: Performance</title><link>https://dubbo.apache.org/en/docs/v2.7/user/perf-test/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/perf-test/</guid><description> |
| <h2 id="test-instructions">Test instructions</h2> |
| <ol start="0"> |
| <li>In this performance test, the performance of all Dubbo 2.0 supported protocols in different sizes and data types is tested and compared with the Dubbo 1.0.</li> |
| <li>The overall performance is increased by 1.0 compared with 10%, and the average increase is 10%. The performance improvement of 10%~50% can also be achieved by using the new Dubbo serialization of Dubbo 2.0 .</li> |
| <li>In the stability test, because the underlying communication framework is changed from Mina to netty, the growth of objects in old area is greatly reduced, and the 50 hour operation increases less than 200m and no fullgc.</li> |
| <li>There is a problem: performance of 2.0 is less than 1.0 in 50K data, and it is doubted that it may be a buffer setting problem, and the next version will be further confirmed.</li> |
| </ol> |
| <h2 id="test-environment">Test environment</h2> |
| <h3 id="hardware-deployment-and-parameter-adjustment">Hardware deployment and parameter adjustment</h3> |
| <table> |
| <thead> |
| <tr> |
| <th>Model</th> |
| <th>CPU</th> |
| <th>Memory</th> |
| <th>Network</th> |
| <th>Disk</th> |
| <th>Kernel</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Tecal BH620</td> |
| <td>model name : Intel(R) Xeon(R) CPU E5520 @ 2.27GHz cache size : 8192 KB processor_count : 16</td> |
| <td>Total System Memory: 6G Hardware Memory Info: Size: 4096MB</td> |
| <td>eth0: Link is up at 1000 Mbps, full duplex. peth0: Link is up at 1000 Mbps, full duplex.</td> |
| <td>/dev/sda: 597.9 GB</td> |
| <td>2.6.18-128.el5xen x86_64</td> |
| </tr> |
| </tbody> |
| </table> |
| <h3 id="software-architecture">Software architecture</h3> |
| <table> |
| <thead> |
| <tr> |
| <th>Software name and version</th> |
| <th>key parameter</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>java version &ldquo;1.6.0_18&rdquo; Java(TM) SE Runtime Environment (build 1.6.0_18-b07) Java HotSpot(TM) 64-Bit Server VM (build 16.0-b13, mixed mode)</td> |
| <td>-server -Xmx2g -Xms2g -Xmn256m -XX:PermSize=128m -Xss256k -XX:+DisableExplicitGC -XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+UseCMSCompactAtFullCollection -XX:LargePageSizeInBytes=128m -XX:+UseFastAccessorMethods -XX:+UseCMSInitiatingOccupancyOnly -XX:CMSInitiatingOccupancyFraction=70</td> |
| </tr> |
| <tr> |
| <td>jboss-4.0.5.GA</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>httpd-2.0.61</td> |
| <td>KeepAlive On MaxKeepAliveRequests 100000 KeepAliveTimeout 180 MaxRequestsPerChild 1000000 <IfModule worker.c> StartServers 5 MaxClients 1024 MinSpareThreads 25 MaxSpareThreads 75 ThreadsPerChild 64 ThreadLimit 128 ServerLimit 16 </IfModule></td> |
| </tr> |
| </tbody> |
| </table> |
| <h2 id="test-purpose">Test purpose</h2> |
| <h3 id="expected-performance-indicators-quantized">Expected performance indicators (quantized)</h3> |
| <table> |
| <thead> |
| <tr> |
| <th>Scene name</th> |
| <th>Corresponding index name</th> |
| <th>Range of expected values</th> |
| <th>Actual value</th> |
| <th>Whether or not to meet expectations (yes / no)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>1k data</td> |
| <td>Response time</td> |
| <td>0.9ms</td> |
| <td>0.79ms</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>1k data</td> |
| <td>TPS</td> |
| <td>10000</td> |
| <td>11994</td> |
| <td>Yes</td> |
| </tr> |
| </tbody> |
| </table> |
| <h3 id="expected-operating-conditions-non-quantified-optional">Expected operating conditions (non quantified, optional)</h3> |
| <ul> |
| <li>The performance of 2.0 is not less than 1, and the performance of the intermodulation of 2.0 and 1.0 is not significantly reduced. In addition to 50K string, the rest are passed</li> |
| <li>JVM memory is running stable, no OOM, and there is no reasonable large object in the heap memory. Passed</li> |
| <li>CPU, memory, network, disk, file handle are occupied smoothly. Passed</li> |
| <li>There is no frequent thread lock, and the number of threads is stable. Passed</li> |
| <li>Business thread load balance. Passed</li> |
| </ul> |
| <h2 id="test-script">Test script</h2> |
| <ol start="0"> |
| <li> |
| <p>Performance test scence (10 concurrency)</p> |
| <ul> |
| <li>Pass in 1K String, do not do anything, return the original</li> |
| <li>Pass in 50K String, do not do anything, return the original</li> |
| <li>Pass in 200K String, do not do anything, return the original</li> |
| <li>Incoming 1K POJO (nested complex person objects) without any processing, return to the original</li> |
| </ul> |
| <p>The above scenario is tested for 10 minutes in Dubbo 1.0, Dubbo 2.0 (hessian2 serialization), Dubbo 2.0 (Dubbo serialization), RMI, Hessian 3.2.0, HTTP (JSON serialization). It mainly examines the performance of serialization and network IO, so the server has no business logic. 10 is to consider the concurrent HTTP protocol in high with the use of CPU high rate may hit the bottleneck.</p> |
| </li> |
| <li> |
| <p>Concurrent scene (20 concurrency) |
| 1K String is introduced into the server segment for 1W times, and a random number is regenerated each time and then assembled. Examine whether business threads can be assigned to each CPU.</p> |
| </li> |
| <li> |
| <p>Stability scence (20 concurrency) |
| At the same time, we call the 1 parameter String (5K) method, the 1 parameter is the person object method, the 1 parameter is map (the value is 3 person), and it runs for 50 hours continuously.</p> |
| </li> |
| <li> |
| <p>High pressure scene (20 concurrency) |
| On the basis of the stability scenario, the providers and consumers are arranged into 2 sets (one machine and 2 instances), and the parameters of String are 20byte to 200K, and are randomly transformed every 10 minutes.</p> |
| </li> |
| </ol> |
| <h2 id="test-result">Test result</h2> |
| <h3 id="scene-name-scence-pojo">Scene name: scence POJO</h3> |
| <table> |
| <thead> |
| <tr> |
| <th></th> |
| <th>TPS success avg value</th> |
| <th>Response time avg value(ms)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>dubbo1 (hessian2 serialization+mina)</td> |
| <td>10813.5</td> |
| <td>0.9</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (hessian2 serialization+netty)</td> |
| <td>11994</td> |
| <td>0.79</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (dubbo serialization+netty)</td> |
| <td>13620</td> |
| <td>0.67</td> |
| </tr> |
| <tr> |
| <td>rmi</td> |
| <td>2461.79</td> |
| <td>4</td> |
| </tr> |
| <tr> |
| <td>hessian</td> |
| <td>2417.7</td> |
| <td>4.1</td> |
| </tr> |
| <tr> |
| <td>http（json serialization）</td> |
| <td>8179.08</td> |
| <td>1.15</td> |
| </tr> |
| <tr> |
| <td>The default percentage of 2.0 and 1.0</td> |
| <td>10.92</td> |
| <td>-12.22</td> |
| </tr> |
| <tr> |
| <td>Dubbo serialization compared to the percentage of hessian2 serialization</td> |
| <td>13.56</td> |
| <td>-15.19</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>POJO TPS</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/pojotps.png" alt="pojotps.png"></p> |
| <p>POJO Response</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/pojores.png" alt="pojores.png"></p> |
| <h3 id="scene-name-scence-1k-string">Scene name: scence 1k string</h3> |
| <table> |
| <thead> |
| <tr> |
| <th></th> |
| <th>TPS success avg value</th> |
| <th>Response time avg value(ms)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>dubbo1（hessian2 serialization+mina）</td> |
| <td>11940</td> |
| <td>0.8</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (hessian2 serialization+netty)</td> |
| <td>14402</td> |
| <td>0.64</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (dubbo serialization+netty)</td> |
| <td>15096</td> |
| <td>0.6</td> |
| </tr> |
| <tr> |
| <td>rmi</td> |
| <td>11136.02</td> |
| <td>0.81</td> |
| </tr> |
| <tr> |
| <td>hessian</td> |
| <td>11426.83</td> |
| <td>0.79</td> |
| </tr> |
| <tr> |
| <td>http（json serialization）</td> |
| <td>8919.27</td> |
| <td>1.04</td> |
| </tr> |
| <tr> |
| <td>The default percentage of 2.0 and 1.0</td> |
| <td>20.62</td> |
| <td>-20.00</td> |
| </tr> |
| <tr> |
| <td>Dubbo serialization compared to the percentage of hessian2 serialization</td> |
| <td>4.82</td> |
| <td>-6.25</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>1k TPS</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/1ktps.png" alt="1ktps.png"></p> |
| <p>1k Response</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/1kres.png" alt="1kres.png"></p> |
| <h3 id="scene-name-scence-50k-string">Scene name: scence 50k string</h3> |
| <table> |
| <thead> |
| <tr> |
| <th>TPS success avg value</th> |
| <th>Response time avg value(ms)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>dubbo1（hessian2 serialization+mina</td> |
| <td>1962.7</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (hessian2 serialization+netty)</td> |
| <td>1293</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (dubbo serialization+netty)</td> |
| <td>1966</td> |
| </tr> |
| <tr> |
| <td>rmi</td> |
| <td>3349.88</td> |
| </tr> |
| <tr> |
| <td>hessian</td> |
| <td>1925.33</td> |
| </tr> |
| <tr> |
| <td>http（json serialization）</td> |
| <td>3247.1</td> |
| </tr> |
| <tr> |
| <td>The default percentage of 2.0 and 1.0</td> |
| <td>-34.12</td> |
| </tr> |
| <tr> |
| <td>Dubbo serialization compared to the percentage of hessian2 serialization</td> |
| <td>52.05</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>50K TPS</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/50ktps.png" alt="50ktps.png"></p> |
| <p>50K Response</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/50kres.png" alt="50kres.png"></p> |
| <h3 id="scene-name-scence-200k-string">Scene name: scence 200k string</h3> |
| <table> |
| <thead> |
| <tr> |
| <th>TPS success avg value</th> |
| <th>Response time avg value(ms)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>dubbo1（hessian2 serialization+mina）</td> |
| <td>324.2</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (hessian2 serialization+netty)</td> |
| <td>362.92</td> |
| </tr> |
| <tr> |
| <td>dubbo2 (dubbo serialization+netty)</td> |
| <td>569.5</td> |
| </tr> |
| <tr> |
| <td>rmi</td> |
| <td>1031.28</td> |
| </tr> |
| <tr> |
| <td>hessian</td> |
| <td>628.06</td> |
| </tr> |
| <tr> |
| <td>http（json serialization）</td> |
| <td>1011.97</td> |
| </tr> |
| <tr> |
| <td>The default percentage of 2.0 and 1.0</td> |
| <td>11.94</td> |
| </tr> |
| <tr> |
| <td>Dubbo serialization compared to the percentage of hessian2 serialization</td> |
| <td>56.92</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>200K TPS</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/200ktps.png" alt="200ktps.png"></p> |
| <p><strong>200K Response</strong></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/200kres.png" alt="200kres.png"></p> |
| <h2 id="test-analysis">Test analysis</h2> |
| <h3 id="performance-analysis-and-evaluation">Performance analysis and evaluation</h3> |
| <p>The performance test conclusion of Dubbo 2 has been improved and improved from performance, memory footprint and stability. Because of its memory management, the change of Mina into netty greatly reduces the 1 version of the large memory sawtooth in high concurrency and large data.</p> |
| <h3 id="performance-comparison-analysis-new-and-old-environment-different-data-magnitude-etc">Performance comparison analysis (new and old environment, different data magnitude, etc.)</h3> |
| <p>The performance of Dubbo 2 is compared with that of Dubbo 1, which is all hessian2 serialization. The performance is improved (except for 50K String). See the performance data of the fifth chapter in detail.</p> |
| <p>For compatibility default serialization and 1 consistent with hessian2, such as have higher requirements on the performance of Dubbo serialization can be used, which is in the process of complicated object, can be obtained in 50% large data upgrade (but it is not recommended for use Dubbo protocol).</p> |
| <p>The purpose of Dubbo is to meet the RPC calls with high concurrent and small data volume. The performance is not good under large data volume. It is recommended to use RMI or HTTP protocol.</p> |
| <h3 id="test-limitation-analysis-optional">Test limitation analysis (optional)</h3> |
| <p>This performance test examines the performance of the Dubbo itself, and the performance of the actual use needs to be verified.</p> |
| <p>Because the performance of Dubbo itself is in millisecond and the base number is small, performance improvement may not change the performance of the application as a whole.</p> |
| <p>All the monitoring charts are not listed because of the limit of length.</p></description></item><item><title>Docs: Test coverage report</title><link>https://dubbo.apache.org/en/docs/v2.7/user/coveragence/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/coveragence/</guid><description> |
| <ul> |
| <li>v2.0 Codecov report , Statistics since 2017-12-29 |
| The test coverage is : <a href="https://codecov.io/gh/apache/dubbo"><img src="https://codecov.io/gh/apache/dubbo/branch/master/graph/badge.svg" alt="codecov"></a> , we can get the report in <a href="https://codecov.io/gh/apache/dubbo">https://codecov.io/gh/apache/dubbo</a></li> |
| <li>v1.0 Based on version <code>2.0.12</code>，Statistics on 2012-02-03</li> |
| </ul> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality1.jpg" alt="code-quality1.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality2.jpg" alt="code-quality2.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality3.jpg" alt="code-quality3.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality4.jpg" alt="code-quality4.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality5.jpg" alt="code-quality5.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality6.jpg" alt="code-quality6.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-quality7.jpg" alt="code-quality7.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-coverage.jpg" alt="code-coverage.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-tendency.jpg" alt="code-tendency.jpg"></p> |
| <p><img src="https://dubbo.apache.org/imgs/user/code-dependency.jpg" alt="code-dependency.jpg"></p></description></item><item><title>Docs: Benchmark Suite</title><link>https://dubbo.apache.org/en/docs/v2.7/user/benchmark-tool/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/benchmark-tool/</guid><description> |
| <ul> |
| <li>download： git clone <a href="https://github.com/apache/dubbo.git">https://github.com/apache/dubbo.git</a></li> |
| <li>compile benchmark: cd dubbo/dubbo-test/dubbo-test-benchmark; mvn clean install</li> |
| <li>uncompress benchmark： dubbo/dubbo-test/dubbo-test-benchmark/target/dubbo-test-benchmark-2.6.2-SNAPSHOT.tar.gz</li> |
| </ul> |
| <p>Read ReadMe.txt (the contents are as follows, in the compressed package.)</p> |
| <ul> |
| <li> |
| <p>Build a new benchmark project, such as demo.benchmark</p> |
| </li> |
| <li> |
| <p>Import the your own interface api jar and dubbo.benchmark.jar (Unzip dubbo.benchmark.tar.gz, under the lib directory )</p> |
| </li> |
| <li> |
| <p>Create a new class to implement AbstractClientRunnable</p> |
| <ul> |
| <li>Implement the constructor of the parent class</li> |
| <li>Implement the invoke method and create a local interface proxy by serviceFactory，and finish your own business logic, as follows:</li> |
| </ul> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> Object <span style="color:#268bd2">invoke</span>(ServiceFactory serviceFactory) { |
| </span></span><span style="display:flex;"><span> DemoService demoService <span style="color:#719e07">=</span> (DemoService) serviceFactory.get(DemoService.class); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> demoService.sendRequest(<span style="color:#2aa198">&#34;hello&#34;</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div></li> |
| <li> |
| <p>Make your own benchmark project into a jar package, such as demo.benchmark.jar</p> |
| </li> |
| <li> |
| <p>Put the demo.benchmark.jar and service API jar into directory dubbo.benchmark/lib</p> |
| </li> |
| <li> |
| <p>Configuring dubbo.properties</p> |
| </li> |
| <li> |
| <p>Run run.bat(windows) or run.sh(linux)</p> |
| </li> |
| </ul> |
| <p>If you want to test the different versions of Dubbo, you can replace the jar of the Dubbo.</p></description></item><item><title>Docs: REST support</title><link>https://dubbo.apache.org/en/docs/v2.7/user/rest/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/rest/</guid><description> |
| <div class="pageinfo pageinfo-primary"> |
| <p>Original author: Li Shen |
| Document copyright: <a href="HTTP://www.apache.org/licenses/LICENSE-2.0">Apache 2.0license Signature - No interpretation</a></p> |
| <p>Working in progress &hellip;</p> |
| </div> |
| <blockquote> |
| <p>This article is lengthy since REST involves many aspects. Besides, it refers to the document style of Spring and so on. Not only limited to usage of the framework but also strives to present the design concept of the framework and the architectural idea of an excellent application. |
| For people who only want to get a glimpse of Dubbo and REST, all they need is to browse through the <code>Overview</code> to <code>Introduction to Standard Java REST API: JAX-RS</code>.</p> |
| </blockquote> |
| <h2 id="content">CONTENT</h2> |
| <ul> |
| <li>Overview</li> |
| <li>Advantages of REST</li> |
| <li>Application Scenarios</li> |
| <li>Quick Start</li> |
| <li>Introduction to Standard Java REST API: JAX-RS</li> |
| <li>Details of REST Service Provider |
| <ul> |
| <li>Implementation of HTTP POST/GET</li> |
| <li>Should Annotation be Placed in the Interface or Implementation</li> |
| <li>Support for Multiple Data Formats (JSON, XML, etc.)</li> |
| <li>Support for Chinese Characters</li> |
| <li>Additional Requirements for XML Format</li> |
| <li>Custom Serialization</li> |
| <li>Configure the Implementation of REST Server</li> |
| <li>Access Context Data</li> |
| <li>Configure the Port Number and Context Path</li> |
| <li>Configure Number of Threads and IO Threads</li> |
| <li>Configure Persistent Connection</li> |
| <li>Configure Maximum Number of HTTP Connections</li> |
| <li>Configure Timeout and HTTP Connections Per Consumer</li> |
| <li>Gzip Data Compression</li> |
| <li>Replace Part of Spring XML Configuration With Annotation</li> |
| <li>Add Custom Filter, Interceptor, etc.</li> |
| <li>Add Custom Exception Handler</li> |
| <li>Configure HTTP Log Output</li> |
| <li>Verification of Input Parameters</li> |
| <li>Should REST Services be Published Transparently</li> |
| <li>Get Headers In Dubbo Rest Provider</li> |
| </ul> |
| </li> |
| <li>Details of REST Service Consumer |
| <ul> |
| <li>Scenario 1: Non-Dubbo Consumer Calls Dubbo REST Service</li> |
| <li>Scenario 2: Dubbo Consumer Calls Dubbo REST Service</li> |
| <li>Scenario 3: Dubbo Consumer Calls Non-Dubbo REST Service</li> |
| <li>Custom Header By Dubbo Consumer while Calling REST Service</li> |
| </ul> |
| </li> |
| <li>JAX-RS Restrictions in Dubbo</li> |
| <li>REST FAQ |
| <ul> |
| <li>Can Dubbo REST Services be Integrated With Dubbo Registration Center and Monitoring Center?</li> |
| <li>How to Implement Load Balancing and Failover in Dubbo REST?</li> |
| <li>Can Overloaded Methods in JAX-RS Map to Single URL?</li> |
| <li>Can a Method in JAX-RS Receive Multiple Parameters Via POST?</li> |
| </ul> |
| </li> |
| <li>Possible shortcomings of Current Dubbo System (Related to REST) |
| <ul> |
| <li>Invasiveness of Rpc Context</li> |
| <li>Limitations of Protocol Configuration</li> |
| <li>XML Naming Does Not Conform to the Convention of Spring</li> |
| </ul> |
| </li> |
| <li>REST Best Practices</li> |
| <li>Performance Benchmark |
| <ul> |
| <li>Test Environment</li> |
| <li>Test Script</li> |
| <li>Test Result</li> |
| </ul> |
| </li> |
| <li>Extended Discussion |
| <ul> |
| <li>Comparison of REST, Thrift, Protobuf, etc.</li> |
| <li>Comparison Between REST and Traditional Web Services</li> |
| <li>Comparison Between JAX-RS and Spring MVC</li> |
| </ul> |
| </li> |
| <li>Future</li> |
| </ul> |
| <h2 id="overview">Overview</h2> |
| <p>Dubbo supports a variety of remote calling methods, such as Dubbo RPC (Binary Serialization + TCP), HTTP Invoker (Binary Serialization + HTTP, at least there is no support for Text Serialization in the open source version), Hessian (Binary Serialization + HTTP), Web Services (Text Serialization + HTTP), etc., but lacks support for trending RESTful Remote Calls (Text Serialization + HTTP).</p> |
| <p>Therefore, based on the standard Java REST API: JAX-RS 2.0 (Abbreviation of Java API for RESTful Web Services), we provide a mostly transparent REST Call support for Dubbo. Since it is fully compatible with the Standard Java API, all REST services developed for Dubbo may normally work without Dubbo or any specific underlying REST implementation.</p> |
| <p>It is particularly worth noting that we do not need to strictly adhere to the original definition and architectural style of REST. Even the famous Twitter REST API will make modest adjustments according to the situations, rather than mechanically follow the original REST style.</p> |
| <blockquote> |
| <p>Note: We call this feature RESTful Remoting (abstracted remote process or call) rather than a RESTful RPC (specific remote &ldquo;procedure&rdquo; call) because REST and RPC can be thought of two different styles. In Dubbo&rsquo;s REST implementation, there are two aspects, one is to provide or consume regular REST services, the other is to make REST a protocol implementation in the Dubbo RPC system, and RESTful Remoting covers both aspects.</p> |
| </blockquote> |
| <h2 id="advantages-of-rest">Advantages of REST</h2> |
| <p>The following is quoted from Wikipedia:</p> |
| <ul> |
| <li>REST can use cache to improve response speed more efficiently.</li> |
| <li>The stateless nature of the communication allows a set of servers to handle different requests in series, resulting in the increment of server scalability.</li> |
| <li>Browser can be used as a client to simplify software requirements.</li> |
| <li>REST software dependency is smaller than other mechanisms superimposed on HTTP.</li> |
| <li>REST does not require additional resource discovery mechanism.</li> |
| <li>REST&rsquo;s long-term compatibility is better in software technology evolution.</li> |
| </ul> |
| <p>Here I also want to add a particular advantage of REST: REST bases on simple text format messages and universal HTTP. Therefore, it has a broad applicability and is supported by almost all languages and platforms, together with a lower threshold in using and learning.</p> |
| <h2 id="application-scenarios">Application scenarios</h2> |
| <p>Because of the advantages of REST in applicability, supporting REST in Dubbo can bring (significant) benefits to most of current mainstream remoting call scenarios:</p> |
| <ol> |
| <li> |
| <p>Significantly simplify (cross-language) calls between heterogeneous systems within the enterprise. This is mainly for the following scene: Dubbo acts as a service provider, and systems that are written by other languages (including some java systems that do not base on Dubbo) works as service consumers. The two systems communicate through HTTP and text messages. REST has its unique advantages even comparing to binary cross-language RPC frameworks such as Thrift and ProtoBuf. (See discussion below)</p> |
| </li> |
| <li> |
| <p>Significantly simplify the development of the external Open API (Open Platform). You can use Dubbo to develop a specific Open API application, or you can directly publish the internal Dubbo service as a &ldquo;transparent&rdquo; REST API (Of course, it&rsquo;s better for Dubbo itself to provide more features transparently, for example, permission control, frequency control, billing and so on).</p> |
| </li> |
| <li> |
| <p>Significantly simplify the development of mobile (tablet) apps or desktop clients. Similar to point 2, you can use Dubbo to develop a specialized server for the applications, or transparently expose the internal Dubbo service. Of course in some projects, mobile or desktop applications can directly access the Open API described in point 2.</p> |
| </li> |
| <li> |
| <p>Significantly simplify the development of AJAX applications on the browser. Similar to point 2, you can use Dubbo to develop a specialized server for AJAX, or transparently expose the internal Dubbo service directly to JavaScript in the browser. Of course, many AJAX applications work better with web frameworks, so direct access to the Dubbo service may not be an exquisite architecture in many web projects.</p> |
| </li> |
| <li> |
| <p>Provide a text-based, easy-to-read remote call method for Dubbo systems within the enterprise (that is, both the service provider and the consumer are Dubbo-based systems).</p> |
| </li> |
| <li> |
| <p>Simplify the call from the Dubbo system to other heterogeneous systems. You can use a simple way like Dubbo to &ldquo;transparently&rdquo; call REST services provided by Non-Dubbo systems (regardless of whether the service provider is inside or outside the enterprise)</p> |
| </li> |
| </ol> |
| <p>It should be pointed out that I think that 1~3 are the most valuable application scenarios for Dubbo&rsquo;s REST call. And the main purpose why we add REST calls for Dubbo is to provide a service-oriented provider. In other words, to develop REST services for Non-Dubbo (heterogeneous) consumers.</p> |
| <p>To sum up, all application scenarios are shown below: |
| <img src="https://dubbo.apache.org/imgs/user/rest.jpg" alt="rest.jpg"></p> |
| <p>Borrowing the most famous slogan of Java in the past, by adding REST calls to Dubbo, you can implement the &ldquo;Write once, access everywhere&rdquo; service, which can theoretically be accessed all over the world, thus truly achieving an idealized Service-oriented Architecture (SOA).</p> |
| <p>Of course, traditional Web Services (WSDL/SOAP) can meet the requirements (even those that require enterprise-level features) of the above scenarios (except for scenario 4). But due to the complexity and other issues, they are less and less used.</p> |
| <h2 id="quick-start">Quick Start</h2> |
| <p>Developing a RESTful service in Dubbo is relatively straightforward. Let&rsquo;s take a simple user registration service for example.</p> |
| <p>The function to be implemented by this service is to provide the following URL (Note: This URL is not entirely RESTful, but more straightforward and more practical):</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>http://localhost:8080/users/register |
| </span></span></code></pre></div><p>Any client can POST a JSON string containing the user&rsquo;s information to the above URL to complete the user registration.</p> |
| <p>First, implement the interface of the service:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Then, implement the service:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>The above implementation code for the service is very simple, but since the REST service is to be published to a specific HTTP URL so they can be accessed by clients written by any language or even a browser, there are a few additional JAX-RS standard annotations to be added for the relevant configuration:</p> |
| <p>@Path(&ldquo;users&rdquo;): Specify that the relative path for <code>UserService</code> is <code>/users</code>, standing for http://localhost:8080/users</p> |
| <p>@Path(&ldquo;register&rdquo;): Specify that the relative path for <code>registerUser()</code> is <code>/register</code>. Combining the previous @Path specified for <code>UserService</code>, the URL to call <code>UserService.register()</code> is HTTP://localhost:8080/users/register</p> |
| <p>@POST: Specify that <code>registerUser()</code> should be accessed with HTTP POST method</p> |
| <p>@Consumes({MediaType.APPLICATION_JSON}): Specify that <code>registerUser()</code> receives data in JSON format. The REST framework will automatically deserialize JSON data into a User object.</p> |
| <p>Finally, add this service to the spring configuration file and finish all service development work:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- Exposure service on port 8080 with rest protocol --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;Dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- Declare the service interface that needs to be exposed --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;Dubbo:service</span> interface=<span style="color:#2aa198">&#34;xxx.UserService&#34;</span> ref=<span style="color:#2aa198">&#34;userService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- Implement the service like the local bean --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;userService&#34;</span> class=<span style="color:#2aa198">&#34;xxx.UserServiceImpl&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h2 id="introduction-to-standard-java-rest-api-jax-rs">Introduction to Standard Java REST API: JAX-RS</h2> |
| <p>JAX-RS is a standard Java REST API that has been widely supported and applied in the industry. There are many well-known open source implementations, including Oracle&rsquo;s Jersey, RedHat&rsquo;s RestEasy, Apache&rsquo;s CXF and Wink, restlet, etc. In addition, all commercial JavaEE application servers that support the JavaEE 6.0 specifications or above support JAX-RS. Therefore, JAX-RS is a very mature solution, and it does not have any so-called vendor lock-in problems.</p> |
| <p>JAX-RS has a wealth of information on the web, such as the following introductory tutorial:</p> |
| <ul> |
| <li>Oracle official tutorial: <a href="https://www.oracle.com/technical-resources/articles/java/jax-rs.html">https://www.oracle.com/technical-resources/articles/java/jax-rs.html</a></li> |
| <li>Article on IBM developerWorks China: <a href="http://www.ibm.com/developerworks/cn/java/j-lo-jaxrs/">http://www.ibm.com/developerworks/cn/java/j-lo-jaxrs/</a></li> |
| </ul> |
| <p>For more information, please feel free to Google or Baidu. As far as learning JAX-RS is concerned, it is generally enough to master the usage of various annotations.</p> |
| <blockquote> |
| <p>Note: Dubbo is based on the JAX-RS 2.0, and sometimes you need to pay attention to the version of the reference material or REST implementation.</p> |
| </blockquote> |
| <h2 id="rest-service-provider-details">REST Service Provider Details</h2> |
| <p>In this section, we will expand the <code>UserService</code> in the &ldquo;Quick Start&rdquo; to further demonstrate the development points of the REST service provider in Dubbo.</p> |
| <h3 id="implementation-of-http-postget">Implementation of HTTP POST/GET</h3> |
| <p>Although it&rsquo;s recommended to use the four standard methods (POST, DELETE, PUT and GET) in the HTTP protocol to implement common CRUD in REST services, but in practice, we generally use POST to implement create and update, and use GET to implement delete and read (DELETE and PUT will even be blocked by some firewalls).</p> |
| <p>The implementation of POST has already been briefly demonstrated. Here, we will add a function to get the registered user data to <code>UserService</code>, in order to demonstrate the implementation of GET.</p> |
| <p>This function is to enable the client to obtain user data of different IDs by accessing different URLs as follows:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>http://localhost:8080/users/1001 |
| </span></span><span style="display:flex;"><span>http://localhost:8080/users/1002 |
| </span></span><span style="display:flex;"><span>http://localhost:8080/users/1003 |
| </span></span></code></pre></div><p>Of course, you can use other forms of URLs to access user data of different IDs, for example:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-gdscript3" data-lang="gdscript3"><span style="display:flex;"><span>http:<span style="color:#719e07">//</span>localhost:<span style="color:#2aa198">8080</span><span style="color:#719e07">/</span>users<span style="color:#719e07">/</span><span style="color:#b58900">load</span>?id<span style="color:#719e07">=</span><span style="color:#2aa198">1001</span> |
| </span></span></code></pre></div><p>JAX-RS itself can support all of these forms. However, the first form of including query parameters in the URL path (http://localhost:8080/users/1001) is more in line with the general habit of REST, so it is recommended to use. Below we will add a <code>getUser()</code> method to the <code>UserService</code> to implement this form of URL access:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>@GET: Specify that the method shoule be accessed with HTTP GET method</p> |
| <p>@Path(&quot;{id : \d+}&quot;): According to the above functional requirements, the URL to access <code>getUser()</code> should be &ldquo;http://localhost:8080/users/ + any number&rdquo;, and this number should passed to <code>getUser()</code> method as parameter passed to the getUser() method. In the annotation here, the {id: xxx} in @Path specifies that the relative path contains the id parameter, and its value will be automatically passed to the method parameter <code>id</code> annotated with @PathParam(&ldquo;id&rdquo;). <code>\d+</code> following <code>{id:</code> is a regular expression specifies that the id parameter must be a number.</p> |
| <p>@Produces({MediaType.APPLICATION_JSON}): Specify that <code>getUser()</code> outputs data in JSON format. The REST framework automatically serializes the User object into JSON data.</p> |
| <h3 id="is-annotation-put-in-interface-class-or-implementation-class">Is annotation put in interface class or implementation class?</h3> |
| <p>The development of REST services based on Dubbo is mainly configured through JAX-RS annotations. In the above example, we put the annotation in the implementation class of the service. But in fact, we can completely put the annotation in the interface of the service. These two methods are completely equivalent, for example:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In a typical application, we recommend put the annotation in the service implementation class. Then, annotations are closer to Java implementation code and easier to develop and maintain. More importantly, we generally tend to avoid contamination of the interface, maintaining the purity and wide applicability of the interface.</p> |
| <p>However, as will be described later, if we access this service by using the consumer directly developed by Dubbo, the annotation must be put in the interface.</p> |
| <p>If the interface and the implementation class are both added annotation at the same time, the implementation configuration of the implementation class will take effect, and the annotation on the interface will be ignored.</p> |
| <h3 id="support-for-json-xml-and-other-data-formats">Support for JSON, XML and other data formats</h3> |
| <p>The dubbo REST services can support the transmission of data in multiple formats to provide maximum flexibility to the client. And we add extra functions to the JSON and XML formats which is most commonly used.</p> |
| <p>For example, we want the <code>getUser()</code> method in the above example support returning JSON and XML format data separately, just need to include two formats in the annotation:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>Or you can directly represent a MediaType with a string (also supports wildcards):</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({<span style="color:#2aa198">&#34;application/json&#34;</span>, <span style="color:#2aa198">&#34;text/xml&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>If all methods support the same type of input and output data format, then we do not need to make configure on each method, just add annotation to the service class:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In the case where a REST service supports multiple data formats, according to the JAX-RS standard, the MIME header (content-type and accept) in HTTP is generally used to specify which format data is currently used.</p> |
| <p>But in dubbo, we also automatically support the current common use of the industry, that is, use a URL suffix (.json and .xml) to specify the data format you want to use. For example, after adding the above annotation, directly accessing <code>http://localhost:8888/users/1001.json</code> means using the json format, and directly accessing <code>http://localhost:8888/users/1002.xml</code> means using the xml format. It&rsquo;s simpler and more intuitive than using HTTP Header. This way is used by the REST APIs of Twitter, Weibo, etc.</p> |
| <p>If you don&rsquo;t add HTTP header or suffix, the REST of dubbo will give priority to enable the top ranked data format in the above definition of annotation.</p> |
| <blockquote> |
| <p>Note: To support XML format data, you can use either <code>MediaType.TEXT_XML</code> or <code>MediaType.APPLICATION_XML</code> in annotation, but TEXT_XML is more commonly used, and if you want to use the above URL suffix to specify the data format, you can only configure it as TEXT_XML to take effect.</p> |
| </blockquote> |
| <h3 id="chinese-character-support">Chinese character support</h3> |
| <p>In order to output Chinese characters normally in dubbo REST, as with the usual Java web applications, we need to set the contentType of the HTTP response to UTF-8 encoding.</p> |
| <p>Based on the standard usage of JAX-RS, we only need to do the following annotation configuration:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({<span style="color:#2aa198">&#34;application/json; charset=UTF-8&#34;</span>, <span style="color:#2aa198">&#34;text/xml; charset=UTF-8&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>For the convenience of users, we add a support class directly in dubbo REST to define the above constants, which can be used directly and reduce the possibility of error.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><h3 id="additional-requirements-for-xml-data-format">Additional requirements for XML data format</h3> |
| <p>Because the implementation of JAX-RS generally use standard JAXB (Java API for XML Binding) to serialize and deserialize XML format data, we need to add a class-level JAXB annotation for each object to be transferred in XML. Otherwise serialization will report an error. For example, add follows to the User returned in <code>getUser()</code> :</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In addition, if the return value in the service method is Java primitive type (such as int, long, float, double, etc.), it is best to add a wrapper object to them, because JAXB can not directly serialize the primitive type.</p> |
| <p>For example, we want the above <code>registerUser()</code> method to return the ID number generated by the server for the user:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#dc322f">long</span> <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span></code></pre></div><p>Because the primitive type is not supported by JAXB serialization, add a wrapper object:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">RegistrationResult</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> Long id; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">RegistrationResult</span>() { |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">RegistrationResult</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Long <span style="color:#268bd2">getId</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">setId</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>And modify the service method:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span>RegistrationResult <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span></code></pre></div><p>This not only solves the problem of XML serialization, but also makes the returned data conform to the specifications of XML and JSON. For example, in JSON, the returned form would be as follows:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-javascript" data-lang="javascript"><span style="display:flex;"><span>{<span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">:</span> <span style="color:#2aa198">1001</span>} |
| </span></span></code></pre></div><p>If you do not add a wrapper, the JSON return value will be directly</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>1001 |
| </span></span></code></pre></div><p>In XML, the return value after adding wrapper will be:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;registrationResult&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;id&gt;</span>1002<span style="color:#268bd2">&lt;/id&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/registrationResult&gt;</span> |
| </span></span></code></pre></div><p>This wrapper object actually uses the so-called Data Transfer Object (DTO) mode, and DTO can also make more useful customizations for transferring data. |
| While in XML, after adding wrapper, the return value will be</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;registrationResult&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;id&gt;</span>1002<span style="color:#268bd2">&lt;/id&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/registrationResult&gt;</span> |
| </span></span></code></pre></div><p>In fact, this wrapper object uses the so-called Data Transfer Object (DTO) mode. DTO can also be used to make more useful customizations to transfer data.</p> |
| <h3 id="custom-serialization">Custom Serialization</h3> |
| <p>As mentioned above, the underlying implementation of REST will automatically serialize/deserialize between the service object and the JSON/XML data format.</p> |
| <p>The REST implementation in Dubbo uses JAXB for XML serialization and Jackson for JSON serialization,so you can customize the mapping by adding JAXB or Jackson&rsquo;s annotation to the object.</p> |
| <p>For example, customizing the object properties to map to the names of the XML elements:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@XmlAccessorType</span>(XmlAccessType.FIELD) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@XmlElement</span>(name<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Customizing the object properties to map to the names of the JSON field:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@JsonProperty</span>(<span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>For more information, please refer to the official documentation of JAXB and Jackson, or google yourself.</p> |
| <h3 id="configuring-rest-server-implementation">Configuring REST Server implementation</h3> |
| <p>Currently in dubbo, we support the implementation of five embedded rest servers. The implementation of the rest server is selected by the following XML attribute of the server:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses the embedded jetty to do the rest server. At the same time, if you do not configure the server attribute, the rest protocol also uses jetty by default. jetty is a very mature java servlet container and has a good integration with dubbob (Among the five embedded servers, Only jetty and later tomcat、tjws, complete seamless integration with Dubbo monitoring system.), so, if your dubbo system is a separate process, you can use jetty by default.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;tomcat&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses the embedded tomcat to do the rest server.On embedded tomcat, REST performance is much better than jetty (See the benchmark below). It is recommended that Tomcat is used in scenarios where high performance is required.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;netty&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses embedded netty to do the rest server. (TODO more contents to add)</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;tjws&#34;</span><span style="color:#268bd2">/&gt;</span> (tjws is now deprecated) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;sunhttp&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses embedded tjws or Sun HTTP server to do the rest server. These two server implementations are very lightweight, it is very convenient for quick start-up in integration testing, of course, it can also be used in a production environment with low load. Note: tjws is currently deprecated because it does not work well with the servlet 3.1 API.</p> |
| <p>If your dubbo system is not a separate process, |
| instead of deploying to a Java application server, we recommend the following configuration:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;servlet&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>By setting the server as the servlet, dubbo will use the servlet container of the external application server to do the rest server. At the same time, add the following configuration to the web.xml of the dubbo system:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;web-app&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;context-param&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;param-name&gt;</span>contextConfigLocation<span style="color:#268bd2">&lt;/param-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;param-value&gt;</span>/WEB-INF/classes/META-INF/spring/dubbo-demo-provider.xml<span style="color:#268bd2">&lt;/param-value&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/context-param&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener-class&gt;</span>org.apache.dubbo.remoting.http.servlet.BootstrapListener<span style="color:#268bd2">&lt;/listener-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/listener&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener-class&gt;</span>org.springframework.web.context.ContextLoaderListener<span style="color:#268bd2">&lt;/listener-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/listener&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-class&gt;</span>org.apache.dubbo.remoting.http.servlet.DispatcherServlet<span style="color:#268bd2">&lt;/servlet-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;load-on-startup&gt;</span>1<span style="color:#268bd2">&lt;/load-on-startup&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/web-app&gt;</span> |
| </span></span></code></pre></div><p>In other words, you must add dubbo&rsquo;s BootstrapListener and DispatherServlet to web.xml to complete the integration of dubbo&rsquo;s REST functionality with the external servlet container.</p> |
| <blockquote> |
| <p>Note:If you are using spring&rsquo;s ContextLoaderListener to load spring, you must ensure that the BootstrapListener is configured before the ContextLoaderListener, otherwise the dubbo initialization will fail.</p> |
| </blockquote> |
| <p>In fact, you can still stick to the embedded server in this scenario, but the servlet container of the external application server is often more powerful than the embedded server(Especially if you are deploying to a more robust and scalable WebLogic, WebSphere, etc.). In addition, it is sometimes convenient to do unified management, monitoring, and so on in the application server.</p> |
| <h3 id="get-context-information">Get Context Information</h3> |
| <p>Varieties of context information are valuable when calling procedures remotely. For instance, the IP address from the Client.</p> |
| <p>We provide two methods to get the Client&rsquo;s IP in dubbo.</p> |
| <p>The first one is using @Context annotation from JAX-RS:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id, <span style="color:#268bd2">@Context</span> HttpServletRequest request) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> request.getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>After decorating a parameter of <code>getUser()</code> with Context, we can inject the current HttpServletRequest and then call the servlet api to get the IP.</p> |
| <blockquote> |
| <p>Notice: This method can only be used when the server is one of the followings: twjs, tomecat, jetty or servlet. All of them provide servlet container. In addition, standard JAX-RS also allow us to get HttpServletRequest using an instance field in service Class decorated by <code>@Context</code>.</p> |
| </blockquote> |
| <p>The second method is to use RpcContext, which is commonly seen in dubbo:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRemoteAddressString()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>Notice: Similarly, this method only works in the jetty, tomcat, servlet or tjws server. In dubbo, the usage of RpcContext is rather invasive. We are likely to refactor it in the future.</p> |
| </blockquote> |
| <p>The first method is suggested when your project may run without dubbo and need the compatibility with JAX-RS. But if you want a more elegant service interface definition, the second method would be the better choice.</p> |
| <p>What&rsquo;s more, in the newest version of dubbo REST service, RpcContext could be used to get HttpServletRequest and HttpServletResponse, providing great flexibility for users to implement some complex functions. The following is an example:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getRequest() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getRequest() <span style="color:#719e07">instanceof</span> HttpServletRequest) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> ((HttpServletRequest) RpcContext.getContext().getRequest()).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getResponse() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getResponse() <span style="color:#719e07">instanceof</span> HttpServletResponse) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>Notice: |
| In order to maintain the neutrality of the protocol, <code>RpcContext.getRequest()</code> and <code>RpcContext.getResponse()</code> only return an Object which could be null. Therefore, you have to check the type on your own.</p> |
| </blockquote> |
| <blockquote> |
| <p>Notice: only when you use jetty, tomcat, servlet as the server can you get the HttpServletRequest and HttpServletResponse as expected. Because only these server |
| implemented the servlet container.</p> |
| </blockquote> |
| <p>To simplify the programme, you can also use generic to get a specific type of request/response:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getRequest(HttpServletRequest.class) <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRequest(HttpServletRequest.class).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getResponse(HttpServletResponse.class) <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse(HttpServletResponse.class)); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>If request/response does not correspond to the specific type, it would return null.</p> |
| <h3 id="configure-the-port-number-and-context-path">Configure The Port Number and Context Path</h3> |
| <p>The REST protocol in dubbo use 80 as the default port. But you are also allowed to modify it:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>As what have been metioned before, we can use <code>@Path</code> to configure relative URL path in single REST service. In fact, we can also set a basic relative path which is known as context path for all REST service.</p> |
| <p>All we need to do is to add the contextpath property:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> contextpath=<span style="color:#2aa198">&#34;services&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Let&rsquo;s have a look at the previous code:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Now the complete path would be:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>http://localhost:8888/services/users/register |
| </span></span></code></pre></div><p>Notice: If you use external server as REST server, you should configure as followings,</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> contextpath=<span style="color:#2aa198">&#34;services&#34;</span> server=<span style="color:#2aa198">&#34;servlet&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>meaning that you should keep the config of port and contextpath are the same with the port and DispatcherServlet&rsquo;s context path (webapp path + servlet url pattern) in external server. For example, when we are configuring the application on tomcat Root path, we need to make sure the contextpath here is totally the same with the <code>&lt;url-pattern/&gt;</code> of DispacherServlet in web.xml:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/services/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-the-number-of-threads-and-io-threads">Configure the number of threads and IO threads</h3> |
| <p>We can set the number of threads of rest service:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> threads=<span style="color:#2aa198">&#34;500&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Notice: Currently, the setting only works when the server is netty, jetty or tomcat. If you use servlet as the server, you are using the external server as the REST server which is out of dubboes&rsquo; control, so the setting would not work expectedly.</p> |
| </blockquote> |
| <p>You can also set threads number of IO worker of netty server:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> iothreads=<span style="color:#2aa198">&#34;5&#34;</span> threads=<span style="color:#2aa198">&#34;100&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-long-connections">Configure long connections</h3> |
| <p>The REST service in Dubbo is accessed by default with http long connection, if you want to switch to short connection, you can configure it as below:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> keepalive=<span style="color:#2aa198">&#34;false&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Notice: This configuration only works in netty and tomcat.</p> |
| </blockquote> |
| <h3 id="configure-the-maximum-number-of-http-connections">Configure the maximum number of HTTP connections</h3> |
| <p>Configuring the maximum number of HTTP connections can prevent REST server from |
| overload as the basic self-protection mechanism.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> accepts=<span style="color:#2aa198">&#34;500&#34;</span> server=<span style="color:#2aa198">&#34;tomcat/</span><span style="color:#268bd2">&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Notice: Currently, it only works in tomcat.</p> |
| </blockquote> |
| <h3 id="configuring-the-timeout-and-http-connections-for-each-consumer">Configuring the timeout and HTTP connections for each consumer</h3> |
| <p>If the consumer of the rest service is also a dubbo system, you can configure the maximum timeout for the consumer to call the rest service, and the maximum number of HTTP connections that each consumer can initiate, just like other dubbo RPC mechanisms.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;xxx&#34;</span> ref=<span style="color:#2aa198">&#34;xxx&#34;</span> protocol=<span style="color:#2aa198">&#34;rest&#34;</span> timeout=<span style="color:#2aa198">&#34;2000&#34;</span> connections=<span style="color:#2aa198">&#34;10&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Of course, since this configuration is valid for the consumer, it can also be configured on the consumer side:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;xxx&#34;</span> interface=<span style="color:#2aa198">&#34;xxx&#34;</span> timeout=<span style="color:#2aa198">&#34;2000&#34;</span> connections=<span style="color:#2aa198">&#34;10&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>However, we generally recommend configuring the service provider to provide such a configuration. According to the official dubbo documentation, “Provider should configure the properties of the Consumer side as much as possible. |
| Let the Provider implementer think about the service features and service quality of the Provider from the beginning.”</p> |
| <blockquote> |
| <p>Note: If dubbo REST service is released to non-dubbo clients, the configuration on <code>&lt;dubbo:service/&gt;</code> is completely invalid because the client is not under dubbo control.</p> |
| </blockquote> |
| <h3 id="gzip-data-compresssion">GZIP data compresssion</h3> |
| <p>Dubbo RESTful Remoting supports the use of Gzip to compress request and response data to reduce network transmission time and bandwidth consumption, but this will also increase CPU overhead.</p> |
| <p>TODO more contents to add.</p> |
| <h3 id="replacing-part-of-the-spring-xml-configuration-with-annotation">Replacing part of the spring XML configuration with annotation</h3> |
| <p>Above discussions are based on the XML configuration of Dubbo in spring. |
| However, dubbo/spring itself supports the use of annotation for configuration, so we can also follow the steps in the Dubbo document and add the relevant annotation to the REST service implementation, replacing some XML configurations, such as:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Service</span>(protocol <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;rest&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Autowired</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> UserRepository userRepository; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user</span> |
| </span></span><span style="display:flex;"><span> userRepository.save(user); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Annotation-based configuration is more concise and precise, and often easier to maintain (modern IDE can support such things as class name refactoring in XML, and therefore the maintenance of XML is good for specific use cases here). XML is less intrusive to code, especially for dynamically modifying configurations, especially when you want to modify the timeout for connection of a single service configuration, the maximum number of connections per client, cluster policy, weights, and so on. In addition, for complex applications or modules, XML provides a central point to cover all the components and configurations. It is at a glance, and generally more convenient for long term maintenance of the project.</p> |
| <p>Of course, there&rsquo;s no right or wrong of different choices of configuration method. Sometimes it&rsquo;s just personal preference.</p> |
| <h3 id="adding-a-custom-filter-interceptor-etc">Adding a custom Filter, Interceptor, etc</h3> |
| <p>Dubbo RESTful Remoting also supports JAX-RS standard Filter and Interceptor to facilitate customized interception of REST request and response processes.</p> |
| <p>Here, Filter is mainly used to access and set parameters, URIs for HTTP request and response, and so on, for example, setting the cache header for HTTP response:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">CacheControlFilter</span> <span style="color:#268bd2">implements</span> ContainerResponseFilter { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">filter</span>(ContainerRequestContext req, ContainerResponseContext res) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> (req.getMethod().equals(<span style="color:#2aa198">&#34;GET&#34;</span>)) { |
| </span></span><span style="display:flex;"><span> res.getHeaders().add(<span style="color:#2aa198">&#34;Cache-Control&#34;</span>, <span style="color:#2aa198">&#34;someValue&#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Interceptor is mainly used to access and modify the input and output byte streams, for example, manually adding GZIP compression:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">GZIPWriterInterceptor</span> <span style="color:#268bd2">implements</span> WriterInterceptor { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Override</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">aroundWriteTo</span>(WriterInterceptorContext context) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">throws</span> IOException, WebApplicationException { |
| </span></span><span style="display:flex;"><span> OutputStream outputStream <span style="color:#719e07">=</span> context.getOutputStream(); |
| </span></span><span style="display:flex;"><span> context.setOutputStream(<span style="color:#719e07">new</span> GZIPOutputStream(outputStream)); |
| </span></span><span style="display:flex;"><span> context.proceed(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In standard JAX-RS applications, we generally add @Provider annotations to Filter and Interceptor, and JAX-RS runtime will automatically discover and enable them. In Dubbo, we register Filter and Interceptor by adding an XML configuration:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.TraceInterceptor, xxx.TraceFilter&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Here, we can add these three types of objects, Filter, Interceptor and DynamicFeature, to the <code>extension</code> attributes, separated by commas. (DynamicFeature is another interface that allows us to enable Filter and Interceptor more dynamically. Please feel free to google.)</p> |
| <p>Of course, Dubbo itself also supports Filter, but the Filter and Interceptor we discuss here are more like the bottom of the protocol implementation. Compared to Dubbo&rsquo;s filter, you can do a lower level of customization here.</p> |
| <blockquote> |
| <p>Note: The XML attribute here is called extension, not interceptor or filter. That is because we will add more extension types in addition to Interceptor and Filter in the future.</p> |
| </blockquote> |
| <p>If the REST consumer is also a Dubbo system (see discussion below), you can also configure the Interceptor and Filter for the consumer in a similar way.</p> |
| <p>However, it should be noted that the consumer-side Filter and the provider-side Filter in JAX-RS are two different interfaces. For example, in the previous example, the server is the ContainerResponseFilter interface, and the consumer side corresponds to the ClientResponseFilter:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">LoggingFilter</span> <span style="color:#268bd2">implements</span> ClientResponseFilter { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">filter</span>(ClientRequestContext reqCtx, ClientResponseContext resCtx) <span style="color:#268bd2">throws</span> IOException { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;status: &#34;</span> <span style="color:#719e07">+</span> resCtx.getStatus()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;date: &#34;</span> <span style="color:#719e07">+</span> resCtx.getDate()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;last-modified: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLastModified()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;location: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLocation()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;headers:&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (Entry<span style="color:#719e07">&lt;</span>String, List<span style="color:#719e07">&lt;</span>String<span style="color:#719e07">&gt;&gt;</span> header : resCtx.getHeaders().entrySet()) { |
| </span></span><span style="display:flex;"><span> System.out.print(<span style="color:#2aa198">&#34;\t&#34;</span> <span style="color:#719e07">+</span> header.getKey() <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34; :&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (String value : header.getValue()) { |
| </span></span><span style="display:flex;"><span> System.out.print(value <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34;, &#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> System.out.print(<span style="color:#2aa198">&#34;\n&#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;media-type: &#34;</span> <span style="color:#719e07">+</span> resCtx.getMediaType().getType()); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="adding-custom-exception-handler">Adding custom Exception handler</h3> |
| <p>Dubbo RESTful Remoting also supports JAX-RS standard ExceptionMapper, which can be used to customize the HTTP response after a particular exception occurs.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">CustomExceptionMapper</span> <span style="color:#268bd2">implements</span> ExceptionMapper<span style="color:#719e07">&lt;</span>NotFoundException<span style="color:#719e07">&gt;</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Response <span style="color:#268bd2">toResponse</span>(NotFoundException e) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.NOT_FOUND).entity(<span style="color:#2aa198">&#34;Oops! the requested resource is not found!&#34;</span>).type(<span style="color:#2aa198">&#34;text/plain&#34;</span>).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Similar to Interceptor and Filter, it can be enabled by adding it to an XML configuration file:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.CustomExceptiionMapper&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configuring-http-log-output">Configuring HTTP log output</h3> |
| <p>Dubbo RESTful Remoting supports outputting the header and body in all HTTP requests/responses.</p> |
| <p>Add the following REST filter to the XML configuration:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;org.apache.dubbo.rpc.protocol.rest.support.LoggingFilter&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><strong>Then turn on at least INFO level log output for org.apache.dubbo.rpc.protocol.rest.support in the logging configuration</strong>,for example,in log4j.xml:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;logger</span> name=<span style="color:#2aa198">&#34;org.apache.dubbo.rpc.protocol.rest.support&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;level</span> value=<span style="color:#2aa198">&#34;INFO&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;appender-ref</span> ref=<span style="color:#2aa198">&#34;CONSOLE&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/logger&gt;</span> |
| </span></span></code></pre></div><p>Of course, you can also turn on INFO level log output directly in the ROOT logger:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;root&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;level</span> value=<span style="color:#2aa198">&#34;INFO&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;appender-ref</span> ref=<span style="color:#2aa198">&#34;CONSOLE&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/root&gt;</span> |
| </span></span></code></pre></div><p>Then there will be something like the following output in the log:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>The HTTP headers are: |
| </span></span><span style="display:flex;"><span>accept: application/json;charset=UTF-8 |
| </span></span><span style="display:flex;"><span>accept-encoding: gzip, deflate |
| </span></span><span style="display:flex;"><span>connection: Keep-Alive |
| </span></span><span style="display:flex;"><span>content-length: 22 |
| </span></span><span style="display:flex;"><span>content-type: application/json |
| </span></span><span style="display:flex;"><span>host: 192.168.1.100:8888 |
| </span></span><span style="display:flex;"><span>user-agent: Apache-HttpClient/4.2.1 (java 1.5) |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>The contents of request body is: |
| </span></span><span style="display:flex;"><span>{&#34;id&#34;:1,&#34;name&#34;:&#34;dang&#34;} |
| </span></span></code></pre></div><p>After the HTTP log output is turned on, in addition to the performance overhead of the normal log output, additional overhead is generated in, for example, HTTP request parsing, because an additional memory buffer needs to be allocated to prepare the data for the log output.</p> |
| <h3 id="inputing-parameter-validation">Inputing parameter validation</h3> |
| <p>Dubbo RESTful Remoting supports the use of the Java standard bean validation annotation(JSR 303) for input validation <a href="http://beanvalidation.org/">http://beanvalidation.org/</a>.</p> |
| <p>In order to be consistent with other Dubbo remote invocation protocols, the annotations that are checked for rest must be placed on the interface of the service, for example:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@Min</span>(value<span style="color:#719e07">=</span>1L, message<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;User ID must be greater than 1&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Of course, in many other bean validation scenarios, annotations are placed on implementation classes rather than interfaces. At least one advantage of placing an annotation on an interface is that the Dubbo client can share information about the interface. The input validation can be done locally even without RPC.</p> |
| <p>Then turn on the validation in the XML configuration in the same way as Dubbo:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">xxx.UserService&#34;</span> ref=<span style="color:#2aa198">&#34;userService&#34;</span> protocol=<span style="color:#2aa198">&#34;rest&#34;</span> validation=<span style="color:#2aa198">&#34;true&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>In many other RPC protocols of Dubbo, if the input validation error occurs, the <code>RpcException</code> is directly thrown to the client, but in the rest, since the client is often non-Dubbo or even non-Java system, it is inconvenient to directly throw a Java exception. Therefore, at present we will return the validation error in XML format:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;violationReport&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;constraintViolations&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;path&gt;</span>getUserArgument0<span style="color:#268bd2">&lt;/path&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;message&gt;</span>User ID must be greater than 1<span style="color:#268bd2">&lt;/message&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;value&gt;</span>0<span style="color:#268bd2">&lt;/value&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/constraintViolations&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/violationReport&gt;</span> |
| </span></span></code></pre></div><p>The return values of other data formats will also be supported later. As for how to internationalize the verification error message, refer directly to the relevant documentation of the bean validation.</p> |
| <p>If you think that the default validation error return format does not meet your requirements, you can add custom ExceptionMapper to custom error return format freely as described in the previous section. It should be noted that this ExceptionMapper must use the generic declaration to capture the RpcException of Dubbo in order to successfully override the default exception handling strategy of Dubbo rest. In order to simplify the operation, the easiest way to do this is to directly inherit the RpcExceptionMapper of Dubbo rest and override the method that handles the validation exception:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">MyValidationExceptionMapper</span> <span style="color:#268bd2">extends</span> RpcExceptionMapper { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">protected</span> Response <span style="color:#268bd2">handleConstraintViolationException</span>(ConstraintViolationException cve) { |
| </span></span><span style="display:flex;"><span> ViolationReport report <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ViolationReport(); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (ConstraintViolation cv : cve.getConstraintViolations()) { |
| </span></span><span style="display:flex;"><span> report.addConstraintViolation(<span style="color:#719e07">new</span> RestConstraintViolation( |
| </span></span><span style="display:flex;"><span> cv.getPropertyPath().toString(), |
| </span></span><span style="display:flex;"><span> cv.getMessage(), |
| </span></span><span style="display:flex;"><span> cv.getInvalidValue() <span style="color:#719e07">==</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">?</span> <span style="color:#2aa198">&#34;null&#34;</span> : cv.getInvalidValue().toString())); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// Use json output instead of xml output</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Then add this ExceptionMapper to the XML configuration:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.MyValidationExceptionMapper&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="whether-to-transparently-publish-rest-service">Whether to transparently publish REST service</h3> |
| <p>Dubbo RESTful Remoting differs from some other RPCs in Dubbo in that you need to add JAX-RS annotations (and JAXB, Jackson&rsquo;s annotation) to your service code. If you think these annotations &ldquo;pollute&rdquo; your service code to a certain extent,you can consider writing additional Facade and DTO classes, adding annotations to that, and Facade forwards the calls to the real service implementation class. Of course, adding annotations directly to the service code basically has no negative effects, and this is itself a standard usage in Java EE. In addition, JAX-RS and JAXB annotations belong to the Java standard. Compared with spring, Dubbo, etc., which we often use, annotations have no problem with vendor lock-in, so there is usually no need to introduce additional objects.</p> |
| <p>In addition,when you want to use the @Context annotation mentioned above, injecting HttpServletRequest through method parameters (such as <code>public User getUser(@PathParam(&quot;id&quot;) Long id, @Context HttpServletRequest request)</code>), the method signature of service is changed and HttpServletRequest is a REST-specific parameter, you should introduce additional Facade classes if your service supports multiple RPC mechanisms.</p> |
| <p>Of course, your service code may already act as a Facade and DTO before adding RESTful Remoting (as to why some scenarios require these roles, and if you are interested, you can refer to [Micro-SOA: Service Design Principles and Practices] Http://www.infoq.com/cn/articles/micro-soa-1). In this case, after adding REST, if you add additional REST-related Facade and DTO, it is equivalent to wrapping the original code again, which forms the following call chain:</p> |
| <p><code>RestFacade/RestDTO -&gt; Facade/DTO -&gt; Service</code></p> |
| <p>This kind of system is cumbersome, and the workload of data conversion is not small, so it should be avoided if possible.</p> |
| <h3 id="get-headers-in-dubbo-rest-provider">Get Headers In Dubbo Rest Provider</h3> |
| <p>Dubbo take out and split headers by RpcContextFilter and put them into attachments of RpcContext, so provider can get headers from RpcContext attachments like:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span> String header-value1 = RpcContext.getContext().getAttachment(header-key1) |
| </span></span><span style="display:flex;"><span> String header-value2 = RpcContext.getContext().getAttachment(header-key2) |
| </span></span></code></pre></div><h3 id="consumer-of-restful-remoting">Consumer of RESTful Remoting</h3> |
| <p>Here we use three scenarios:</p> |
| <ol> |
| <li>The non-Dubbo consumer calls Dubbo REST service (non-Dubbo &ndash;&gt; Dubbo)</li> |
| <li>The Dubbo consumer calls Dubbo REST service (Dubbo &ndash;&gt; Dubbo)</li> |
| <li>The consumer of Dubbo calls the non-Dubbo REST service (Dubbo &ndash;&gt; non-Dubbo)</li> |
| </ol> |
| <h3 id="scenario-1-non-dubbo-consumer-calls-dubbo-rest-service">Scenario 1: Non-Dubbo consumer calls Dubbo REST Service</h3> |
| <p>The client of this scenario has nothing to do with Dubbo itself, and it can be directly selected in the appropriate language and framework.</p> |
| <p>If it is still a Java client (but not using Dubbo), consider using the standard JAX-RS Client API or a specific REST-implemented Client API to invoke the REST service. The following is the registerUser() that uses the JAX-RS Client API to access the above UserService:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span>User user <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> User(); |
| </span></span><span style="display:flex;"><span>user.setName(<span style="color:#2aa198">&#34;Larry&#34;</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>Client client <span style="color:#719e07">=</span> ClientBuilder.newClient(); |
| </span></span><span style="display:flex;"><span>WebTarget target <span style="color:#719e07">=</span> client.target(<span style="color:#2aa198">&#34;http://localhost:8080/services/users/register.json&#34;</span>); |
| </span></span><span style="display:flex;"><span>Response response <span style="color:#719e07">=</span> target.request().post(Entity.entity(user, MediaType.APPLICATION_JSON_TYPE)); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">try</span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> (response.getStatus() <span style="color:#719e07">!=</span> 200) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">throw</span> <span style="color:#719e07">new</span> RuntimeException(<span style="color:#2aa198">&#34;Failed with HTTP error code : &#34;</span> <span style="color:#719e07">+</span> response.getStatus()); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;The generated id is &#34;</span> <span style="color:#719e07">+</span> response.readEntity(RegistrationResult.class).getId()); |
| </span></span><span style="display:flex;"><span>} <span style="color:#719e07">finally</span> { |
| </span></span><span style="display:flex;"><span> response.close(); |
| </span></span><span style="display:flex;"><span> client.close(); <span style="color:#586e75">//Do not close the client every time in real development, such as HTTP long connection is held by the client</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>The User and RegistrationResult classes in the code snippet above are written by the consumer itself, and the JAX-RS Client API automatically serializes/deserializes them.</p> |
| <p>Of course, in Java, you can also use the familiar technologies such as HttpClient, FastJson, XStream, etc. to implement the REST client, which will not be detailed here.</p> |
| <h3 id="scenario-2-dubbo-consumer-calls-dubbo-restful-remoting">Scenario 2: Dubbo consumer calls Dubbo RESTful Remoting</h3> |
| <p>In this scenario, same as other Dubbo remote calling methods, the Java service interface is shared directly between the service provider and the service consumer, and the Spring XML configuration is added (of course, the Spring/Dubbo annotation configuration can also be used),the remote REST service can be called transparently:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;userService&#34;</span> interface=<span style="color:#2aa198">&#34;xxx.UserService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>As mentioned earlier, in this scenario, JAX-RS annotations must be added to the service interface, so that the corresponding REST configuration information can be shared on the consumer side of Dubbo and remotely called accordingly:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>If a variety of data formats are configured in the annotation of the service interface, since both ends are Dubbo systems, a lot of details of REST are blocked, so there is no possibility to select a data format using the aforementioned URL suffix. Currently in this case, the top ranked data format will be used directly.</p> |
| <p>Therefore, we recommend that you put the most appropriate data format in front of defining an annotation. For example, we put JSON in front of XML because JSON&rsquo;s transmission performance is better than XML.</p> |
| <h3 id="scenario-3-the-consumer-of-dubbo-calls-a-non-dubbo-restful-remoting">Scenario 3: The consumer of Dubbo calls a non-Dubbo RESTful Remoting</h3> |
| <p>In this scenario, the REST service can be called directly using the Java method described in Scenario 1. But in fact, you can also use the way described in Scenario 2, that is, calling the REST service more transparently, even if this service is not provided by Dubbo.</p> |
| <p>If the scenario 2 is used, since the REST service is not provided by Dubbo, there is generally no shared Java service interface mentioned above, so we need to write the Java interface and the corresponding parameter class according to the external REST service. Add JAX-RS, JAXB, Jackson and other annotations, Dubbo&rsquo;s REST underlying implementation will automatically generate request messages, automatically parse response messages, etc., so as to transparently make remote calls. Or this way can also be understood as, we try to use JAX-RS to copy the implementation of the external REST service provider, and then put the written service interface to the client to use directly, Dubbo REST underlying implementation can call other REST services as it calls Dubbo&rsquo;s REST service .</p> |
| <p>For example, we want to call the following external service.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>http://api.foo.com/services/users/1001 |
| </span></span><span style="display:flex;"><span>http://api.foo.com/services/users/1002 |
| </span></span></code></pre></div><p>Get user data of different IDs, the return format is JSON</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span>{ |
| </span></span><span style="display:flex;"><span> <span style="color:#2aa198">&#34;id&#34;</span>: 1001, |
| </span></span><span style="display:flex;"><span> <span style="color:#2aa198">&#34;name&#34;</span>: <span style="color:#2aa198">&#34;Larry&#34;</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>We can write service interfaces and parameter classes based on this information:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> Long id; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// …</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>For the configuration in Spring, because the REST service is not provided by Dubbo, you can not use the Dubbo registry to directly configure the url address of the external REST service (such as multiple addresses separated by commas):</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;userService&#34;</span> interface=<span style="color:#2aa198">&#34;xxx.UserService&#34;</span> url=<span style="color:#2aa198">&#34;rest://api.foo.com/services/&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Note: The protocol here must use rest:// instead of http://. If the external REST service has a context path, it must also be added to the url (unless you have a context path in the @Path annotation for each service interface), such as /services/ above. At the same time, the services here must be followed by /, in order to make Dubbo work properly.</p> |
| <p>In addition, you can still configure the maximum number of connections and timeouts that the client can start:</p> |
| </blockquote> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;userService&#34;</span> interface=<span style="color:#2aa198">&#34;xxx.UserService&#34;</span> url=<span style="color:#2aa198">&#34;rest://api.foo.com/services/&#34;</span> timeout=<span style="color:#2aa198">&#34;2000&#34;</span> connections=<span style="color:#2aa198">&#34;10&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="custom-header-by-dubbo-consumer-while-calls-rest-service">Custom Header By Dubbo Consumer while Calls REST Service</h3> |
| <p>When Dubbo calls rest, it uses the method of converting the attachments of RpcContext to header.</p> |
| <p>Therefore, you can set headers in the following ways:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span> RpcContext.getContext().setAttachment(&#34;header-key1&#34;, &#34;header-value1&#34;); |
| </span></span><span style="display:flex;"><span> RpcContext.getContext().setAttachment(&#34;header-key2&#34;, &#34;header-value2&#34;); |
| </span></span></code></pre></div><p>Then the headers will be looks like following:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span> header-key1 = header-value1 |
| </span></span><span style="display:flex;"><span> header-key2 = header-value2 |
| </span></span></code></pre></div><h3 id="jax-rs-restrictions-in-dubbo">JAX-RS restrictions in Dubbo</h3> |
| <p>The REST development in Dubbo is fully compatible with standard JAX-RS, but the features it supports are currently a subset of full JAX-RS, in part because it is limited to the specific architecture of Dubbo and Spring. The limitations of JAX-RS used in Dubbo include but are not limited to:</p> |
| <ol> |
| <li>Service implementation can only be singleton, and it can not support per-request scope and per-lookup scope</li> |
| <li>It is not supported to inject into ServletConfig, ServletContext, HttpServletRequest, HttpServletResponse, etc. with the @Context annotation for the instance field of the service, but it can support the injection of service method parameters. However, for certain REST server implementations (see the previous section), injection of service method parameters is not supported.</li> |
| </ol> |
| <h2 id="rest-faq">REST FAQ</h2> |
| <hr> |
| <h3 id="can-dubbo-rest-services-be-integrated-with-dubbo-registry-and-monitor">Can Dubbo REST services be integrated with Dubbo Registry and Monitor?</h3> |
| <p>Yes, and it will integrate automatically. That is, all the REST services you develop in Dubbo are automatically registered to the Registry and Monitor, by which you can managed your services. |
| However, many of the service governance operations in the Registry can only be fully functional when the REST consumer is based on Dubbo. If the consumer side is non-Dubbo, it is naturally not managed by the Registry, so that many of the operations will not work for the consumer.</p> |
| <h3 id="how-to-implement-load-balancing-and-failover-in-dubbo-rest">How to implement load balancing and failover in Dubbo REST?</h3> |
| <p>If the consumer side of Dubbo REST is based on Dubbo, then Dubbo REST is basically the same as other Dubbo remote call protocols: Dubbo framework transparently performs load balancing, failover, etc. on the consumer side. |
| If the consumer side of Dubbo REST is non-Dubbo or even non-Java, it is better to configure the soft load balancing mechanism on the service provider. Currently, you can consider LVS, HAProxy, Nginx, and so on to achieve load balancing for HTTP requests.</p> |
| <h3 id="can-overloaded-method-in-jax-rs-maps-to-the-same-url-address">Can overloaded method in JAX-RS maps to the same URL address?</h3> |
| <p><a href="http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params">http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params</a></p> |
| <h3 id="can-a-post-method-in-jax-rs-receive-multiple-parameters">Can a POST method in JAX-RS receive multiple parameters?</h3> |
| <p><a href="http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects">http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects</a></p> |
| <h2 id="the-shortcomings-of-dubbos-current-system-related-to-rest">The shortcomings of Dubbo&rsquo;s current system (related to REST)</h2> |
| <hr> |
| <p>I think there are obviously a lot of deficiencies in Dubbo&rsquo;s current system. Here are a few REST-related issues that affect users (not including internal implementation issues) for reference and comments, which can help prepare for the refactoring later.</p> |
| <h3 id="invasiveness-of-rpccontext">Invasiveness of RpcContext</h3> |
| <p>We have already mentioned the intrusiveness of RpcContext(See above). Because it uses a singleton to access context information, which is completely inconsistent with the general style of spring applications as well as not conducive to application extension and unit testing. In the future, we may inject an interface with dependency injection, and then use it to access the context information in ThreadLocal.</p> |
| <h3 id="limitations-of-protocol-configuration">limitations of Protocol configuration</h3> |
| <p>Dubbo supports multiple remote call methods, but all call methods are configured with <a href="Dubbo:protocol/">Dubbo:protocol/</a>, for example:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;Dubbo:protocol</span> name=<span style="color:#2aa198">&#34;Dubbo&#34;</span> port=<span style="color:#2aa198">&#34;9090&#34;</span> server=<span style="color:#2aa198">&#34;netty&#34;</span> client=<span style="color:#2aa198">&#34;netty&#34;</span> codec=<span style="color:#2aa198">&#34;Dubbo&#34;</span> serialization=<span style="color:#2aa198">&#34;hessian2&#34;</span> |
| </span></span><span style="display:flex;"><span> charset=<span style="color:#2aa198">&#34;UTF-8&#34;</span> threadpool=<span style="color:#2aa198">&#34;fixed&#34;</span> threads=<span style="color:#2aa198">&#34;100&#34;</span> queues=<span style="color:#2aa198">&#34;0&#34;</span> iothreads=<span style="color:#2aa198">&#34;9&#34;</span> buffer=<span style="color:#2aa198">&#34;8192&#34;</span> accepts=<span style="color:#2aa198">&#34;1000&#34;</span> payload=<span style="color:#2aa198">&#34;8388608&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Dubbo supports multiple remote call methods, but all call methods are configured with <a href="Dubbo:protocol/">Dubbo:protocol/</a>, for example: |
| In fact, many of the above properties are uniquely held by the Dubbo RPC remote call method and many other remote call methods in Dubbo do not support server, client, codec, iothreads, accepts, payload, etc. (of course, some are not supported because of limited conditions, some have no need to be supported at all). This adds a lot of confusions to users when they use Dubbo, and they actually do not know that some attributes (such as performance tuning) will not work after adding them.</p> |
| <p>On the other hand, various remote call methods often have a large number of unique configuration requirements, especially as we gradually add much richer and more advanced functions to each kind of remote call method, which cause the expands in <protocol/> attributes inevitably (for example, we have added keepalive and extension two attributes in REST at the moment) and then lead to bloated <protocol/> and user confusion.</p> |
| <p>Of course, there is a way to expand <protocol/> in Dubbo by using <a href="Dubbo:parameter/">Dubbo:parameter/</a>, but this method is obviously very limited, the usage is complicated and the schema verification is lacking. |
| So that the best method is to set your own protocol elements for each remote call, such as <protocol-Dubbo/>, <protocol-rest/>, etc. Each element specifies its own attributes using XML Schema. (Of course, it is best to use common attributes between a variety of remote call methods) |
| In this way, a freer way can be used when doing the extension configuration mentioned above, so that it can be much clearer and more extensible (the following is just an example, of course there may be a better way):</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;Dubbo:protocol-rest</span> port=<span style="color:#2aa198">&#34;8080&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;Dubbo:extension&gt;</span>someInterceptor<span style="color:#268bd2">&lt;/Dubbo:extension&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;Dubbo:extension&gt;</span>someFilter<span style="color:#268bd2">&lt;/Dubbo:extension&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;Dubbo:extension&gt;</span>someDynamicFeature<span style="color:#268bd2">&lt;/Dubbo:extension&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;Dubbo:extension&gt;</span>someEntityProvider<span style="color:#268bd2">&lt;/Dubbo:extension&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/Dubbo:protocol-rest&gt;</span> |
| </span></span></code></pre></div><h3 id="xml-naming-does-not-conform-to-the-spring-specification">XML naming does not conform to the spring specification</h3> |
| <p>A lot of naming in XML configuration of Dubbo dose not conform to the spring specification, such as:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;Dubbo:protocol</span> name=<span style="color:#2aa198">&#34;Dubbo&#34;</span> port=<span style="color:#2aa198">&#34;9090&#34;</span> server=<span style="color:#2aa198">&#34;netty&#34;</span> client=<span style="color:#2aa198">&#34;netty&#34;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>codec=<span style="color:#2aa198">&#34;Dubbo&#34;</span> serialization=<span style="color:#2aa198">&#34;hessian2&#34;</span> |
| </span></span><span style="display:flex;"><span> charset=<span style="color:#2aa198">&#34;UTF-8&#34;</span> threadpool=<span style="color:#2aa198">&#34;fixed&#34;</span> threads=<span style="color:#2aa198">&#34;100&#34;</span> queues=<span style="color:#2aa198">&#34;0&#34;</span> iothreads=<span style="color:#2aa198">&#34;9&#34;</span> buffer=<span style="color:#2aa198">&#34;8192&#34;</span> accepts=<span style="color:#2aa198">&#34;1000&#34;</span> payload=<span style="color:#2aa198">&#34;8388608&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above threadpool should be changed to thread-pool, iothreads should be changed to io-threads, and words should be separated by &ldquo;-&rdquo;. While this may seem like a minor issue, it also involves readability, especially scalability, because sometimes we will inevitably use more words to describe XML elements and attributes.</p> |
| <p>In fact, Dubbo itself also recommended to follow the naming convention of spring to XML.</p> |
| <h2 id="best-practices-of-rest">Best practices of REST</h2> |
| <hr> |
| <p>TODO</p> |
| <h2 id="performance-benchmark">Performance benchmark</h2> |
| <hr> |
| <h3 id="test-environment">Test Environment</h3> |
| <p>Roughly as follows:</p> |
| <ul> |
| <li>4-core Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz</li> |
| <li>8G memory</li> |
| <li>The network between servers passes through a 100 Mbps switch</li> |
| <li>CentOS 5</li> |
| <li>JDK 7</li> |
| <li>Tomcat 7</li> |
| <li>JVM parameter -server -Xms1g -Xmx1g -XX:PermSize=64M -XX:+UseConcMarkSweepGC</li> |
| </ul> |
| <h3 id="test-script">Test Script</h3> |
| <p>Similar to Dubbo&rsquo;s own benchmarks: |
| 10 concurrent clients send requests continuously: |
| • Pass in nested complex objects (single data is small), do nothing and return |
| • Pass in a 50K string, do nothing and return (TODO: the result is not listed yet) |
| Excute a five-minute performance test. (Reference to Dubbo&rsquo;s own test considerations: &ldquo;Mainly consider the serialization and performance of network IO, so that the server side does not have any business logic. Take 10 to run simultaneously because of the consideration that the bottleneck can be hit first when the high CPU usage rate is reached by HTTP protocol under the high concurrency situation.&rdquo;)</p> |
| <h3 id="test-result">Test Result</h3> |
| <p>The following results are mainly from the comparison between to the two remote call methods, REST and Dubbo RPC which are configured differently, for example:</p> |
| <ul> |
| <li>“REST: Jetty + XML + GZIP” means: Test REST, use jetty server and XML data format, and enable GZIP compression.</li> |
| <li>“Dubbo: hessian2” means: test Dubbo RPC and use hessian2 serialization.</li> |
| </ul> |
| <p>The results for complex objects are as follows (the smaller Response Time and the larger TPS, the better results):</p> |
| <table> |
| <thead> |
| <tr> |
| <th>Remote Call Mode</th> |
| <th>Average Response Time</th> |
| <th>Average TPS（Num of transactions per second）</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>REST: Jetty + JSON</td> |
| <td>7.806</td> |
| <td>1280</td> |
| </tr> |
| <tr> |
| <td>REST: Jetty + JSON + GZIP</td> |
| <td>TODO</td> |
| <td>TODO</td> |
| </tr> |
| <tr> |
| <td>REST: Jetty + XML</td> |
| <td>TODO</td> |
| <td>TODO</td> |
| </tr> |
| <tr> |
| <td>REST: Jetty + XML + GZIP</td> |
| <td>TODO</td> |
| <td>TODO</td> |
| </tr> |
| <tr> |
| <td>REST: Tomcat + JSON</td> |
| <td>2.082</td> |
| <td>4796</td> |
| </tr> |
| <tr> |
| <td>REST: Netty + JSON</td> |
| <td>2.182</td> |
| <td>4576</td> |
| </tr> |
| <tr> |
| <td>Dubbo: FST</td> |
| <td>1.211</td> |
| <td>8244</td> |
| </tr> |
| <tr> |
| <td>Dubbo: kyro</td> |
| <td>1.182</td> |
| <td>8444</td> |
| </tr> |
| <tr> |
| <td>Dubbo: Dubbo serialization</td> |
| <td>1.43</td> |
| <td>6982</td> |
| </tr> |
| <tr> |
| <td>Dubbo: hessian2</td> |
| <td>1.49</td> |
| <td>6701</td> |
| </tr> |
| <tr> |
| <td>Dubbo: fastjson</td> |
| <td>1.572</td> |
| <td>6352</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>Just a brief summary of the current results:</p> |
| <ul> |
| <li>Dubbo RPC (especially when based on efficient java serialization methods such as kryo and fst) has a significant advantage response time and throughput over REST. Dubbo RPC is preferred in the intranet Dubbo systems.</li> |
| <li>When choosinf REST implementation, tomcat7 and netty are optimal (of course, the current versions of jetty and netty are lower) currently only considering performance. Tjws and sun http server performed extremely poorly in performance tests, with an average response time of more than 200ms and an average tps of only about 50 (to avoid affecting the picture effect, the results are not listed above).</li> |
| <li>Performance of JSON data format is better than XML in REST (data is not listed above).</li> |
| <li>Enabling GZIP in REST has little to do with complex objects with small data volume in the intranet, but performance has declined (data is not listed above).</li> |
| </ul> |
| <h2 id="performance-optimization-recommendations">Performance Optimization Recommendations</h2> |
| <p>If you deploy Dubbo REST to an external Tomcat and configure server=&ldquo;servlet&rdquo;, that is, enable external tomcat as the underlying implementation of rest server, it is best to add the following configuration to tomcat:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;Connector</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>protocol=<span style="color:#2aa198">&#34;org.apache.coyote.http11.Http11NioProtocol&#34;</span> |
| </span></span><span style="display:flex;"><span> connectionTimeout=<span style="color:#2aa198">&#34;20000&#34;</span> |
| </span></span><span style="display:flex;"><span> redirectPort=<span style="color:#2aa198">&#34;8443&#34;</span> |
| </span></span><span style="display:flex;"><span> minSpareThreads=<span style="color:#2aa198">&#34;20&#34;</span> |
| </span></span><span style="display:flex;"><span> enableLookups=<span style="color:#2aa198">&#34;false&#34;</span> |
| </span></span><span style="display:flex;"><span> maxThreads=<span style="color:#2aa198">&#34;100&#34;</span> |
| </span></span><span style="display:flex;"><span> maxKeepAliveRequests=<span style="color:#2aa198">&#34;-1&#34;</span> |
| </span></span><span style="display:flex;"><span> keepAliveTimeout=<span style="color:#2aa198">&#34;60000&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Especially the configuration maxKeepAliveRequests=&quot;-1&quot; ,which is mainly to ensure that tomcat always enables http long connection, in order to improve the performance of REST call. Note, however, that if the REST consumer side is not continuously call REST services, it is not always best to enable long connections all time. In addition, the way to always enable long connections is generally not suitable for ordinary webapps, but more suitable for such rpc-like scenarios. So that in order to get high performance, Dubbo REST applications and ordinary web applications are best not to be mixed deployment, but should use a separate instance in tomcat.</p> |
| <h2 id="extended-discussion">##Extended discussion</h2> |
| <h3 id="comparison-among-rest-thrift-protobuf-and-so-on">Comparison among Rest, Thrift, Protobuf and so on</h3> |
| <p>TODO</p> |
| <h3 id="comparison-between-rest-and-traditional-webservers">Comparison between REST and traditional Webservers</h3> |
| <p>TODO</p> |
| <h3 id="comparison-of-jax-rs-between-spring-mvc">Comparison of JAX-RS Between Spring MVC</h3> |
| <p>A preliminary view from <a href="http://www.infoq.com/cn/news/2014/10/Dubbox-open-source?utm_source=infoq&amp;utm_medium=popular_links_homepage#theCommentsSection">http://www.infoq.com/cn/news/2014/10/Dubbox-open-source?utm_source=infoq&amp;utm_medium=popular_links_homepage#theCommentsSection</a></p> |
| <blockquote> |
| <p>Thank you, in fact, for jax-rs and Spring MVC, I do not have a deep look at the rest support of Spring MVC. I would like to give you some preliminary ideas. Please correct me:</p> |
| </blockquote> |
| <blockquote> |
| <p>Spring MVC also supports configuration using annotation, which actually looks very similar to jax-rs.</p> |
| </blockquote> |
| <blockquote> |
| <p>Personally, I think Spring MVC is better suited to restful services of web applications, such as being invoked by AJAX, or possibly outputting HTML or something like page jump processes in applications. Spring MVC can handle both normal web page requests and rest requests at the same time. But in general, the restful service is implemented in the presentation layer or the web layer.</p> |
| </blockquote> |
| <blockquote> |
| <p>But Jax-rs is more suitable for pure service-oriented applications, that is, the middle-tier services in traditional Java EE, for example, it can publish traditional EJB as restful services. In a Spring application, the bean that acts as a service in the Spring is directly published as a restful service. In general, the restful service is at the business layer, application layer, or facade layer. And MVC hierarchies and concepts are often of little value in such (back-end) applications.</p> |
| </blockquote> |
| <blockquote> |
| <p>Of course, some implementations of jax-rs, such as jersey, also try to include MVC to better accommodate the web applications described above, but not as well as Spring MVC.</p> |
| </blockquote> |
| <blockquote> |
| <p>In Dubbo applications, I think a lot of people prefer to publish a local Spring service bean (or manager) as a remote service directly and transparently, so that it is more straightforward to use JAX-RS here, and there is no need to introduce the MVC concept. Of course, we do not discuss whether transparent publishing of remote services is a best practice or whether to add facade things here first.</p> |
| </blockquote> |
| <blockquote> |
| <p>Of course, I know that many people use Spring MVC restful to call Dubbo (spring) service to publish restful services under the situation that Dubbo does not support rest now. It’s a good method also in my opinion, but if you do not modify Spring MVC and integrate it deeply with Dubbo, restful services cannot enjoy many advanced services such as registering to the Dubbo Registry, monitoring the number of calls, TPS, response time through the Dubbo Monitor, controlling the size of the thread pool and the maximum number of connections through the unified configuration of Dubbo, and controlling the service flow, authority and frequency through Dubbo unified mode like other remote call protocol such as webservices, Dubbo rpc, hessian and so on in Dubbo system. In addition, Spring MVC only works in server side and Spring restTemplate are usually used on consumer side. If restTemplate is not integrated with Dubbo, the service can be downgraded by Dubbo client automatically or manually. If the server and consumer are all Dubbo system, you cannot use unified routing and other functions in Dubbo if the Spring rest is not deeply integrated into Dubbo through interaction of Spring and rest.</p> |
| </blockquote> |
| <blockquote> |
| <p>Of course, I personally think that these things are not necessarily to be one or the other. I heard that Rod Johnson, the founder of spring usually says ‘the customer is always right,’ In fact, it is better to support both ways at the same time rather than discuss which way is better, so that originally I wrote in the document that we plan to support Spring rest annotation, but the feasibility is unknown.</p> |
| </blockquote> |
| <h2 id="future">##Future</h2> |
| <p>Functions may be supported later:</p> |
| <ul> |
| <li>Rest annotation for Spring MVC</li> |
| <li>Safety System</li> |
| <li>OAuth</li> |
| <li>Asynchronous calls</li> |
| <li>Gzip</li> |
| <li>Payload maxsize</li> |
| </ul></description></item><item><title>Docs: Simple Monitor</title><link>https://dubbo.apache.org/en/docs/v2.7/user/simple-monitor/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/simple-monitor/</guid><description> |
| <div class="alert alert-warning" role="alert"> |
| <h4 class="alert-heading">Warning</h4> |
| <p>Monitor service is a standard Dubbo service，can be exported to the registry，also can be connected straightly.</p> |
| <p><a href="https://dubbo.apache.org/en/docs/v2.7/admin/install/">Install the simple registry</a></p> |
| </div> |
| <ol start="0"> |
| <li> |
| <p>export a simple monitor service to the registry: (If you use the installer, you don&rsquo;t need to write this configuration yourself. if you implement the monitor service yourself，need it)</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;beans</span> xmlns=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans&#34;</span> |
| </span></span><span style="display:flex;"><span>xmlns:xsi=<span style="color:#2aa198">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> |
| </span></span><span style="display:flex;"><span>xmlns:dubbo=<span style="color:#2aa198">&#34;http://dubbo.apache.org/schema/dubbo&#34;</span> |
| </span></span><span style="display:flex;"><span>xsi:schemaLocation=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- configuration of current application --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;simple-monitor&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- connection address of the registry --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:registry</span> address=<span style="color:#2aa198">&#34;127.0.0.1:9090&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- protool configuration of exposed services --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> port=<span style="color:#2aa198">&#34;7070&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- configuration of certain exposed service --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.monitor.MonitorService&#34;</span> ref=<span style="color:#2aa198">&#34;monitorService&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;monitorService&#34;</span> class=<span style="color:#2aa198">&#34;org.apache.dubbo.monitor.simple.SimpleMonitorService&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/beans&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>Discovery the monitor service int the registry:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:monitor</span> protocol=<span style="color:#2aa198">&#34;registry&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>or</p> |
| <blockquote> |
| <p>dubbo.properties</p> |
| </blockquote> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span>dubbo.monitor.protocol=registry |
| </span></span></code></pre></div></li> |
| <li> |
| <p>Export a simple monitor service ，but don&rsquo;t register it to th registry: (If you use the installer, you don&rsquo;t need to write this configuration yourself. if you implement the monitor service yourself，need it)</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;beans</span> xmlns=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans&#34;</span> |
| </span></span><span style="display:flex;"><span>xmlns:xsi=<span style="color:#2aa198">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> |
| </span></span><span style="display:flex;"><span>xmlns:dubbo=<span style="color:#2aa198">&#34;http://dubbo.apache.org/schema/dubbo&#34;</span> |
| </span></span><span style="display:flex;"><span>xsi:schemaLocation=<span style="color:#2aa198">&#34;http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- configuration of current application --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;simple-monitor&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- protool configuration of exposed service --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> port=<span style="color:#2aa198">&#34;7070&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- configuration of exposed service --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.monitor.MonitorService&#34;</span> ref=<span style="color:#2aa198">&#34;monitorService&#34;</span> registry=<span style="color:#2aa198">&#34;N/A&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;monitorService&#34;</span> class=<span style="color:#2aa198">&#34;org.apache.dubbo.monitor.simple.SimpleMonitorService&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/beans&gt;</span> |
| </span></span></code></pre></div></li> |
| <li> |
| <p>connected to the monitor service straightly</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:monitor</span> address=<span style="color:#2aa198">&#34;dubbo://127.0.0.1:7070/org.apache.dubbo.monitor.MonitorService&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>or：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>&lt;dubbo:monitor <span style="color:#268bd2">address</span><span style="color:#719e07">=</span><span style="color:#2aa198">&#34;127.0.0.1:7070&#34;</span> /&gt; |
| </span></span></code></pre></div><p>or：</p> |
| <p><strong>dubbo.properties</strong></p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>dubbo.monitor.address<span style="color:#719e07">=</span>127.0.0.1:7070 |
| </span></span></code></pre></div></li> |
| </ol></description></item><item><title>Docs: Other Languages</title><link>https://dubbo.apache.org/en/docs/v2.7/user/languages/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/user/languages/</guid><description/></item></channel></rss> |
