| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Apache Dubbo – 协议参考手册</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/</link><description>Recent content in 协议参考手册 on Apache Dubbo</description><generator>Hugo -- gohugo.io</generator><language>zh-cn</language><atom:link href="https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/index.xml" rel="self" type="application/rss+xml"/><item><title>Docsv2.7: dubbo 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/dubbo/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/dubbo/</guid><description> |
| <p>Dubbo 缺省协议采用单一长连接和 NIO 异步通讯,适合于小数据量大并发的服务调用,以及服务消费者机器数远大于服务提供者机器数的情况。</p> |
| <p>反之,Dubbo 缺省协议不适合传送大数据量的服务,比如传文件,传视频等,除非请求量很低。</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/dubbo-protocol.jpg" alt="dubbo-protocol.jpg"></p> |
| <ul> |
| <li>Transporter: mina, netty, grizzy</li> |
| <li>Serialization: dubbo, hessian2, java, json</li> |
| <li>Dispatcher: all, direct, message, execution, connection</li> |
| <li>ThreadPool: fixed, cached</li> |
| </ul> |
| <h2 id="特性">特性</h2> |
| <p>缺省协议,使用基于 netty <code>3.2.5.Final</code> 和 hessian2 <code>3.2.1-fixed-2(Alibaba embed version)</code> 的 tbremoting 交互。</p> |
| <ul> |
| <li>连接个数:单连接</li> |
| <li>连接方式:长连接</li> |
| <li>传输协议:TCP</li> |
| <li>传输方式:NIO 异步传输</li> |
| <li>序列化:Hessian 二进制序列化</li> |
| <li>适用范围:传入传出参数数据包较小(建议小于100K),消费者比提供者个数多,单一消费者无法压满提供者,尽量不要用 dubbo 协议传输大文件或超大字符串。</li> |
| <li>适用场景:常规远程服务方法调用</li> |
| </ul> |
| <h2 id="约束">约束</h2> |
| <ul> |
| <li>参数及返回值需实现 <code>Serializable</code> 接口</li> |
| <li>参数及返回值不能自定义实现 <code>List</code>, <code>Map</code>, <code>Number</code>, <code>Date</code>, <code>Calendar</code> 等接口,只能用 JDK 自带的实现,因为 hessian 会做特殊处理,自定义实现类中的属性值都会丢失。</li> |
| <li>Hessian 序列化,只传成员属性值和值的类型,不传方法或静态变量,兼容情况 <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup><sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>:</li> |
| </ul> |
| <table> |
| <thead> |
| <tr> |
| <th>数据通讯</th> |
| <th>情况</th> |
| <th>结果</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>类A多一种 属性(或者说类B少一种 属性)</td> |
| <td>不抛异常,A多的那 个属性的值,B没有, 其他正常</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>枚举A多一种 枚举(或者说B少一种 枚举),A使用多 出来的枚举进行传输</td> |
| <td>抛异常</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>枚举A多一种 枚举(或者说B少一种 枚举),A不使用 多出来的枚举进行传输</td> |
| <td>不抛异常,B正常接 收数据</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>A和B的属性 名相同,但类型不相同</td> |
| <td>抛异常</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>serialId 不相同</td> |
| <td>正常传输</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>接口增加方法,对客户端无影响,如果该方法不是客户端需要的,客户端不需要重新部署。输入参数和结果集中增加属性,对客户端无影响,如果客户端并不需要新属性,不用重新部署。</p> |
| <p>输入参数和结果集属性名变化,对客户端序列化无影响,但是如果客户端不重新部署,不管输入还是输出,属性名变化的属性值是获取不到的。</p> |
| <p>总结:服务器端和客户端对领域对象并不需要完全一致,而是按照最大匹配原则。</p> |
| <h2 id="配置">配置</h2> |
| <p>配置协议:</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><p>设置默认协议:</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:provider</span> protocol=<span style="color:#2aa198">&#34;dubbo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>设置服务协议:</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> protocol=<span style="color:#2aa198">&#34;dubbo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>多端口:</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> id=<span style="color:#2aa198">&#34;dubbo1&#34;</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:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;dubbo2&#34;</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20881&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置协议选项:</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">“dubbo”</span> port=<span style="color:#2aa198">“9090”</span> server=<span style="color:#2aa198">“netty”</span> client=<span style="color:#2aa198">“netty”</span> codec=<span style="color:#2aa198">“dubbo”</span> serialization=<span style="color:#2aa198">“hessian2”</span> charset=<span style="color:#2aa198">“UTF-8”</span> threadpool=<span style="color:#2aa198">“fixed”</span> threads=<span style="color:#2aa198">“100”</span> queues=<span style="color:#2aa198">“0”</span> iothreads=<span style="color:#2aa198">“9”</span> buffer=<span style="color:#2aa198">“8192”</span> accepts=<span style="color:#2aa198">“1000”</span> payload=<span style="color:#2aa198">“8388608”</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>多连接配置:</p> |
| <p>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> connections=<span style="color:#2aa198">&#34;1&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> connections=<span style="color:#2aa198">&#34;1&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><ul> |
| <li><code>&lt;dubbo:service connections=&quot;0&quot;&gt;</code> 或 <code>&lt;dubbo:reference connections=&quot;0&quot;&gt;</code> 表示该服务使用 JVM 共享长连接。<strong>缺省</strong></li> |
| <li><code>&lt;dubbo:service connections=&quot;1&quot;&gt;</code> 或 <code>&lt;dubbo:reference connections=&quot;1&quot;&gt;</code> 表示该服务使用独立长连接。</li> |
| <li><code>&lt;dubbo:service connections=&quot;2&quot;&gt;</code> 或<code>&lt;dubbo:reference connections=&quot;2&quot;&gt;</code> 表示该服务使用独立两条长连接。</li> |
| </ul> |
| <p>为防止被大量连接撑挂,可在服务提供方限制大接收连接数,以实现服务提供方自我保护。</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> accepts=<span style="color:#2aa198">&#34;1000&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><code>dubbo.properties</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-sh" data-lang="sh"><span style="display:flex;"><span>dubbo.service.protocol<span style="color:#719e07">=</span>dubbo |
| </span></span></code></pre></div><h2 id="常见问题">常见问题</h2> |
| <h4 id="为什么要消费者比提供者个数多">为什么要消费者比提供者个数多?</h4> |
| <p>因 dubbo 协议采用单一长连接,假设网络为千兆网卡 <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>,根据测试经验数据每条连接最多只能压满 7MByte(不同的环境可能不一样,供参考),理论上 1 个服务提供者需要 20 个服务消费者才能压满网卡。</p> |
| <h4 id="为什么不能传大包">为什么不能传大包?</h4> |
| <p>因 dubbo 协议采用单一长连接,如果每次请求的数据包大小为 500KByte,假设网络为千兆网卡 <sup id="fnref1:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>,每条连接最大 7MByte(不同的环境可能不一样,供参考),单个服务提供者的 TPS(每秒处理事务数)最大为:128MByte / 500KByte = 262。单个消费者调用单个服务提供者的 TPS(每秒处理事务数)最大为:7MByte / 500KByte = 14。如果能接受,可以考虑使用,否则网络将成为瓶颈。</p> |
| <h4 id="为什么采用异步单一长连接">为什么采用异步单一长连接?</h4> |
| <p>因为服务的现状大都是服务提供者少,通常只有几台机器,而服务的消费者多,可能整个网站都在访问该服务,比如 Morgan 的提供者只有 6 台提供者,却有上百台消费者,每天有 1.5 亿次调用,如果采用常规的 hessian 服务,服务提供者很容易就被压跨,通过单一连接,保证单一消费者不会压死提供者,长连接,减少连接握手验证等,并使用异步 IO,复用线程池,防止 C10K 问题。</p> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>由吴亚军提供&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>总结:会抛异常的情况:枚举值一边多一种,一边少一种,正好使用了差别的那种,或者属性名相同,类型不同&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>1024Mbit=128MByte&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a>&#160;<a href="#fnref1:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: rest 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/rest/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/rest/</guid><description> |
| <p>基于标准的Java REST API——JAX-RS 2.0(Java API for RESTful Web Services的简写)实现的REST调用支持</p> |
| <h2 id="快速入门">快速入门</h2> |
| <p>在dubbo中开发一个REST风格的服务会比较简单,下面以一个注册用户的简单服务为例说明。</p> |
| <p>这个服务要实现的功能是提供如下URL(注:这个URL不是完全符合REST的风格,但是更简单实用):</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>而任何客户端都可以将包含用户信息的JSON字符串POST到以上URL来完成用户注册。</p> |
| <p>首先,开发服务的接口:</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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span><span style="color:#719e07">(</span>User user<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>然后,开发服务的实现:</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:#719e07">(</span><span style="color:#2aa198">&#34;/users&#34;</span><span style="color:#719e07">)</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 style="color:#719e07">{</span> |
| </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:#719e07">(</span><span style="color:#2aa198">&#34;/register&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">})</span> |
| </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><span style="color:#719e07">(</span>User user<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>上面的实现非常简单,但是由于该 REST 服务是要发布到指定 URL 上,供任意语言的客户端甚至浏览器来访问,所以这里额外添加了几个 JAX-RS 的标准 annotation 来做相关的配置。</p> |
| <p>@Path(&quot;/users&quot;):指定访问UserService的URL相对路径是/users,即http://localhost:8080/users</p> |
| <p>@Path(&quot;/register&quot;):指定访问registerUser()方法的URL相对路径是/register,再结合上一个@Path为UserService指定的路径,则调用UserService.register()的完整路径为http://localhost:8080/users/register</p> |
| <p>@POST:指定访问registerUser()用HTTP POST方法</p> |
| <p>@Consumes({MediaType.APPLICATION_JSON}):指定registerUser()接收JSON格式的数据。REST框架会自动将JSON数据反序列化为User对象</p> |
| <p>最后,在spring配置文件中添加此服务,即完成所有服务开发工作:</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;!-- 用rest协议在8080端口暴露服务 --&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;!-- 声明需要暴露的服务接口 --&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;!-- 和本地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="rest服务提供端详解">REST服务提供端详解</h2> |
| <p>下面我们扩充“快速入门”中的UserService,进一步展示在dubbo中REST服务提供端的开发要点。</p> |
| <h3 id="http-postget的实现">HTTP POST/GET的实现</h3> |
| <p>REST服务中虽然建议使用HTTP协议中四种标准方法POST、DELETE、PUT、GET来分别实现常见的“增删改查”,但实际中,我们一般情况直接用POST来实现“增改”,GET来实现“删查”即可(DELETE和PUT甚至会被一些防火墙阻挡)。</p> |
| <p>前面已经简单演示了POST的实现,在此,我们为UserService添加一个获取注册用户资料的功能,来演示GET的实现。</p> |
| <p>这个功能就是要实现客户端通过访问如下不同URL来获取不同ID的用户资料:</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>当然,也可以通过其他形式的URL来访问不同ID的用户资料,例如:</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/load?id=1001 |
| </span></span></code></pre></div><p>JAX-RS本身可以支持所有这些形式。但是上面那种在URL路径中包含查询参数的形式(http://localhost:8080/users/1001) 更符合REST的一般习惯,所以更推荐大家来使用。下面我们就为UserService添加一个getUser()方法来实现这种形式的URL访问:</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:#719e07">(</span><span style="color:#2aa198">&#34;/{id : \\d+}&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>@GET:指定用HTTP GET方法访问</p> |
| <p>@Path(&quot;/{id : \d+}&quot;):根据上面的功能需求,访问getUser()的URL应当是“http://localhost:8080/users/ + 任意数字&quot;,并且这个数字要被做为参数传入getUser()方法。 这里的annotation配置中,@Path中间的{id: xxx}指定URL相对路径中包含了名为id参数,而它的值也将被自动传递给下面用@PathParam(&ldquo;id&rdquo;)修饰的方法参数id。{id:后面紧跟的\d+是一个正则表达式,指定了id参数必须是数字。</p> |
| <p>@Produces({MediaType.APPLICATION_JSON}):指定getUser()输出JSON格式的数据。框架会自动将User对象序列化为JSON数据。</p> |
| <h3 id="annotation放在接口类还是实现类">Annotation放在接口类还是实现类</h3> |
| <p>在Dubbo中开发REST服务主要都是通过JAX-RS的annotation来完成配置的,在上面的示例中,我们都是将annotation放在服务的实现类中。但其实,我们完全也可以将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">@Path</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;/users&#34;</span><span style="color:#719e07">)</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 style="color:#719e07">{</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:#719e07">(</span><span style="color:#2aa198">&#34;/{id : \\d+}&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>在一般应用中,我们建议将annotation放到服务实现类,这样annotation和java实现代码位置更接近,更便于开发和维护。另外更重要的是,我们一般倾向于避免对接口的污染,保持接口的纯净性和广泛适用性。</p> |
| <p>但是,如后文所述,如果我们要用dubbo直接开发的消费端来访问此服务,则annotation必须放到接口上。</p> |
| <p>如果接口和实现类都同时添加了annotation,则实现类的annotation配置会生效,接口上的annotation被直接忽略。</p> |
| <h3 id="jsonxml等多数据格式的支持">JSON、XML等多数据格式的支持</h3> |
| <p>在dubbo中开发的REST服务可以同时支持传输多种格式的数据,以给客户端提供最大的灵活性。其中我们目前对最常用的JSON和XML格式特别添加了额外的功能。</p> |
| <p>比如,我们要让上例中的getUser()方法支持分别返回JSON和XML格式的数据,只需要在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><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">,</span> MediaType<span style="color:#719e07">.</span>TEXT_XML<span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><p>或者也可以直接用字符串(还支持通配符)表示MediaType:</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:#719e07">({</span><span style="color:#2aa198">&#34;application/json&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;text/xml&#34;</span><span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><p>如果所有方法都支持同样类型的输入输出数据格式,则我们无需在每个方法上做配置,只需要在服务类上添加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">@Path</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;/users&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Consumes</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">,</span> MediaType<span style="color:#719e07">.</span>TEXT_XML<span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">,</span> MediaType<span style="color:#719e07">.</span>TEXT_XML<span style="color:#719e07">})</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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>在一个REST服务同时对多种数据格式支持的情况下,根据JAX-RS标准,一般是通过HTTP中的MIME header(content-type和accept)来指定当前想用的是哪种格式的数据。</p> |
| <p>但是在dubbo中,我们还自动支持目前业界普遍使用的方式,即用一个URL后缀(.json和.xml)来指定想用的数据格式。例如,在添加上述annotation后,直接访问http://localhost:8888/users/1001.json则表示用json格式,直接访问http://localhost:8888/users/1002.xml则表示用xml格式,比用HTTP Header更简单直观。Twitter、微博等的REST API都是采用这种方式。</p> |
| <p>如果你既不加HTTP header,也不加后缀,则dubbo的REST会优先启用在以上annotation定义中排位最靠前的那种数据格式。</p> |
| <blockquote> |
| <p>注意:这里要支持XML格式数据,在annotation中既可以用MediaType.TEXT_XML,也可以用MediaType.APPLICATION_XML,但是TEXT_XML是更常用的,并且如果要利用上述的URL后缀方式来指定数据格式,只能配置为TEXT_XML才能生效。</p> |
| </blockquote> |
| <h3 id="中文字符支持">中文字符支持</h3> |
| <p>为了在dubbo REST中正常输出中文字符,和通常的Java web应用一样,我们需要将HTTP响应的contentType设置为UTF-8编码。</p> |
| <p>基于JAX-RS的标准用法,我们只需要做如下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><span style="color:#719e07">({</span><span style="color:#2aa198">&#34;application/json; charset=UTF-8&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;text/xml; charset=UTF-8&#34;</span><span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><p>为了方便用户,我们在dubbo REST中直接添加了一个支持类,来定义以上的常量,可以直接使用,减少出错的可能性。</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:#719e07">({</span>ContentType<span style="color:#719e07">.</span>APPLICATION_JSON_UTF_8<span style="color:#719e07">,</span> ContentType<span style="color:#719e07">.</span>TEXT_XML_UTF_8<span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><h3 id="xml数据格式的额外要求">XML数据格式的额外要求</h3> |
| <p>由于JAX-RS的实现一般都用标准的JAXB(Java API for XML Binding)来序列化和反序列化XML格式数据,所以我们需要为每一个要用XML传输的对象添加一个类级别的JAXB annotation,否则序列化将报错。例如为getUser()中返回的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:#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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>此外,如果service方法中的返回值是Java的 primitive类型(如int,long,float,double等),最好为它们添加一层wrapper对象,因为JAXB不能直接序列化primitive类型。</p> |
| <p>例如,我们想让前述的registerUser()方法返回服务器端为用户生成的ID号:</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><span style="color:#719e07">(</span>User user<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><p>由于primitive类型不被JAXB序列化支持,所以添加一个wrapper对象:</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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> Long id<span style="color:#719e07">;</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><span style="color:#719e07">()</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</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><span style="color:#719e07">(</span>Long id<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span><span style="color:#719e07">.</span>id <span style="color:#719e07">=</span> id<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</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 style="color:#719e07">()</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> id<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</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><span style="color:#719e07">(</span>Long id<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span><span style="color:#719e07">.</span>id <span style="color:#719e07">=</span> id<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>并修改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>RegistrationResult <span style="color:#268bd2">registerUser</span><span style="color:#719e07">(</span>User user<span style="color:#719e07">);</span> |
| </span></span></code></pre></div><p>这样不但能够解决XML序列化的问题,而且使得返回的数据都符合XML和JSON的规范。例如,在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-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>如果不加wrapper,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-fallback" data-lang="fallback"><span style="display:flex;"><span>1001 |
| </span></span></code></pre></div><p>而在XML中,加wrapper后返回值将是:</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>这种wrapper对象其实利用所谓Data Transfer Object(DTO)模式,采用DTO还能对传输数据做更多有用的定制。</p> |
| <h3 id="定制序列化">定制序列化</h3> |
| <p>如上所述,REST的底层实现会在service的对象和JSON/XML数据格式之间自动做序列化/反序列化。但有些场景下,如果觉得这种自动转换不满足要求,可以对其做定制。</p> |
| <p>Dubbo中的REST实现是用JAXB做XML序列化,用Jackson做JSON序列化,所以在对象上添加JAXB或Jackson的annotation即可以定制映射。</p> |
| <p>例如,定制对象属性映射到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-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><span style="color:#719e07">(</span>XmlAccessType<span style="color:#719e07">.</span>FIELD<span style="color:#719e07">)</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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@XmlElement</span><span style="color:#719e07">(</span>name<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;username&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>定制对象属性映射到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 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 style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@JsonProperty</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;username&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>更多资料请参考JAXB和Jackson的官方文档,或自行google。</p> |
| <h3 id="配置rest-server的实现">配置REST Server的实现</h3> |
| <p>目前在dubbo中,我们支持5种嵌入式rest server的实现,并同时支持采用外部应用服务器来做rest server的实现。rest 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>以上配置选用了嵌入式的jetty来做rest server,同时,如果不配置server属性,rest协议默认也是选用jetty。jetty是非常成熟的java servlet容器,并和dubbo已经有较好的集成(目前5种嵌入式server中只有jetty和后面所述的tomcat、tjws,与dubbo监控系统等完成了无缝的集成),所以,如果你的dubbo系统是单独启动的进程,你可以直接默认采用jetty即可。</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>以上配置选用了嵌入式的tomcat来做rest server。在嵌入式tomcat上,REST的性能比jetty上要好得多(参见后面的基准测试),建议在需要高性能的场景下采用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;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>以上配置选用嵌入式的netty来做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>以上配置选用嵌入式的tjws或Sun HTTP server来做rest server。这两个server实现非常轻量级,非常方便在集成测试中快速启动使用,当然也可以在负荷不高的生产环境中使用。 注:tjws目前已经被deprecated掉了,因为它不能很好的和servlet 3.1 API工作。</p> |
| <p>如果你的dubbo系统不是单独启动的进程,而是部署到了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-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>通过将server设置为servlet,dubbo将采用外部应用服务器的servlet容器来做rest server。同时,还要在dubbo系统的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;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>即必须将dubbo的BootstrapListener和DispatherServlet添加到web.xml,以完成dubbo的REST功能与外部servlet容器的集成。</p> |
| <blockquote> |
| <p>注意:如果你是用spring的ContextLoaderListener来加载spring,则必须保证BootstrapListener配置在ContextLoaderListener之前,否则dubbo初始化会出错。</p> |
| </blockquote> |
| <p>其实,这种场景下你依然可以坚持用嵌入式server,但外部应用服务器的servlet容器往往比嵌入式server更加强大(特别是如果你是部署到更健壮更可伸缩的WebLogic,WebSphere等),另外有时也便于在应用服务器做统一管理、监控等等。</p> |
| <h3 id="获取上下文context信息">获取上下文(Context)信息</h3> |
| <p>在远程调用中,值得获取的上下文信息可能有很多种,这里特别以获取客户端IP为例。</p> |
| <p>在dubbo的REST中,我们有两种方式获取客户端IP。</p> |
| <p>第一种方式,用JAX-RS标准的@Context 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">public</span> User <span style="color:#268bd2">getUser</span><span style="color:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">,</span> <span style="color:#268bd2">@Context</span> HttpServletRequest request<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> request<span style="color:#719e07">.</span>getRemoteAddr<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>用Context修饰getUser()的一个方法参数后,就可以将当前的HttpServletRequest注入进来,然后直接调用servlet api获取IP。</p> |
| <blockquote> |
| <p>注意:这种方式只能在将server设置为 tjws、tomcat、jetty 或者 servlet 的时候才能工作,因为只有这几种 server 的实现才提供了 servlet 容器。另外,标准的JAX-RS还支持用@Context修饰service类的一个实例字段来获取HttpServletRequest,但在dubbo中我们没有对此作出支持。</p> |
| </blockquote> |
| <p>第二种方式,用dubbo中常用的RpcContext:</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:#719e07">(</span><span style="color:#268bd2">@PathParam</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRemoteAddressString<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><blockquote> |
| <p>注意:这种方式只能在设置server=&ldquo;jetty&quot;或者server=&ldquo;tomcat&quot;或者server=&ldquo;servlet&quot;或者server=&ldquo;tjws&quot;的时候才能工作。另外,目前dubbo的RpcContext是一种比较有侵入性的用法,未来我们很可能会做出重构。</p> |
| </blockquote> |
| <p>如果你想保持你的项目对JAX-RS的兼容性,未来脱离dubbo也可以运行,请选择第一种方式。如果你想要更优雅的服务接口定义,请选用第二种方式。</p> |
| <p>此外,在最新的dubbo rest中,还支持通过RpcContext来获取HttpServletRequest和HttpServletResponse,以提供更大的灵活性来方便用户实现某些复杂功能,比如在dubbo标准的filter中访问HTTP Header。用法示例如下:</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> <span style="color:#719e07">(</span>RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRequest<span style="color:#719e07">()</span> <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRequest<span style="color:#719e07">()</span> <span style="color:#719e07">instanceof</span> HttpServletRequest<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> <span style="color:#719e07">((</span>HttpServletRequest<span style="color:#719e07">)</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRequest<span style="color:#719e07">()).</span>getRemoteAddr<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> <span style="color:#719e07">(</span>RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getResponse<span style="color:#719e07">()</span> <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getResponse<span style="color:#719e07">()</span> <span style="color:#719e07">instanceof</span> HttpServletResponse<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getResponse<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><blockquote> |
| <p>注意:为了保持协议的中立性,RpcContext.getRequest()和RpcContext.getResponse()返回的仅仅是一个Object类,而且可能为null。所以,你必须自己做null和类型的检查。</p> |
| </blockquote> |
| <blockquote> |
| <p>注意:只有在设置server=&ldquo;jetty&quot;或者server=&ldquo;tomcat&quot;或者server=&ldquo;servlet&quot;的时候,你才能通过以上方法正确的得到HttpServletRequest和HttpServletResponse,因为只有这几种server实现了servlet容器。</p> |
| </blockquote> |
| <p>为了简化编程,在此你也可以用泛型的方式来直接获取特定类型的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> <span style="color:#719e07">(</span>RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRequest<span style="color:#719e07">(</span>HttpServletRequest<span style="color:#719e07">.</span>class<span style="color:#719e07">)</span> <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span><span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getRequest<span style="color:#719e07">(</span>HttpServletRequest<span style="color:#719e07">.</span>class<span style="color:#719e07">).</span>getRemoteAddr<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> <span style="color:#719e07">(</span>RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getResponse<span style="color:#719e07">(</span>HttpServletResponse<span style="color:#719e07">.</span>class<span style="color:#719e07">)</span> <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span><span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext<span style="color:#719e07">.</span>getContext<span style="color:#719e07">().</span>getResponse<span style="color:#719e07">(</span>HttpServletResponse<span style="color:#719e07">.</span>class<span style="color:#719e07">));</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>如果request/response不符合指定的类型,这里也会返回null。</p> |
| <h3 id="配置端口号和context-path">配置端口号和Context Path</h3> |
| <p>dubbo中的rest协议默认将采用80端口,如果想修改端口,直接配置:</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>另外,如前所述,我们可以用@Path来配置单个rest服务的URL相对路径。但其实,我们还可以设置一个所有rest服务都适用的基础相对路径,即java web应用中常说的context path。</p> |
| <p>只需要添加如下contextpath属性即可:</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>以前面代码为例:</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:#719e07">(</span><span style="color:#2aa198">&#34;/users&#34;</span><span style="color:#719e07">)</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 style="color:#719e07">{</span> |
| </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:#719e07">(</span><span style="color:#2aa198">&#34;/register&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">})</span> |
| </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><span style="color:#719e07">(</span>User user<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>现在registerUser()的完整访问路径为:</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>注意:如果你是选用外部应用服务器做rest 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> 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>则必须保证这里设置的port、contextpath,与外部应用服务器的端口、DispatcherServlet的上下文路径(即webapp path加上servlet url pattern)保持一致。例如,对于部署为tomcat ROOT路径的应用,这里的contextpath必须与web.xml中DispacherServlet的<code>&lt;url-pattern/&gt;</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;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="配置线程数和io线程数">配置线程数和IO线程数</h3> |
| <p>可以为rest服务配置线程池大小:</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>注意:目前线程池的设置只有当server=&ldquo;netty&quot;或者server=&ldquo;jetty&quot;或者server=&ldquo;tomcat&quot;的时候才能生效。另外,如果server=&ldquo;servlet&rdquo;,由于这时候启用的是外部应用服务器做rest server,不受dubbo控制,所以这里的线程池设置也无效。</p> |
| </blockquote> |
| <p>如果是选用netty server,还可以配置Netty的IO worker线程数:</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="配置长连接">配置长连接</h3> |
| <p>Dubbo中的rest服务默认都是采用http长连接来访问,如果想切换为短连接,直接配置:</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>注意:这个配置目前只对server=&ldquo;netty&quot;和server=&ldquo;tomcat&quot;才能生效。</p> |
| </blockquote> |
| <h3 id="配置最大的http连接数">配置最大的HTTP连接数</h3> |
| <p>可以配置服务器提供端所能同时接收的最大HTTP连接数,防止REST 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> 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>注意:这个配置目前只对server=&ldquo;tomcat&quot;才能生效。</p> |
| </blockquote> |
| <h3 id="配置每个消费端的超时时间和http连接数">配置每个消费端的超时时间和HTTP连接数</h3> |
| <p>如果rest服务的消费端也是dubbo系统,可以像其他dubbo RPC机制一样,配置消费端调用此rest服务的最大超时时间以及每个消费端所能启动的最大HTTP连接数。</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>当然,由于这个配置针对消费端生效的,所以也可以在消费端配置:</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>但是,通常我们建议配置在服务提供端提供此类配置。按照dubbo官方文档的说法:“Provider上尽量多配置Consumer端的属性,让Provider实现者一开始就思考Provider服务特点、服务质量的问题。”</p> |
| <blockquote> |
| <p>注意:如果dubbo的REST服务是发布给非dubbo的客户端使用,则这里<code>&lt;dubbo:service/&gt;</code>上的配置完全无效,因为这种客户端不受dubbo控制。</p> |
| </blockquote> |
| <h3 id="用annotation取代部分spring-xml配置">用Annotation取代部分Spring XML配置</h3> |
| <p>以上所有的讨论都是基于dubbo在spring中的xml配置。但是,dubbo/spring本身也支持用annotation来作配置,所以我们也可以按dubbo官方文档中的步骤,把相关annotation加到REST服务的实现中,取代一些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-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Service</span><span style="color:#719e07">(</span>protocol <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;rest&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;/users&#34;</span><span style="color:#719e07">)</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 style="color:#719e07">{</span> |
| </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 style="color:#719e07">;</span> |
| </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:#719e07">(</span><span style="color:#2aa198">&#34;/register&#34;</span><span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span><span style="color:#719e07">({</span>MediaType<span style="color:#719e07">.</span>APPLICATION_JSON<span style="color:#719e07">})</span> |
| </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><span style="color:#719e07">(</span>User user<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> userRepository<span style="color:#719e07">.</span>save<span style="color:#719e07">(</span>user<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>annotation的配置更简单更精确,通常也更便于维护(当然现代IDE都可以在xml中支持比如类名重构,所以就这里的特定用例而言,xml的维护性也很好)。而xml对代码的侵入性更小一些,尤其有利于动态修改配置,特别是比如你要针对单个服务配置连接超时时间、每客户端最大连接数、集群策略、权重等等。另外,特别对复杂应用或者模块来说,xml提供了一个中心点来涵盖的所有组件和配置,更一目了然,一般更便于项目长时期的维护。</p> |
| <p>当然,选择哪种配置方式没有绝对的优劣,和个人的偏好也不无关系。</p> |
| <h3 id="添加自定义的filterinterceptor等">添加自定义的Filter、Interceptor等</h3> |
| <p>Dubbo的REST也支持JAX-RS标准的Filter和Interceptor,以方便对REST的请求与响应过程做定制化的拦截处理。</p> |
| <p>其中,Filter主要用于访问和设置HTTP请求和响应的参数、URI等等。例如,设置HTTP响应的cache header:</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 style="color:#719e07">{</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">filter</span><span style="color:#719e07">(</span>ContainerRequestContext req<span style="color:#719e07">,</span> ContainerResponseContext res<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> <span style="color:#719e07">(</span>req<span style="color:#719e07">.</span>getMethod<span style="color:#719e07">().</span>equals<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;GET&#34;</span><span style="color:#719e07">))</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> res<span style="color:#719e07">.</span>getHeaders<span style="color:#719e07">().</span>add<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Cache-Control&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;someValue&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>Interceptor主要用于访问和修改输入与输出字节流,例如,手动添加GZIP压缩:</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 style="color:#719e07">{</span> |
| </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><span style="color:#719e07">(</span>WriterInterceptorContext context<span style="color:#719e07">)</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">throws</span> IOException<span style="color:#719e07">,</span> WebApplicationException <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> OutputStream outputStream <span style="color:#719e07">=</span> context<span style="color:#719e07">.</span>getOutputStream<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> context<span style="color:#719e07">.</span>setOutputStream<span style="color:#719e07">(</span><span style="color:#719e07">new</span> GZIPOutputStream<span style="color:#719e07">(</span>outputStream<span style="color:#719e07">));</span> |
| </span></span><span style="display:flex;"><span> context<span style="color:#719e07">.</span>proceed<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>在标准JAX-RS应用中,我们一般是为Filter和Interceptor添加@Provider annotation,然后JAX-RS runtime会自动发现并启用它们。而在dubbo中,我们是通过添加XML配置的方式来注册Filter和Interceptor:</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>在此,我们可以将Filter、Interceptor和DynamicFeature这三种类型的对象都添加到<code>extension</code>属性上,多个之间用逗号分隔。(DynamicFeature是另一个接口,可以方便我们更动态的启用Filter和Interceptor,感兴趣请自行google。)</p> |
| <p>当然,dubbo自身也支持Filter的概念,但我们这里讨论的Filter和Interceptor更加接近协议实现的底层,相比dubbo的filter,可以做更底层的定制化。</p> |
| <blockquote> |
| <p>注:这里的XML属性叫extension,而不是叫interceptor或者filter,是因为除了Interceptor和Filter,未来我们还会添加更多的扩展类型。</p> |
| </blockquote> |
| <p>如果REST的消费端也是dubbo系统(参见下文的讨论),则也可以用类似方式为消费端配置Interceptor和Filter。但注意,JAX-RS中消费端的Filter和提供端的Filter是两种不同的接口。例如前面例子中服务端是ContainerResponseFilter接口,而消费端对应的是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 style="color:#719e07">{</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">filter</span><span style="color:#719e07">(</span>ClientRequestContext reqCtx<span style="color:#719e07">,</span> ClientResponseContext resCtx<span style="color:#719e07">)</span> <span style="color:#268bd2">throws</span> IOException <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;status: &#34;</span> <span style="color:#719e07">+</span> resCtx<span style="color:#719e07">.</span>getStatus<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;date: &#34;</span> <span style="color:#719e07">+</span> resCtx<span style="color:#719e07">.</span>getDate<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;last-modified: &#34;</span> <span style="color:#719e07">+</span> resCtx<span style="color:#719e07">.</span>getLastModified<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;location: &#34;</span> <span style="color:#719e07">+</span> resCtx<span style="color:#719e07">.</span>getLocation<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;headers:&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> <span style="color:#719e07">(</span>Entry<span style="color:#719e07">&lt;</span>String<span style="color:#719e07">,</span> List<span style="color:#719e07">&lt;</span>String<span style="color:#719e07">&gt;&gt;</span> header <span style="color:#719e07">:</span> resCtx<span style="color:#719e07">.</span>getHeaders<span style="color:#719e07">().</span>entrySet<span style="color:#719e07">())</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>print<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;\t&#34;</span> <span style="color:#719e07">+</span> header<span style="color:#719e07">.</span>getKey<span style="color:#719e07">()</span> <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34; :&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> <span style="color:#719e07">(</span>String value <span style="color:#719e07">:</span> header<span style="color:#719e07">.</span>getValue<span style="color:#719e07">())</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>print<span style="color:#719e07">(</span>value <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34;, &#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>print<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;\n&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> System<span style="color:#719e07">.</span>out<span style="color:#719e07">.</span>println<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;media-type: &#34;</span> <span style="color:#719e07">+</span> resCtx<span style="color:#719e07">.</span>getMediaType<span style="color:#719e07">().</span>getType<span style="color:#719e07">());</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><h3 id="添加自定义的exception处理">添加自定义的Exception处理</h3> |
| <p>Dubbo的REST也支持JAX-RS标准的ExceptionMapper,可以用来定制特定exception发生后应该返回的HTTP响应。</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 style="color:#719e07">{</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><span style="color:#719e07">(</span>NotFoundException e<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response<span style="color:#719e07">.</span>status<span style="color:#719e07">(</span>Response<span style="color:#719e07">.</span>Status<span style="color:#719e07">.</span>NOT_FOUND<span style="color:#719e07">).</span>entity<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Oops! the requested resource is not found!&#34;</span><span style="color:#719e07">).</span>type<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;text/plain&#34;</span><span style="color:#719e07">).</span>build<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>和Interceptor、Filter类似,将其添加到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;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.CustomExceptionMapper&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="配置http日志输出">配置HTTP日志输出</h3> |
| <p>Dubbo rest支持输出所有HTTP请求/响应中的header字段和body消息体。</p> |
| <p>在XML配置中添加如下自带的REST filter:</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>然后配置在logging配置中至少为org.apache.dubbo.rpc.protocol.rest.support打开INFO级别日志输出,例如,在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>当然,你也可以直接在ROOT logger打开INFO级别日志输出:</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>然后在日志中会有类似如下的内容输出:</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>打开HTTP日志输出后,除了正常日志输出的性能开销外,也会在比如HTTP请求解析时产生额外的开销,因为需要建立额外的内存缓冲区来为日志的输出做数据准备。</p> |
| <h3 id="输入参数的校验">输入参数的校验</h3> |
| <p>dubbo的rest支持采用Java标准的bean validation annotation(JSR 303)来做输入校验http://beanvalidation.org/</p> |
| <p>为了和其他dubbo远程调用协议保持一致,在rest中作校验的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">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> <span style="color:#719e07">{</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:#719e07">(</span><span style="color:#268bd2">@Min</span><span style="color:#719e07">(</span>value<span style="color:#719e07">=</span>1L<span style="color:#719e07">,</span> message<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;User ID must be greater than 1&#34;</span><span style="color:#719e07">)</span> Long id<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>当然,在很多其他的bean validation的应用场景都是将annotation放到实现类而不是接口上。把annotation放在接口上至少有一个好处是,dubbo的客户端可以共享这个接口的信息,dubbo甚至不需要做远程调用,在本地就可以完成输入校验。</p> |
| <p>然后按照dubbo的标准方式在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;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>在dubbo的其他很多远程调用协议中,如果输入验证出错,是直接将<code>RpcException</code>抛向客户端,而在rest中由于客户端经常是非dubbo,甚至非java的系统,所以不便直接抛出Java异常。因此,目前我们将校验错误以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;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>稍后也会支持其他数据格式的返回值。至于如何对验证错误消息作国际化处理,直接参考bean validation的相关文档即可。</p> |
| <p>如果你认为默认的校验错误返回格式不符合你的要求,可以如上面章节所述,添加自定义的ExceptionMapper来自由的定制错误返回格式。需要注意的是,这个ExceptionMapper必须用泛型声明来捕获dubbo的RpcException,才能成功覆盖dubbo rest默认的异常处理策略。为了简化操作,其实这里最简单的方式是直接继承dubbo rest的RpcExceptionMapper,并覆盖其中处理校验异常的方法即可:</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 style="color:#719e07">{</span> |
| </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><span style="color:#719e07">(</span>ConstraintViolationException cve<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> ViolationReport report <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ViolationReport<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> <span style="color:#719e07">(</span>ConstraintViolation cv <span style="color:#719e07">:</span> cve<span style="color:#719e07">.</span>getConstraintViolations<span style="color:#719e07">())</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> report<span style="color:#719e07">.</span>addConstraintViolation<span style="color:#719e07">(</span><span style="color:#719e07">new</span> RestConstraintViolation<span style="color:#719e07">(</span> |
| </span></span><span style="display:flex;"><span> cv<span style="color:#719e07">.</span>getPropertyPath<span style="color:#719e07">().</span>toString<span style="color:#719e07">(),</span> |
| </span></span><span style="display:flex;"><span> cv<span style="color:#719e07">.</span>getMessage<span style="color:#719e07">(),</span> |
| </span></span><span style="display:flex;"><span> cv<span style="color:#719e07">.</span>getInvalidValue<span style="color:#719e07">()</span> <span style="color:#719e07">==</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">?</span> <span style="color:#2aa198">&#34;null&#34;</span> <span style="color:#719e07">:</span> cv<span style="color:#719e07">.</span>getInvalidValue<span style="color:#719e07">().</span>toString<span style="color:#719e07">()));</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// 采用json输出代替xml输出 |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">return</span> Response<span style="color:#719e07">.</span>status<span style="color:#719e07">(</span>Response<span style="color:#719e07">.</span>Status<span style="color:#719e07">.</span>INTERNAL_SERVER_ERROR<span style="color:#719e07">).</span>entity<span style="color:#719e07">(</span>report<span style="color:#719e07">).</span>type<span style="color:#719e07">(</span>ContentType<span style="color:#719e07">.</span>APPLICATION_JSON_UTF_8<span style="color:#719e07">).</span>build<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>然后将这个ExceptionMapper添加到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;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></description></item><item><title>Docsv2.7: http 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/http/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/http/</guid><description> |
| <p>基于 HTTP 表单的远程调用协议,采用 Spring 的 HttpInvoker 实现</p> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">提示</h4> |
| <code>2.3.0</code> 以上版本支持 |
| </div> |
| <h2 id="特性">特性</h2> |
| <ul> |
| <li>连接个数:多连接</li> |
| <li>连接方式:短连接</li> |
| <li>传输协议:HTTP</li> |
| <li>传输方式:同步传输</li> |
| <li>序列化:表单序列化</li> |
| <li>适用范围:传入传出参数数据包大小混合,提供者比消费者个数多,可用浏览器查看,可用表单或URL传入参数,暂不支持传文件。</li> |
| <li>适用场景:需同时给应用程序和浏览器 JS 使用的服务。</li> |
| </ul> |
| <h2 id="约束">约束</h2> |
| <ul> |
| <li>参数及返回值需符合 Bean 规范</li> |
| </ul> |
| <h2 id="配置">配置</h2> |
| <p>配置协议:</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;http&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置 Jetty 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> ... server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置 Servlet Bridge 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> ... server=<span style="color:#2aa198">&#34;servlet&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置 DispatcherServlet:</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&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<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 style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<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></code></pre></div><p>注意,如果使用 servlet 派发请求:</p> |
| <ul> |
| <li>协议的端口 <code>&lt;dubbo:protocol port=&quot;8080&quot; /&gt;</code> 必须与 servlet 容器的端口相同,</li> |
| <li>协议的上下文路径 <code>&lt;dubbo:protocol contextpath=&quot;foo&quot; /&gt;</code> 必须与 servlet 应用的上下文路径相同。</li> |
| </ul></description></item><item><title>Docsv2.7: hessian 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/hessian/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/hessian/</guid><description> |
| <p>Hessian <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> 协议用于集成 Hessian 的服务,Hessian 底层采用 Http 通讯,采用 Servlet 暴露服务,Dubbo 缺省内嵌 Jetty 作为服务器实现。</p> |
| <p>Dubbo 的 Hessian 协议可以和原生 Hessian 服务互操作,即:</p> |
| <ul> |
| <li>提供者用 Dubbo 的 Hessian 协议暴露服务,消费者直接用标准 Hessian 接口调用</li> |
| <li>或者提供方用标准 Hessian 暴露服务,消费方用 Dubbo 的 Hessian 协议调用。</li> |
| </ul> |
| <h2 id="特性">特性</h2> |
| <ul> |
| <li>连接个数:多连接</li> |
| <li>连接方式:短连接</li> |
| <li>传输协议:HTTP</li> |
| <li>传输方式:同步传输</li> |
| <li>序列化:Hessian二进制序列化</li> |
| <li>适用范围:传入传出参数数据包较大,提供者比消费者个数多,提供者压力较大,可传文件。</li> |
| <li>适用场景:页面传输,文件传输,或与原生hessian服务互操作</li> |
| </ul> |
| <h2 id="依赖">依赖</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>com.caucho<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>hessian<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>4.0.7<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h2 id="约束">约束</h2> |
| <ul> |
| <li>参数及返回值需实现 <code>Serializable</code> 接口</li> |
| <li>参数及返回值不能自定义实现 <code>List</code>, <code>Map</code>, <code>Number</code>, <code>Date</code>, <code>Calendar</code> 等接口,只能用 JDK 自带的实现,因为 hessian 会做特殊处理,自定义实现类中的属性值都会丢失。</li> |
| </ul> |
| <h2 id="配置">配置</h2> |
| <p>定义 hessian 协议:</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;hessian&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>设置默认协议:</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:provider</span> protocol=<span style="color:#2aa198">&#34;hessian&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>设置 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> protocol=<span style="color:#2aa198">&#34;hessian&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>多端口:</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> id=<span style="color:#2aa198">&#34;hessian1&#34;</span> name=<span style="color:#2aa198">&#34;hessian&#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 style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;hessian2&#34;</span> name=<span style="color:#2aa198">&#34;hessian&#34;</span> port=<span style="color:#2aa198">&#34;8081&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>直连:</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;helloService&#34;</span> interface=<span style="color:#2aa198">&#34;HelloWorld&#34;</span> url=<span style="color:#2aa198">&#34;hessian://10.20.153.10:8080/helloWorld&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p><a href="http://hessian.caucho.com">Hessian</a> 是 Caucho 开源的一个 RPC 框架,其通讯效率高于 WebService 和 Java 自带的序列化。&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: redis 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/redis/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/redis/</guid><description> |
| <p>基于 Redis <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> 实现的 RPC 协议。</p> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">提示</h4> |
| <code>2.3.0</code> 以上版本支持 |
| </div> |
| <h2 id="注册-redis-服务的地址">注册 redis 服务的地址</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-java" data-lang="java"><span style="display:flex;"><span>RegistryFactory registryFactory <span style="color:#719e07">=</span> ExtensionLoader<span style="color:#719e07">.</span>getExtensionLoader<span style="color:#719e07">(</span>RegistryFactory<span style="color:#719e07">.</span>class<span style="color:#719e07">).</span>getAdaptiveExtension<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory<span style="color:#719e07">.</span>getRegistry<span style="color:#719e07">(</span>URL<span style="color:#719e07">.</span>valueOf<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span><span style="color:#719e07">));</span> |
| </span></span><span style="display:flex;"><span>registry<span style="color:#719e07">.</span>register<span style="color:#719e07">(</span>URL<span style="color:#719e07">.</span>valueOf<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;redis://10.20.153.11/com.foo.BarService?category=providers&amp;dynamic=false&amp;application=foo&amp;group=member&amp;loadbalance=consistenthash&#34;</span><span style="color:#719e07">));</span> |
| </span></span></code></pre></div><h2 id="在客户端引用">在客户端引用</h2> |
| <p>在客户端使用 <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;store&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> group=<span style="color:#2aa198">&#34;member&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>或者,点对点直连:</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;store&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>也可以使用自定义接口:</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;store&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.StoreService&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>方法名建议和 redis 的标准方法名相同,即:get(key), set(key, value), delete(key)。</p> |
| <p>如果方法名和 redis 的标准方法名不相同,则需要配置映射关系 <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> p:set=<span style="color:#2aa198">&#34;putFoo&#34;</span> p:get=<span style="color:#2aa198">&#34;getFoo&#34;</span> p:delete=<span style="color:#2aa198">&#34;removeFoo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p><a href="http://redis.io">Redis</a> 是一个高效的 KV 存储服务器&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>不需要感知 Redis 的地址&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>其中 &ldquo;p:xxx&rdquo; 为 spring 的标准 p 标签&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: thrift 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/thrift/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/thrift/</guid><description> |
| <p>当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> 的扩展,在原生协议的基础上添加了一些额外的头信息,比如 service name,magic number 等。</p> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">提示</h4> |
| <code>2.3.0</code> 以上版本支持 |
| </div> |
| <p>使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码,后续版本中会在这方面做一些增强。</p> |
| <h2 id="依赖">依赖</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.thrift<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>libthrift<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>0.8.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h2 id="配置">配置</h2> |
| <p>所有服务共用一个端口 <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;thrift&#34;</span> port=<span style="color:#2aa198">&#34;3030&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h2 id="使用">使用</h2> |
| <p>可以参考 <a href="https://github.com/apache/dubbo/tree/master/dubbo-rpc/dubbo-rpc-thrift/src/test/java/org/apache/dubbo/rpc/protocol/thrift">dubbo 项目中的示例代码</a></p> |
| <h2 id="常见问题">常见问题</h2> |
| <ul> |
| <li>Thrift 不支持 null 值,即:不能在协议中传递 null 值</li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p><a href="http://thrift.apache.org">Thrift</a> 是 Facebook 捐给 Apache 的一个 RPC 框架&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>与原生Thrift不兼容&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: gRPC 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/grpc/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/grpc/</guid><description> |
| <p>Dubbo 自 2.7.5 版本开始支持 gRPC 协议,对于计划使用 HTTP/2 通信,或者想利用 gRPC 带来的 Stream、反压、Reactive 编程等能力的开发者来说, |
| 都可以考虑启用 gRPC 协议。</p> |
| <h2 id="支持-grpc-的好处">支持 gRPC 的好处</h2> |
| <ul> |
| <li>为期望使用 gRPC 协议的用户带来服务治理能力,方便接入 Dubbo 体系</li> |
| <li>用户可以使用 Dubbo 风格的,基于接口的编程风格来定义和使用远程服务</li> |
| </ul> |
| <h2 id="如何在-dubbo-中使用-grpc">如何在 Dubbo 中使用 gRPC</h2> |
| <p>大概需要以下步骤:</p> |
| <ol> |
| <li>使用 IDL 定义服务</li> |
| <li>配置 compiler 插件,本地预编译</li> |
| <li>配置暴露/引用 Dubbo 服务</li> |
| </ol> |
| <p>具体可参见以下<a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc">示例</a></p> |
| <p>除了原生 StreamObserver 接口类型之外,Dubbo 还支持 <a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc/dubbo-samples-rxjava">RxJava</a>、<a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc/dubbo-samples-reactor">Reactor</a> 编程风格的 API</p></description></item><item><title>Docsv2.7: memcached 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/memcached/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/memcached/</guid><description> |
| <p>基于 memcached <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> 实现的 RPC 协议。</p> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">提示</h4> |
| <code>2.3.0</code> 以上版本支持 |
| </div> |
| <h2 id="注册-memcached-服务的地址">注册 memcached 服务的地址</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-java" data-lang="java"><span style="display:flex;"><span>RegistryFactory registryFactory <span style="color:#719e07">=</span> ExtensionLoader<span style="color:#719e07">.</span>getExtensionLoader<span style="color:#719e07">(</span>RegistryFactory<span style="color:#719e07">.</span>class<span style="color:#719e07">).</span>getAdaptiveExtension<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory<span style="color:#719e07">.</span>getRegistry<span style="color:#719e07">(</span>URL<span style="color:#719e07">.</span>valueOf<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span><span style="color:#719e07">));</span> |
| </span></span><span style="display:flex;"><span>registry<span style="color:#719e07">.</span>register<span style="color:#719e07">(</span>URL<span style="color:#719e07">.</span>valueOf<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;memcached://10.20.153.11/com.foo.BarService?category=providers&amp;dynamic=false&amp;application=foo&amp;group=member&amp;loadbalance=consistenthash&#34;</span><span style="color:#719e07">));</span> |
| </span></span></code></pre></div><h2 id="在客户端引用">在客户端引用</h2> |
| <p>在客户端使用 <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> group=<span style="color:#2aa198">&#34;member&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>或者,点对点直连:</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;cache&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>也可以使用自定义接口:</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;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>方法名建议和 memcached 的标准方法名相同,即:get(key), set(key, value), delete(key)。</p> |
| <p>如果方法名和 memcached 的标准方法名不相同,则需要配置映射关系 <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> p:set=<span style="color:#2aa198">&#34;putFoo&#34;</span> p:get=<span style="color:#2aa198">&#34;getFoo&#34;</span> p:delete=<span style="color:#2aa198">&#34;removeFoo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p><a href="http://memcached.org/">Memcached</a> 是一个高效的 KV 缓存服务器&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>不需要感知 Memcached 的地址&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>其中 &ldquo;p:xxx&rdquo; 为 spring 的标准 p 标签&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: rmi 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/rmi/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/rmi/</guid><description> |
| <p>RMI 协议采用 JDK 标准的 <code>java.rmi.*</code> 实现,采用阻塞式短连接和 JDK 标准序列化方式。</p> |
| <p>注意:如果正在使用 RMI 提供服务给外部访问 <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>,同时应用里依赖了老的 common-collections 包 <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup> 的情况下,存在反序列化安全风险 <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>。</p> |
| <h2 id="特性">特性</h2> |
| <ul> |
| <li>连接个数:多连接</li> |
| <li>连接方式:短连接</li> |
| <li>传输协议:TCP</li> |
| <li>传输方式:同步传输</li> |
| <li>序列化:Java 标准二进制序列化</li> |
| <li>适用范围:传入传出参数数据包大小混合,消费者与提供者个数差不多,可传文件。</li> |
| <li>适用场景:常规远程服务方法调用,与原生RMI服务互操作</li> |
| </ul> |
| <h2 id="约束">约束</h2> |
| <ul> |
| <li>参数及返回值需实现 <code>Serializable</code> 接口</li> |
| <li>dubbo 配置中的超时时间对 RMI 无效,需使用 java 启动参数设置:<code>-Dsun.rmi.transport.tcp.responseTimeout=3000</code>,参见下面的 RMI 配置</li> |
| </ul> |
| <h2 id="dubboproperties-配置">dubbo.properties 配置</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-properties" data-lang="properties"><span style="display:flex;"><span>dubbo.service.protocol<span style="color:#719e07">=</span><span style="color:#2aa198">rmi</span> |
| </span></span></code></pre></div><h2 id="rmi配置">RMI配置</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-sh" data-lang="sh"><span style="display:flex;"><span>java -Dsun.rmi.transport.tcp.responseTimeout<span style="color:#719e07">=</span><span style="color:#2aa198">3000</span> |
| </span></span></code></pre></div><p>更多 RMI 优化参数请查看 <a href="https://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html">JDK 文档</a></p> |
| <h2 id="接口">接口</h2> |
| <p>如果服务接口继承了 <code>java.rmi.Remote</code> 接口,可以和原生 RMI 互操作,即:</p> |
| <ul> |
| <li>提供者用 Dubbo 的 RMI 协议暴露服务,消费者直接用标准 RMI 接口调用,</li> |
| <li>或者提供方用标准 RMI 暴露服务,消费方用 Dubbo 的 RMI 协议调用。</li> |
| </ul> |
| <p>如果服务接口没有继承 <code>java.rmi.Remote</code> 接口:</p> |
| <ul> |
| <li>缺省 Dubbo 将自动生成一个 <code>com.xxx.XxxService$Remote</code> 的接口,并继承 <code>java.rmi.Remote</code> 接口,并以此接口暴露服务,</li> |
| <li>但如果设置了 <code>&lt;dubbo:protocol name=&quot;rmi&quot; codec=&quot;spring&quot; /&gt;</code>,将不生成 <code>$Remote</code> 接口,而使用 Spring 的 <code>RmiInvocationHandler</code> 接口暴露服务,和 Spring 兼容。</li> |
| </ul> |
| <h2 id="配置">配置</h2> |
| <p>定义 RMI 协议:</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;rmi&#34;</span> port=<span style="color:#2aa198">&#34;1099&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>设置默认协议:</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:provider</span> protocol=<span style="color:#2aa198">&#34;rmi&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>设置服务协议:</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> protocol=<span style="color:#2aa198">&#34;rmi&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>多端口:</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> id=<span style="color:#2aa198">&#34;rmi1&#34;</span> name=<span style="color:#2aa198">&#34;rmi&#34;</span> port=<span style="color:#2aa198">&#34;1099&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;rmi2&#34;</span> name=<span style="color:#2aa198">&#34;rmi&#34;</span> port=<span style="color:#2aa198">&#34;2099&#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;dubbo:service</span> protocol=<span style="color:#2aa198">&#34;rmi1&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Spring 兼容性:</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;rmi&#34;</span> codec=<span style="color:#2aa198">&#34;spring&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>公司内网环境应该不会有攻击风险&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>dubbo 不会依赖这个包,请排查自己的应用有没有使用&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>请检查应用:将 commons-collections3 请升级到 <a href="https://commons.apache.org/proper/commons-collections/release_3_2_2.html">3.2.2</a>;将 commons-collections4 请升级到 <a href="https://commons.apache.org/proper/commons-collections/release_4_1.html">4.1</a>。新版本的 commons-collections 解决了该问题&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docsv2.7: webservice 协议</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/webservice/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/references/protocol/webservice/</guid><description> |
| <p>基于 WebService 的远程调用协议,基于 <a href="http://cxf.apache.org">Apache CXF</a> <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> 的 <code>frontend-simple</code> 和 <code>transports-http</code> 实现。</p> |
| <div class="alert alert-primary" role="alert"> |
| <h4 class="alert-heading">提示</h4> |
| <code>2.3.0</code> 以上版本支持 |
| </div> |
| <p>可以和原生 WebService 服务互操作,即:</p> |
| <ul> |
| <li>提供者用 Dubbo 的 WebService 协议暴露服务,消费者直接用标准 WebService 接口调用,</li> |
| <li>或者提供方用标准 WebService 暴露服务,消费方用 Dubbo 的 WebService 协议调用。</li> |
| </ul> |
| <h2 id="依赖">依赖</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.cxf<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>cxf-rt-frontend-simple<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>2.6.1<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.cxf<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>cxf-rt-transports-http<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>2.6.1<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h2 id="特性">特性</h2> |
| <ul> |
| <li>连接个数:多连接</li> |
| <li>连接方式:短连接</li> |
| <li>传输协议:HTTP</li> |
| <li>传输方式:同步传输</li> |
| <li>序列化:SOAP 文本序列化</li> |
| <li>适用场景:系统集成,跨语言调用</li> |
| </ul> |
| <h2 id="约束">约束</h2> |
| <ul> |
| <li>参数及返回值需实现 <code>Serializable</code> 接口</li> |
| <li>参数尽量使用基本类型和 POJO</li> |
| </ul> |
| <h2 id="配置">配置</h2> |
| <p>配置协议:</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;webservice&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置默认协议:</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:provider</span> protocol=<span style="color:#2aa198">&#34;webservice&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置服务协议:</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> protocol=<span style="color:#2aa198">&#34;webservice&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>多端口:</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> id=<span style="color:#2aa198">&#34;webservice1&#34;</span> name=<span style="color:#2aa198">&#34;webservice&#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 style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;webservice2&#34;</span> name=<span style="color:#2aa198">&#34;webservice&#34;</span> port=<span style="color:#2aa198">&#34;8081&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>直连:</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;helloService&#34;</span> interface=<span style="color:#2aa198">&#34;HelloWorld&#34;</span> url=<span style="color:#2aa198">&#34;webservice://10.20.153.10:8080/com.foo.HelloWorld&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>WSDL:</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://10.20.153.10:8080/com.foo.HelloWorld?wsdl |
| </span></span></code></pre></div><p>Jetty 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> ... server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Servlet Bridge 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> ... server=<span style="color:#2aa198">&#34;servlet&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>配置 DispatcherServlet:</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&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<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 style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<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></code></pre></div><p>注意,如果使用 servlet 派发请求:</p> |
| <ul> |
| <li>协议的端口 <code>&lt;dubbo:protocol port=&quot;8080&quot; /&gt;</code> 必须与 servlet 容器的端口相同,</li> |
| <li>协议的上下文路径 <code>&lt;dubbo:protocol contextpath=&quot;foo&quot; /&gt;</code> 必须与 servlet 应用的上下文路径相同。</li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>CXF 是 Apache 开源的一个 RPC 框架,由 Xfire 和 Celtix 合并而来&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item></channel></rss> |