Home

微服务开发框架迁移概述

常见的微服务开发框架包括：

Spring Cloud定义了一套微服务架构模式的抽象，具有丰富的生态，Spring Cloud Netfilx、Spring Cloud Alibaba、Spring Cloud Huawei等提供了Spring Cloud的具体实现。Spring Cloud的RPC框架继承了Spring Boot及其他开源的技术体系，比如OpenFeign的功能。在服务治理领域，Spring Cloud可以适配Netflix、Resilence4j、Sentinel等开源组件。Spring Cloud的开放性得到广大开发者、商业公司的支持和使用。
ServiceComb作为功能完善的微服务框架，包括高性能RPC开发框架，服务注册发现、服务配置管理、和开箱即用的服务治理能力，能够更加快速的搭建成熟的微服务应用。
Apache Dubbo 是一款高性能、轻量级的开源微服务框架，提供了六大核心能力：面向接口代理的高性能RPC调用，智能容错和负载均衡，服务自动注册和发现，高度可扩展能力，运行期流量调度，可视化的服务治理与运维。
HSF在阿里巴巴广泛使用的分布式RPC服务框架。

这些微服务开发框架主要实现了微服务架构模式里面定义的核心设计模式，包括：

微服务之间的RPC通信。
分布式微服务实例和服务发现。
配置外置，动态、集中的配置管理。
提供熔断、隔离、限流、负载均衡等微服务治理能力。

在技术上，这些微服务开发框架都可以基于Spring、Spring Boot运行。共同的技术底座使得可以采用比较简单的方式，将一个微服务开发框架转换为另外一个微服务开发框架。当业务逻辑对微服务开发框架特有功能依赖很重的时候，改造后也会面对一些常见的问题。本文的主要目的是描述如何使用migrator工具，将一个微服务开发框架改造为另外一个微服务开发框架，也介绍了改造后常见的问题及其解决思路。

本文的内容主要参考了如下文献：

HSF 迁移 Spring Cloud

将 HSF 迁移 Spring Cloud，主要需要解决如下几个问题：

将 RPC 接口定义修改为 REST 接口定义；
将 RPC 接口调用修改为 Feign 接口调用；
修改依赖关系和配置文件；
其他常见问题修改，包括启动类修改、解决三方软件冲突等。

详细可以参考HSF迁移Spring Cloud方案分析和最佳实践。

使用 migrator 完成一键式改造

对于多数项目，可以通过migrator一键式完成改造。在后面的章节中，会详细描述migrator是如何做的，即使对于一些特殊的情况，也可以通过给migrator扩充功能，快速满足一键式改造的要求。

使用migrator完成改造，首先需要下载本项目代码，执行

mvn clean install

会在 target 目录编译出 migrator-0.0.1-SNAPSHOT.jar。然后将 migrator-0.0.1-SNAPSHOT.jar 和 templates 目录拷贝到一个程序运行目录，比如 D:\migrator。然后运行：

# 进入target目录或者将 migrator-0.0.1-SNAPSHOT.jar 以及 templates 目录拷贝到另外的目录
cd D:\migrator\target 
java -jar migrator-0.0.1-SNAPSHOT.jar ModifyHSFAction [PROJECT_HOME]

其中PROJECT_HOME是需要改造的项目根目录。程序运行完可以完成一键式修改，一些无法处理的情况，会打印日志，这些情况需要手工处理。比如：

2022-03-17 16:51:35,740 [ERROR] [main] - Manual processing is required. Cause is [Interface definition not valid under @HSFConsumer annotation.].File is [D:\Code\spring-cloud-huawei-samples\migrate\hsf\hsf-pandora-boot\hsf-pandora-boot-provider\src\test\java\com\alibaba\edas\HelloServiceTest.java]. Line is [25] (ModifyHSFConsumerAction.java:67)
2022-03-17 16:51:35,740 [ERROR] [main] - Manual processing is required. Cause is [Interface definition not valid under @HSFConsumer annotation.].File is [D:\Code\spring-cloud-huawei-samples\migrate\hsf\hsf-pandora-boot\hsf-pandora-boot-provider\src\test\java\com\alibaba\edas\HelloServiceTest.java]. Line is [27] (ModifyHSFConsumerAction.java:67)

