You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by li...@apache.org on 2019/01/25 04:34:53 UTC
[incubator-dubbo-website] branch asf-site updated: Add blog: guides
for upgrading to 2.7.0
This is an automated email from the ASF dual-hosted git repository.
liujun pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-dubbo-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 907868c Add blog: guides for upgrading to 2.7.0
907868c is described below
commit 907868cb3a17d51874442f16f1e208be3a28fe96
Author: ken.lj <ke...@gmail.com>
AuthorDate: Fri Jan 25 12:34:27 2019 +0800
Add blog: guides for upgrading to 2.7.0
---
blog/zh-cn/Guides for upgrading to 2.7.x.md | 281 ++++++++++++++++++++++++++++
1 file changed, 281 insertions(+)
diff --git a/blog/zh-cn/Guides for upgrading to 2.7.x.md b/blog/zh-cn/Guides for upgrading to 2.7.x.md
new file mode 100644
index 0000000..c7299cf
--- /dev/null
+++ b/blog/zh-cn/Guides for upgrading to 2.7.x.md
@@ -0,0 +1,281 @@
+# 升级与可能的兼容性问题总结
+
+环境要求：需要Java 8及以上版本。
+
+2.7.0版本在改造的过程中遵循了一个原则，即**保持与低版本的兼容性，因此从功能层面来说它是与2.6.x及更低版本完全兼容的**。既然功能都兼容，那这里所说的兼容性主要是指什么那？兼容性其实主要是和[包重命名]()相关的，我们接下来会详细说明影响点。另外，虽然功能用法保持向后兼容，但为了使用者能尽快升级到2.7.0版本的使用方式，文章最后还补充了关于如何从老版本的用法逐步迁移到新版本用法。
+
+## 升级步骤
+
+1. 升级pom到2.7.0（使用all-in-one依赖）。
+
+```xml
+<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
+
+ ```xml
+<!-- simplified="true"表示注册简化版的URL到Registry -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
+```
+
+ ```properties
+dubbo.registry.simplified=true
+```
+
+建议将此配置集中管理，参考[外部化配置](#使用外部化配置)。
+
+> URL简化只是剔除了一些纯粹的查询用的参数，并没有做大刀阔斧的服务发现模型改造，因此精简后的URL完全可以被2.6及以下版本的消费端实现服务发现与调用，同样2.7版本也可以发现和调用低版本的提供者。
+
+
+
+#### 配置元数据中心
+
+ ```xml
+<dubbo:metadata-report address="redis://127.0.0.1:6379"/>
+```
+
+ ```properties
+dubbo.metadataReport.address=redis://127.0.0.1:6379
+```
+
+建议将此配置集中管理，参考[外部化配置](#使用外部化配置)。
+
+
+
+#### 使用外部化配置
+
+在项目启动前，使用[最新版本Dubbo-OPS](https://github.com/apache/incubator-dubbo-ops)完成Dubbo配置，理论上支持所有本地dubbo.properties所支持的配置项。
+
+以XML开发形式为例，假设我们本地有如下配置：
+
+```xml
+<dubbo:application name="demo-provider"/>
+<dubbo:conig-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控制台](http://47.91.207.147/#/management?key=global)将以下全局配置迁移到配置中心，成为所有应用共享的配置。
+
+```properties
+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
+```
+
+这样应用开发者只需要关心配置中心的配置。
+
+```xml
+<dubbo:application name="demo-provider"/>
+<dubbo:conig-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 -> 服务治理](http://47.91.207.147/#/governance/routingRule)了解规则配置方式，这里我们重点关注的是规则格式，以下提供几个简单示例：
+
+- 条件路由
+
+ ```yaml
+ ---
+ scope: application
+ force: true
+ runtime: true
+ enabled: true
+ key: governance-conditionrouter-consumer
+ conditions:
+ - method=sayHello => address=*:20880
+ - method=sayHi => address=*:20881
+ ...
+ ```
+
+
+
+- 标签路由
+
+ ```yaml
+ ---
+ 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"]
+ ...
+ ```
+
+
+
+- 动态配置（覆盖规则）
+
+ ```yaml
+ ---
+ 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<T>提供的回调或者异步组装能力时，再考虑升级这部分内容。
+
+- 定义CompletableFuture<T>类型接口
+- 同步签名接口实现Provider端异步执行
+
+- 感知异步返回值的Filter链路
+
+
+
+ [使用示例]()。
+
+
+
+## 包名改造
+
+1. Maven坐标
+
+groupId 由 `com.alibaba` 改为 `org.apache.dubbo`
+
+2. package
+
+package 由 `com.alibaba.dubbo` 改为 `org.apache.dubbo`
+
+
+
+Maven坐标升级比较直观，只需要修改相应的pom文件就可以了；而package变更则可能会带来编译问题，升级过程需要用户修改代码。因此为了减少用户升级成本，让用户可以做到渐进式升级，2.7.0版本继续保留了一些常用基础API和SP`com.alibaba.dubb`的支持。
+
+#### API编程接口
+
+- 注解
+
+| 注解 | 说明 |
+| --------------------- | ------------------ |
+| @Reference | 消费端服务引用注解 |
+| @Service | 提供端服务暴露注解 |
+| @EnableDubbo | |
+| 其他常用Spring注解API | |
+
+
+
+- 编程API
+
+| API | 说明 |
+| ----------------- | ----------------------------- |
+| ReferenceConfig | Service配置采集和引用编程接口 |
+| ServiceConfig | Service配置采集和暴露编程接口 |
+| ApplicationConfig | Application配置采集API |
+| RegistryConfig | 注册中心配置采集API |
+| ConsumerConfig | 提供端默认配置采集API |
+| ProviderConfig | 消费端默认配置采集API |
+| ProtocolConfig | RPC协议配置采集API |
+| ArcumentConfig | 服务参数级配置采集API |
+| MethodConfig | 服务方法级配置采集API |
+| ModuleConfig | 服务治理Module配置采集API |
+| MonitorConfig | 监控配置采集API |
+| RpcContext | 编程上下文API |
+
+
+
+#### SPI扩展
+
+> 如果公司内部有维护的自定义SPI扩展库，在业务工程升级到2.7.0之前，请务必先确保扩展库与2.7.0的兼容性。如果发现有兼容性问题，请通过修改包名引用的方式完成升级，并重新打包。
+
+
+
+| SPI扩展点 | 说明 |
+| ------------- | ------------------------------------------------------------ |
+| Registry | 包括`RegistryFactory`, `Registry` ,`RegistryService`等扩展点 |
+| Protocol | RPC协议扩展 |
+| Serialization | 序列化协议扩展 |
+| Cluster | 集群容错策略扩展，如Failover, Failfast等 |
+| Loadbalance | 负载均衡策略扩展 |
+| Transporter | 传输框架扩展，如Netty等 |
+| Monitor | 监控中心扩展，包括MonitorFactory, Monitor, MonitorService等 |
+| Router | 路由规则扩展 |
+| Filter | 拦截器扩展 |
+
+
+
+## FAQ
+
+1. 升级后启动出现curator依赖报错
+