| <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></span><span style="display:flex;"><span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>然后，开发服务的实现：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>上面的实现非常简单，但是由于该 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-gdscript3" data-lang="gdscript3"><span style="display:flex;"><span>http:<span style="color:#719e07">//</span>localhost:<span style="color:#2aa198">8080</span><span style="color:#719e07">/</span>users<span style="color:#719e07">/</span><span style="color:#b58900">load</span>?id<span style="color:#719e07">=</span><span style="color:#2aa198">1001</span> |
| </span></span></code></pre></div><p>JAX-RS本身可以支持所有这些形式。但是上面那种在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:#2aa198">&#34;/{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>@GET：指定用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:#2aa198">&#34;/users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>在一般应用中，我们建议将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>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>或者也可以直接用字符串（还支持通配符）表示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:#2aa198">&#34;application/json&#34;</span>, <span style="color:#2aa198">&#34;text/xml&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>如果所有方法都支持同样类型的输入输出数据格式，则我们无需在每个方法上做配置，只需要在服务类上添加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:#2aa198">&#34;/users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>在一个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:#2aa198">&#34;application/json; charset=UTF-8&#34;</span>, <span style="color:#2aa198">&#34;text/xml; charset=UTF-8&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>为了方便用户，我们在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>({ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><h3 id="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></span><span style="display:flex;"><span> <span style="color:#586e75">// ...</span> |
| </span></span><span style="display:flex;"><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>(User user); |
| </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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> Long id; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">RegistrationResult</span>() { |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">RegistrationResult</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Long <span style="color:#268bd2">getId</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">setId</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>并修改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>(User user); |
| </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>(XmlAccessType.FIELD) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@XmlElement</span>(name<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>定制对象属性映射到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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@JsonProperty</span>(<span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>更多资料请参考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:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id, <span style="color:#268bd2">@Context</span> HttpServletRequest request) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> request.getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>用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:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRemoteAddressString()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>注意：这种方式只能在设置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> (RpcContext.getContext().getRequest() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getRequest() <span style="color:#719e07">instanceof</span> HttpServletRequest) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> ((HttpServletRequest) RpcContext.getContext().getRequest()).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getResponse() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getResponse() <span style="color:#719e07">instanceof</span> HttpServletResponse) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>注意：为了保持协议的中立性，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> (RpcContext.getContext().getRequest(HttpServletRequest.class) <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRequest(HttpServletRequest.class).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getResponse(HttpServletResponse.class) <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse(HttpServletResponse.class)); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>如果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:#2aa198">&#34;/users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>现在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>(protocol <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;rest&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Autowired</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> UserRepository userRepository; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;/register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType.APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user</span> |
| </span></span><span style="display:flex;"><span> userRepository.save(user); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>annotation的配置更简单更精确，通常也更便于维护（当然现代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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">filter</span>(ContainerRequestContext req, ContainerResponseContext res) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> (req.getMethod().equals(<span style="color:#2aa198">&#34;GET&#34;</span>)) { |
| </span></span><span style="display:flex;"><span> res.getHeaders().add(<span style="color:#2aa198">&#34;Cache-Control&#34;</span>, <span style="color:#2aa198">&#34;someValue&#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Interceptor主要用于访问和修改输入与输出字节流，例如，手动添加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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Override</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">aroundWriteTo</span>(WriterInterceptorContext context) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">throws</span> IOException, WebApplicationException { |
| </span></span><span style="display:flex;"><span> OutputStream outputStream <span style="color:#719e07">=</span> context.getOutputStream(); |
| </span></span><span style="display:flex;"><span> context.setOutputStream(<span style="color:#719e07">new</span> GZIPOutputStream(outputStream)); |
| </span></span><span style="display:flex;"><span> context.proceed(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>在标准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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">filter</span>(ClientRequestContext reqCtx, ClientResponseContext resCtx) <span style="color:#268bd2">throws</span> IOException { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;status: &#34;</span> <span style="color:#719e07">+</span> resCtx.getStatus()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;date: &#34;</span> <span style="color:#719e07">+</span> resCtx.getDate()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;last-modified: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLastModified()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;location: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLocation()); |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;headers:&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (Entry<span style="color:#719e07">&lt;</span>String, List<span style="color:#719e07">&lt;</span>String<span style="color:#719e07">&gt;&gt;</span> header : resCtx.getHeaders().entrySet()) { |
| </span></span><span style="display:flex;"><span> System.out.print(<span style="color:#2aa198">&#34;\t&#34;</span> <span style="color:#719e07">+</span> header.getKey() <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34; :&#34;</span>); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (String value : header.getValue()) { |
| </span></span><span style="display:flex;"><span> System.out.print(value <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34;, &#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> System.out.print(<span style="color:#2aa198">&#34;\n&#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;media-type: &#34;</span> <span style="color:#719e07">+</span> resCtx.getMediaType().getType()); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="添加自定义的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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Response <span style="color:#268bd2">toResponse</span>(NotFoundException e) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.NOT_FOUND).entity(<span style="color:#2aa198">&#34;Oops! the requested resource is not found!&#34;</span>).type(<span style="color:#2aa198">&#34;text/plain&#34;</span>).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>和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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@Min</span>(value<span style="color:#719e07">=</span>1L, message<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;User ID must be greater than 1&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>当然，在很多其他的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></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">protected</span> Response <span style="color:#268bd2">handleConstraintViolationException</span>(ConstraintViolationException cve) { |
| </span></span><span style="display:flex;"><span> ViolationReport report <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ViolationReport(); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (ConstraintViolation cv : cve.getConstraintViolations()) { |
| </span></span><span style="display:flex;"><span> report.addConstraintViolation(<span style="color:#719e07">new</span> RestConstraintViolation( |
| </span></span><span style="display:flex;"><span> cv.getPropertyPath().toString(), |
| </span></span><span style="display:flex;"><span> cv.getMessage(), |
| </span></span><span style="display:flex;"><span> cv.getInvalidValue() <span style="color:#719e07">==</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">?</span> <span style="color:#2aa198">&#34;null&#34;</span> : cv.getInvalidValue().toString())); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// 采用json输出代替xml输出</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>然后将这个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.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory.getRegistry(URL.valueOf(<span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span>)); |
| </span></span><span style="display:flex;"><span>registry.register(URL.valueOf(<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></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.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory.getRegistry(URL.valueOf(<span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span>)); |
| </span></span><span style="display:flex;"><span>registry.register(URL.valueOf(<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></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> |