试一试

Srping Cloud Huawei Samples提供了一个HSF的示例项目hsf-pandora-boot，通过运行命令，可以将项目改造为Spring Cloud。改造完成后，下载本地微服务引擎, 编译和运行该项目。通过对比改造前后的差异，可以了解工具的完整运行过程。

migrator 改造步骤详细说明

ModifyHSFAction包含如下操作，分别完成不同的改造任务：

ModifyHSFProviderAction

ModifyHSFProviderAction的主要功能是扫描目录下面的所有JAVA文件，识别文件是否包含@HSFProvider 标签，如果存在，将其替换为 @RestController。

ModifyHSFConsumerAction

ModifyHSFConsumerAction的主要功能是扫描目录下面的所有JAVA文件，识别文件是否包含 @HSFConsumer 标签，如果存在，将其替换为 @FeignClient。

ModifyHSFInterface2RestAction

ModifyHSFInterface2RestAction的主要功能是扫描目录下面的所有JAVA文件，首先扫描出包含 @HSFProvider 标签的文件，并从中解析出需要处理的 JAVA interface文件，然后将 interface 文件修改为 REST 风格。

ModifyHSFAddBootstrapYamlAction

ModifyHSFAddBootstrapYamlAction的主要功能是在项目的 src/main/resources 目录下添加 bootstrap.yml 文件。会在根目录，以及根目录的第一级子目录查找 src/main/resources 目录。

ModifyHSFMainClassAction

ModifyHSFMainClassAction的主要功能是扫描目录下面的所有JAVA文件，识别文件是否包含main函数，并将相关 pandora 逻辑改为 Spring Boot。

ModifyHSFPomAction

ModifyHSFPomAction的主要功能是扫描目录下面的所有POM文件，删除HSF相关的依赖、插件，增加Spring Cloud相关的依赖、插件。

HSF 迁移 Spring Cluod 常见问题

注册发现

HSF基于“接口”进行服务发现，Spring Cloud是基于“服务名”进行注册发现，这个差异会带来如下影响：

HSF一个微服务的接口可能存在多个分组，每个分组使用不一样的名字。创建服务引用的时候，使用分组的名称。切换为Spring Cloud以后，这些名字都必须使用微服务名字spring.application.name 。微服务命名非常重要，因为其他服务会使用微服务名字表示地址，如果名字随意修改，会导致找不到服务实例，调用失败。
HSF定义一个接口，可以在不同的微服务提供实现，服务发现会把这些实现当成一个服务进行负载均衡请求。Spring Cloud只能够在微服务的实例范围内做负载均衡，不支持这种用法。

序列化

HSF使用Hession序列化，能够序列化异常类型，Spring Cloud使用Jackson序列化，不能够序列化异常类型，这个差异会带来如下影响：

假设HSF定义一个接口: public String echo() throws CustomError，在客户端调用的时候，可以捕获到CustomError异常。在使用Spring Cloud以后，无法捕获到CustomError，而是抛出FeignClientException等包装的异常。这个约束要求在写业务代码的时候，不能够依赖服务端抛出的异常类型做逻辑。建议在定义接口的时候，不声明异常。
对于一些特殊类型，比如Map<String,Object>,如果数据包含<String,Byte>类型，HSF能够正常工作。但是Spring Cloud，会抛出java.lang.ClassCastException: java.lang.Integer cannot be cast to java.lang.Byte异常。Spring Cloud反序列化Object类型后，无类型信息，会自动使用Integer。这种情况，客户端不能够假设服务端的类型，需要做好类型检查。比如对于数字类型，可以使用： ((Number)req.get("partyId")).longValue()
在使用Spring Cloud的时候，尽可能避免使用Object, JsonObject，Collection<?>等泛型类型作为参数，避免类型检查错误。必须使用的时候，客户端不能假设类型，需要做好类型检查和判断。

运行时

