| <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/versions/</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/versions/index.xml" rel="self" type="application/rss+xml"/><item><title>Docsv2.7: 升级与可能的兼容性问题总结</title><link>https://dubbo.apache.org/zh-cn/docsv2.7/user/versions/version-270/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/zh-cn/docsv2.7/user/versions/version-270/</guid><description> |
| <p>环境要求:需要<strong>Java 8</strong>及以上版本。</p> |
| <p>2.7.0版本在改造的过程中遵循了一个原则,即<strong>保持与低版本的兼容性,因此从功能层面来说它是与2.6.x及更低版本完全兼容的</strong>,而接下来将要提到的兼容性问题主要是<a href="#1.1">包重命名</a>带来的。另外,虽然功能用法保持向后兼容,但参考本文能帮助您尽快用到2.7.0版本的新特性。</p> |
| <h2 id="升级步骤">升级步骤</h2> |
| <ol> |
| <li>升级pom到2.7.0(以all-in-one依赖为例)。</li> |
| </ol> |
| <div class="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;properties&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dubbo.version&gt;</span>2.7.0<span style="color:#268bd2">&lt;/dubbo.version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/properties&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dependencyManagement&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;dependencies&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.dubbo<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-dependencies-bom<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>${dubbo.version}<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;type&gt;</span>pom<span style="color:#268bd2">&lt;/type&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;scope&gt;</span>import<span style="color:#268bd2">&lt;/scope&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;/dependencies&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependencyManagement&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dependencies&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.dubbo<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>${dubbo.version}<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>io.netty<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>netty-all<span style="color:#268bd2">&lt;/artifactId&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;/dependencies&gt;</span> |
| </span></span></code></pre></div><p>如果升级依赖后出现API或SPI扩展相关的编译错误,请参考<a href="#1.1">包兼容性问题</a></p> |
| <p>此时重新部署应用,所有默认行为和2.6.x保持一致,如果要用到2.7的新特性,则需要继续做以下配置(可选):</p> |
| <ul> |
| <li>简化的URL</li> |
| <li>配置元数据中心</li> |
| <li>使用外部化配置</li> |
| <li>服务治理规则</li> |
| <li>使用异步API</li> |
| </ul> |
| <p>下面我们就对这几部分的配置分别做详细说明。</p> |
| <h4 id="简化的url">简化的URL</h4> |
| <div class="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;!-- simplified=&#34;true&#34;表示注册简化版的URL到Registry --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:registry</span> address=<span style="color:#2aa198">&#34;zookeeper://127.0.0.1:2181&#34;</span> simplified=<span style="color:#2aa198">&#34;true&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-properties" data-lang="properties"><span style="display:flex;"><span>dubbo.registry.simplified<span style="color:#719e07">=</span><span style="color:#2aa198">true</span> |
| </span></span></code></pre></div><p>建议将此配置集中管理,参考<a href="#1.2">外部化配置</a>。</p> |
| <blockquote> |
| <p>URL简化只是剔除了一些纯粹的查询用的参数,并没有做大刀阔斧的服务发现模型改造,因此精简后的URL完全可以被2.6及以下版本的消费端实现服务发现与调用,同样2.7版本也可以发现和调用低版本的提供者。</p> |
| </blockquote> |
| <h4 id="配置元数据中心">配置元数据中心</h4> |
| <div class="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:metadata-report</span> address=<span style="color:#2aa198">&#34;redis://127.0.0.1:6379&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-properties" data-lang="properties"><span style="display:flex;"><span>dubbo.metadataReport.address<span style="color:#719e07">=</span><span style="color:#2aa198">redis://127.0.0.1:6379</span> |
| </span></span></code></pre></div><p>建议将此配置集中管理,参考<a href="#1.2">外部化配置</a>。 |
| 在此了解更多元数据中心设计目的与用途。</p> |
| <h4 id="1.2">使用外部化配置</h4> |
| 需要在项目启动前,使用[最新版本Dubbo-OPS](https://github.com/apache/dubbo-ops)完成外部化配置迁移,理论上配置中心支持所有本地dubbo.properties所支持的配置项。 |
| <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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:application</span> name=<span style="color:#2aa198">&#34;demo-provider&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:config-center</span> address=<span style="color:#2aa198">&#34;zookeeper://127.0.0.1:2181&#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:registry</span> address=<span style="color:#2aa198">&#34;zookeeper://127.0.0.1:2181&#34;</span> simplified=<span style="color:#2aa198">&#34;true&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:metadata-report</span> address=<span style="color:#2aa198">&#34;redis://127.0.0.1:6379&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20880&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;demoService&#34;</span> class=<span style="color:#2aa198">&#34;org.apache.dubbo.samples.basic.impl.DemoServiceImpl&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.samples.basic.api.DemoService&#34;</span> ref=<span style="color:#2aa198">&#34;demoService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>通过OPS控制台将以下全局配置迁移到配置中心,成为所有应用共享的配置。</p> |
| <div class="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.registry.address<span style="color:#719e07">=</span><span style="color:#2aa198">zookeeper://127.0.0.1:2181</span> |
| </span></span><span style="display:flex;"><span>dubbo.registry.simplified<span style="color:#719e07">=</span><span style="color:#2aa198">true</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>dubbo.metadataReport.address<span style="color:#719e07">=</span><span style="color:#2aa198">redis://127.0.0.1:6379</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>dubbo.protocol.name<span style="color:#719e07">=</span><span style="color:#2aa198">dubbo</span> |
| </span></span><span style="display:flex;"><span>dubbo.protocol.port<span style="color:#719e07">=</span><span style="color:#2aa198">20880</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:application</span> name=<span style="color:#2aa198">&#34;demo-provider&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:config-center</span> address=<span style="color:#2aa198">&#34;zookeeper://127.0.0.1:2181&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;demoService&#34;</span> class=<span style="color:#2aa198">&#34;org.apache.dubbo.samples.basic.impl.DemoServiceImpl&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;org.apache.dubbo.samples.basic.api.DemoService&#34;</span> ref=<span style="color:#2aa198">&#34;demoService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>这里增加了一篇Dubbo配置方式的说明文档,详细描述了Dubbo当前支持的配置类型、不同配置之间的覆盖关系等。</p> |
| <h4 id="服务治理规则迁移">服务治理规则迁移</h4> |
| <p>2.7版本可以读取到老的治理规则,因此不用担心升级2.7的应用后老规则会失效,可以选择先升级上线,再慢慢的做增量式规则迁移。</p> |
| <p>请参考OPS -&gt; 服务治理了解规则配置方式,这里我们重点关注的是规则格式,以下提供几个简单示例:</p> |
| <ul> |
| <li> |
| <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-yaml" data-lang="yaml"><span style="display:flex;"><span>--- |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">scope</span>: application |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">force</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">runtime</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">enabled</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">key</span>: governance-conditionrouter-consumer |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">conditions</span>: |
| </span></span><span style="display:flex;"><span> - application=app1 =&gt; address=*:20880 |
| </span></span><span style="display:flex;"><span> - application=app2 =&gt; address=*:20881 |
| </span></span><span style="display:flex;"><span>... |
| </span></span></code></pre></div></li> |
| <li> |
| <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-yaml" data-lang="yaml"><span style="display:flex;"><span>--- |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">force</span>: <span style="color:#cb4b16">false</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">runtime</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">enabled</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">key</span>: governance-tagrouter-provider |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">tags</span>: |
| </span></span><span style="display:flex;"><span> - <span style="color:#268bd2">name</span>: tag1 |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">addresses</span>: [<span style="color:#2aa198">&#34;127.0.0.1:20880&#34;</span>] |
| </span></span><span style="display:flex;"><span> - <span style="color:#268bd2">name</span>: tag2 |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">addresses</span>: [<span style="color:#2aa198">&#34;127.0.0.1:20881&#34;</span>] |
| </span></span><span style="display:flex;"><span>... |
| </span></span></code></pre></div></li> |
| <li> |
| <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-yaml" data-lang="yaml"><span style="display:flex;"><span>--- |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">scope</span>: service |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">key</span>: org.apache.dubbo.samples.governance.api.DemoService |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">enabled</span>: <span style="color:#cb4b16">true</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">configs</span>: |
| </span></span><span style="display:flex;"><span>- <span style="color:#268bd2">addresses</span>: [<span style="color:#2aa198">0.0.0.0</span>] |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">side</span>: consumer |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">parameters</span>: |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">timeout</span>: <span style="color:#2aa198">6000</span> |
| </span></span><span style="display:flex;"><span>... |
| </span></span></code></pre></div></li> |
| </ul> |
| <p>关于治理规则更多详细说明,请参考<a href="../../examples/routing-rule">路由规则</a>和<a href="../../examples/config-rule">覆盖规则</a>用户文档。</p> |
| <p>也可继续了解<a href="https://github.com/apache/dubbo-samples/tree/master/4-governance">使用示例</a>。</p> |
| <h4 id="使用异步api">使用异步API</h4> |
| <p>这部分的接口和低版本同样是完全兼容的,你仅须在打算使用CompletableFuture<T>提供的回调或者异步组装能力时,再考虑升级这部分内容即可。</p> |
| <ul> |
| <li> |
| <p>定义CompletableFuture<T>类型接口</p> |
| </li> |
| <li> |
| <p>同步签名接口实现Provider端异步执行</p> |
| </li> |
| <li> |
| <p>感知异步返回值的Filter链路</p> |
| </li> |
| </ul> |
| <p>点击链接,了解关于异步API如何使用的更多使用示例。</p> |
| <h4 id="1.1">包名改造</h4> |
| 1. Maven坐标 |
| <p><strong>groupId 由 <code>com.alibaba</code> 改为 <code>org.apache.dubbo</code></strong></p> |
| <ol start="2"> |
| <li>package</li> |
| </ol> |
| <p><strong>package 由 <code>com.alibaba.dubbo</code> 改为 <code>org.apache.dubbo</code></strong></p> |
| <p>Maven坐标升级比较直观,只需要修改相应的pom文件就可以了;而package变更则可能会带来编译问题,升级过程需要用户修改代码。因此为了减少用户升级成本,让用户可以做到渐进式升级,2.7.0版本继续保留了一些常用基础API和SPI<code>com.alibaba.dubbo</code>的支持。</p> |
| <h4 id="api编程接口">API编程接口</h4> |
| <ul> |
| <li>注解</li> |
| </ul> |
| <table> |
| <thead> |
| <tr> |
| <th>注解</th> |
| <th>说明</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>@Reference</td> |
| <td>消费端服务引用注解</td> |
| </tr> |
| <tr> |
| <td>@Service</td> |
| <td>提供端服务暴露注解</td> |
| </tr> |
| <tr> |
| <td>@EnableDubbo</td> |
| <td></td> |
| </tr> |
| <tr> |
| <td>其他常用Spring注解API</td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| <ul> |
| <li>编程API</li> |
| </ul> |
| <table> |
| <thead> |
| <tr> |
| <th>API</th> |
| <th>说明</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>ReferenceConfig</td> |
| <td>Service配置采集和引用编程接口</td> |
| </tr> |
| <tr> |
| <td>ServiceConfig</td> |
| <td>Service配置采集和暴露编程接口</td> |
| </tr> |
| <tr> |
| <td>ApplicationConfig</td> |
| <td>Application配置采集API</td> |
| </tr> |
| <tr> |
| <td>RegistryConfig</td> |
| <td>注册中心配置采集API</td> |
| </tr> |
| <tr> |
| <td>ConsumerConfig</td> |
| <td>消费端默认配置采集API</td> |
| </tr> |
| <tr> |
| <td>ProviderConfig</td> |
| <td>提供端默认配置采集API</td> |
| </tr> |
| <tr> |
| <td>ProtocolConfig</td> |
| <td>RPC协议配置采集API</td> |
| </tr> |
| <tr> |
| <td>ArgumentConfig</td> |
| <td>服务参数级配置采集API</td> |
| </tr> |
| <tr> |
| <td>MethodConfig</td> |
| <td>服务方法级配置采集API</td> |
| </tr> |
| <tr> |
| <td>ModuleConfig</td> |
| <td>服务治理Module配置采集API</td> |
| </tr> |
| <tr> |
| <td>MonitorConfig</td> |
| <td>监控配置采集API</td> |
| </tr> |
| <tr> |
| <td>RpcContext</td> |
| <td>编程上下文API</td> |
| </tr> |
| </tbody> |
| </table> |
| <h4 id="spi扩展">SPI扩展</h4> |
| <blockquote> |
| <p>如果公司内部有维护的自定义SPI扩展库,在业务工程升级到2.7.0之前,请务必先确保扩展库与2.7.0的兼容性。如果发现有兼容性问题,请通过修改包名引用的方式完成升级,并重新打包。</p> |
| </blockquote> |
| <table> |
| <thead> |
| <tr> |
| <th>SPI扩展点</th> |
| <th>说明</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Registry</td> |
| <td>包括<code>RegistryFactory</code>, <code>Registry</code> ,<code>RegistryService</code>等扩展点</td> |
| </tr> |
| <tr> |
| <td>Protocol</td> |
| <td>RPC协议扩展</td> |
| </tr> |
| <tr> |
| <td>Serialization</td> |
| <td>序列化协议扩展</td> |
| </tr> |
| <tr> |
| <td>Cluster</td> |
| <td>集群容错策略扩展,如Failover, Failfast等</td> |
| </tr> |
| <tr> |
| <td>Loadbalance</td> |
| <td>负载均衡策略扩展</td> |
| </tr> |
| <tr> |
| <td>Transporter</td> |
| <td>传输框架扩展,如Netty等</td> |
| </tr> |
| <tr> |
| <td>Monitor</td> |
| <td>监控中心扩展,包括MonitorFactory, Monitor, MonitorService等</td> |
| </tr> |
| <tr> |
| <td>Router</td> |
| <td>路由规则扩展</td> |
| </tr> |
| <tr> |
| <td>Filter</td> |
| <td>拦截器扩展</td> |
| </tr> |
| </tbody> |
| </table> |
| <h2 id="faq">FAQ</h2> |
| <ol> |
| <li>升级后启动出现curator依赖报错</li> |
| </ol></description></item></channel></rss> |