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

升级到 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) (f2070b3fdd)