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

升级到 2.7.x 的注意事项和兼容性问题总结

环境要求：需要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编程接口

  • 注解
注解说明
@Reference消费端服务引用注解
@Service提供端服务暴露注解
@EnableDubbo
其他常用Spring注解API
  • 编程API
API说明
ReferenceConfigService配置采集和引用编程接口
ServiceConfigService配置采集和暴露编程接口
ApplicationConfigApplication配置采集API
RegistryConfig注册中心配置采集API
ConsumerConfig消费端默认配置采集API
ProviderConfig提供端默认配置采集API
ProtocolConfigRPC协议配置采集API
ArgumentConfig服务参数级配置采集API
MethodConfig服务方法级配置采集API
ModuleConfig服务治理Module配置采集API
MonitorConfig监控配置采集API
RpcContext编程上下文API

SPI扩展

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

SPI扩展点说明
Registry包括RegistryFactory, Registry ,RegistryService等扩展点
ProtocolRPC协议扩展
Serialization序列化协议扩展
Cluster集群容错策略扩展，如Failover, Failfast等
Loadbalance负载均衡策略扩展
Transporter传输框架扩展，如Netty等
Monitor监控中心扩展，包括MonitorFactory, Monitor, MonitorService等
Router路由规则扩展
Filter拦截器扩展

FAQ

  1. 升级后启动出现curator依赖报错
最后修改 March 1, 2023: Add /zh/ docs aliases (#2336) (f2070b3fdd1)