HSF请求的时候，不走Spring Boot的Tomcat和Servlet协议，Spring相关的拦截机制，比如Filter、认证鉴权等都不会生效。如果系统基于Spring Security做了很多扩展，Spring Cloud框架下，这些扩展会生效。需要显示的关闭认证。特别是对于中台这些使用HSF框架不需要开启认证的场景。这个差异会带来如下影响：

调用服务会报告401，鉴权失败。目前采用的统一策略在以前只提供HSF接口的后台服务中显示加入下面的配置，关闭后台服务的认证。对于前端应用，以前就是Spring Boot的，不需要改变。

@Configuration
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
    // 关闭 security校验
    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/**");
    }
}

超时配置

HSF可以在HSFProvider、HSFConsumer设置接口请求超时时间。Spring Cloud通过设置Feign的超时时间。这个差异会带来如下影响：

Spring Cloud基于服务的发现，设置超时时间相对于没有HSF灵活，需要在配置文件设置某个服务调用的超时时间。

  ```
   @FeignClient(name="biz-oc", contextId = "updateCreditPriceService", path="/updateCreditPriceService")
   public interface UpdateCreditPriceServiceExt extends UpdateCreditPriceService{}

   通过配置文件：
   feign.client.config.updateCreditPriceService.connect-timeout=3000
   feign.client.config.updateCreditPriceService.read-timeout=15000
  ```

三方软件升级

HSF由于很久没有更新，依赖了很多老的三方件，如果使用比较新的Spring Cloud版本，会更新很多三方件，从而导致一些兼容性问题。常见的情况包括：

guava版本过低，导致不兼容问题
stax-apis版本过低，导致找不到类
Spring Boot新版本做了安全加固，CORS配置规则变化
Thymeleaf新版本做了安全加固，限制了一些特殊的用法

这些问题都通过升级到新版本，按照新版本的要求进行适配即可解决

Dubbo 迁移 Spring Cloud

将 Dubbo 迁移 Spring Cloud，主要需要解决如下几个问题：

将 RPC 接口定义修改为 REST 接口定义；
将 RPC 接口调用修改为 Feign 接口调用；
修改依赖关系和配置文件；
其他常见问题修改，包括启动类修改、解决三方软件冲突等。

Dubbo迁移Spring Cloud和HSF迁移Spring Cloud非常类似，详细可以参考HSF迁移Spring Cloud方案分析和最佳实践。

使用 migrator 完成一键式改造

对于多数项目，可以通过migrator一键式完成改造。在后面的章节中，会详细描述migrator是如何做的，即使对于一些特殊的情况，也可以通过给migrator扩充功能，快速满足一键式改造的要求。

使用migrator完成改造，首先需要下载本项目代码，执行

mvn clean install

会在 target 目录编译出 migrator-0.0.1-SNAPSHOT.jar。然后将 migrator-0.0.1-SNAPSHOT.jar 和 templates 目录拷贝到一个程序运行目录，比如 D:\migrator。然后运行：

# 进入target目录或者将 migrator-0.0.1-SNAPSHOT.jar 以及 templates 目录拷贝到另外的目录
cd D:\migrator\target 
java -jar migrator-0.0.1-SNAPSHOT.jar ModifyDubboFAction [PROJECT_HOME]

其中PROJECT_HOME是需要改造的项目根目录。程序运行完可以完成一键式修改，一些无法处理的情况，会打印日志，这些情况需要手工处理。比如：

2022-03-17 16:51:35,740 [ERROR] [main] - Manual processing is required. Cause is [Interface definition not valid under @HSFConsumer annotation.].File is [D:\Code\spring-cloud-huawei-samples\migrate\hsf\hsf-pandora-boot\hsf-pandora-boot-provider\src\test\java\com\alibaba\edas\HelloServiceTest.java]. Line is [25] (ModifyHSFConsumerAction.java:67)
2022-03-17 16:51:35,740 [ERROR] [main] - Manual processing is required. Cause is [Interface definition not valid under @HSFConsumer annotation.].File is [D:\Code\spring-cloud-huawei-samples\migrate\hsf\hsf-pandora-boot\hsf-pandora-boot-provider\src\test\java\com\alibaba\edas\HelloServiceTest.java]. Line is [27] (ModifyHSFConsumerAction.java:67)

试一试

Srping Cloud Huawei Samples提供了一个Dubbo的示例项目dubbo-demo，通过运行命令，可以将项目改造为Spring Cloud。改造完成后，下载本地微服务引擎, 编译和运行该项目。通过对比改造前后的差异，可以了解工具的完整运行过程。

migrator 改造步骤详细说明

ModifyDubboAction包含如下操作，分别完成不同的改造任务：

ModifyDubboServiceAction

ModifyDubboServiceAction的主要功能是扫描目录下面的所有JAVA文件，识别文件是否包含 @DubboService 标签，如果存在，将其替换为 @RestController。

ModifyDubboReferenceAction

ModifyDubboReferenceAction的主要功能是扫描目录下面的所有JAVA文件，识识别文件是否包含 @DubboReference 标签，如果存在，将其替换为 @FeignClient。

ModifyDubboInterface2RestAction

ModifyDubboInterface2RestAction的主要功能是扫描目录下面的所有JAVA文件，首先扫描出包含 @DubboService 标签的文件，并从中解析出需要处理的 JAVA interface文件，

然后将 interface 文件修改为 REST 风格。
ModifyDubboAddBootstrapYamlAction

ModifyDubboAddBootstrapYamlAction的主要功能是在项目的 src/main/resources 目录下添加 bootstrap.yml 文件。会在根目录，以及根目录的第一级子目录查找 src/main/resources 目录。

ModifyDubboMainClassAction

ModifyDubboMainClassAction的主要功能是扫描目录下面的所有JAVA文件，识别文件是否包含main函数，并将相关 @EnableDubbo 逻辑改为 Spring Boot。

ModifyDubboPomAction

ModifyDubboPomAction的主要功能是扫描目录下面的所有POM文件，删除Dubbo相关的依赖、插件，增加Spring Cloud相关的依赖、插件。

Dubbo 迁移 Spring Cloud 常见问题

Dubbo迁移到Spring Cloud的常见问题和HSF很类似，可以参考 HSF 迁移 Spring Cloud 常见问题

为migrator项目贡献代码

如果你正在使用migrator，会发现实际项目有很多差异并不能完全一键式解决。使用自动化工具完成迁移的好处除了提升重复工作的效率，还可以避免手工修改的人为疏漏带来的工作量增加。因此，在完成1~2个代表性服务改造后，将重复步骤自动化，是提升效率和降低改造风险非常重要的手段。你可以下载migrator代码，并做少量修改就可以完成这些工作。

欢迎给migrator提交代码。你可以通过标准的创建PR的流程提交改动，经过项目审核后可以合入项目。为了保证工具的质量，在提交功能的时候，请一并提交恰当的测试代码。

对于本wiki的错漏，或者帮助补充常见问题，可以通过migrator issues进行问题反馈。对于项目的功能规划和建议，也可以通过migrator issues进行反馈。

微服务开发框架迁移概述
Spring Cloud Gateway迁移CSE
Zuul迁移CSE
Nacos+Spring Cloud迁移CSE
- 使用migrator完成一键式改造
- migrator改造步骤详细说明
Eureka+Spring Cloud迁移CSE
- 使用migrator完成一键式改造
- migrator改造步骤详细说明
HSF迁移Spring Cloud
- 使用migrator完成一键式改造
- migrator改造步骤详细说明
Dubbo迁移Spring Cloud
- 使用migrator完成一键式改造
- migrator改造步骤详细说明
常见问题
为migrator项目贡献代码

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Home

微服务开发框架迁移概述

HSF 迁移 Spring Cloud

使用 migrator 完成一键式改造

migrator 改造步骤详细说明

HSF 迁移 Spring Cluod 常见问题

注册发现

序列化

运行时

超时配置

三方软件升级

Dubbo 迁移 Spring Cloud

使用 migrator 完成一键式改造

migrator 改造步骤详细说明

Dubbo 迁移 Spring Cloud 常见问题

为migrator项目贡献代码

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally