升级与可能的兼容性问题总结

环境要求：需要Java 8及以上版本。

2.7.0版本在改造的过程中遵循了一个原则，即保持与低版本的兼容性，因此从功能层面来说它是与2.6.x及更低版本完全兼容的，而接下来将要提到的兼容性问题主要是包重命名带来的。另外，虽然功能用法保持向后兼容，但参考本文能帮助您尽快用到2.7.0版本的新特性。

升级步骤

1. 升级pom到2.7.0（以all-in-one依赖为例）。

<properties>
    <dubbo.version>2.7.0</dubbo.version>
</properties>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.dubbo</groupId>
            <artifactId>dubbo-dependencies-bom</artifactId>
            <version>${dubbo.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.apache.dubbo</groupId>
        <artifactId>dubbo</artifactId>
        <version>${dubbo.version}</version>
    </dependency>
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-all</artifactId>
    </dependency>
</dependencies>

如果升级依赖后出现API或SPI扩展相关的编译错误，请参考包兼容性问题

此时重新部署应用，所有默认行为和2.6.x保持一致，如果要用到2.7的新特性，则需要继续做以下配置（可选）：

• 简化的URL
• 配置元数据中心
• 使用外部化配置
• 服务治理规则
• 使用异步API

下面我们就对这几部分的配置分别做详细说明。

简化的URL

<!-- simplified="true"表示注册简化版的URL到Registry -->
<dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>

dubbo.registry.simplified=true

建议将此配置集中管理，参考外部化配置。

URL简化只是剔除了一些纯粹的查询用的参数，并没有做大刀阔斧的服务发现模型改造，因此精简后的URL完全可以被2.6及以下版本的消费端实现服务发现与调用，同样2.7版本也可以发现和调用低版本的提供者。

配置元数据中心

<dubbo:metadata-report address="redis://127.0.0.1:6379"/>

dubbo.metadataReport.address=redis://127.0.0.1:6379

建议将此配置集中管理，参考外部化配置。 在此了解更多元数据中心设计目的与用途。

使用外部化配置

需要在项目启动前，使用[最新版本Dubbo-OPS](https://github.com/apache/dubbo-ops)完成外部化配置迁移，理论上配置中心支持所有本地dubbo.properties所支持的配置项。

以XML开发形式为例，假设我们本地有如下配置：

<dubbo:application name="demo-provider"/>
<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
<dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
<dubbo:metadata-report address="redis://127.0.0.1:6379"/>
<dubbo:protocol name="dubbo" port="20880"/>
<bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
<dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>

通过OPS控制台将以下全局配置迁移到配置中心，成为所有应用共享的配置。

dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.registry.simplified=true
dubbo.metadataReport.address=redis://127.0.0.1:6379
dubbo.protocol.name=dubbo
dubbo.protocol.port=20880

这样应用开发者只需要关心配置中心的配置。

<dubbo:application name="demo-provider"/>
<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
<bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
<dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>

这里增加了一篇Dubbo配置方式的说明文档，详细描述了Dubbo当前支持的配置类型、不同配置之间的覆盖关系等。

服务治理规则迁移

2.7版本可以读取到老的治理规则，因此不用担心升级2.7的应用后老规则会失效，可以选择先升级上线，再慢慢的做增量式规则迁移。

请参考OPS -> 服务治理了解规则配置方式，这里我们重点关注的是规则格式，以下提供几个简单示例：

• 条件路由

  ---
  scope: application
  force: true
  runtime: true
  enabled: true
  key: governance-conditionrouter-consumer
  conditions:
    - application=app1 => address=*:20880
    - application=app2 => address=*:20881
  ...

• 标签路由

  ---
  force: false
  runtime: true
  enabled: true
  key: governance-tagrouter-provider
  tags:
    - name: tag1
      addresses: ["127.0.0.1:20880"]
    - name: tag2
      addresses: ["127.0.0.1:20881"]
  ...

• 动态配置（覆盖规则）

  ---
  scope: service
  key: org.apache.dubbo.samples.governance.api.DemoService
  enabled: true
  configs:
  - addresses: [0.0.0.0]
    side: consumer
    parameters:
      timeout: 6000
  ...

关于治理规则更多详细说明，请参考路由规则和覆盖规则用户文档。

也可继续了解使用示例。

使用异步API

这部分的接口和低版本同样是完全兼容的，你仅须在打算使用CompletableFuture提供的回调或者异步组装能力时，再考虑升级这部分内容即可。

• 定义CompletableFuture类型接口

• 同步签名接口实现Provider端异步执行

• 感知异步返回值的Filter链路

点击链接，了解关于异步API如何使用的更多使用示例。

包名改造

1. Maven坐标

groupId 由 com.alibaba 改为 org.apache.dubbo

1. package

package 由 com.alibaba.dubbo 改为 org.apache.dubbo

Maven坐标升级比较直观，只需要修改相应的pom文件就可以了；而package变更则可能会带来编译问题，升级过程需要用户修改代码。因此为了减少用户升级成本，让用户可以做到渐进式升级，2.7.0版本继续保留了一些常用基础API和SPIcom.alibaba.dubbo的支持。

API编程接口

• 注解

• 编程API

SPI扩展

如果公司内部有维护的自定义SPI扩展库，在业务工程升级到2.7.0之前，请务必先确保扩展库与2.7.0的兼容性。如果发现有兼容性问题，请通过修改包名引用的方式完成升级，并重新打包。

FAQ

1. 升级后启动出现curator依赖报错