HAP3.X 升级 HZERO

本文档介绍如何将 HAP3.X 版本升级至 HZERO，并注册为 HZERO 的微服务使用。本文档案例基于 HAP 3.5.6 进行，对应的 HZERO 平台需使用 1.1.0.RELEASE 版本及以上。

• 后续调整代码会用到一些工具包及源码文件，已上传至汉得网盘，密码请向HZERO平台获取，请提前下载：HAP升HZERO相关文件

项目结构调整

• HAP 项目原始结构

  

• 首先删除最外层的 core-db 模块及 pom.xml 文件，如果 core-db 下有数据，请先备份

• 将 core 模块下的 src 目录及 pom.xml 移到根目录下

• 删除 core 模块及其下面的 overlays

• 将 webapp 下所有文件和目录移动到 resources/ 下

• 删除 webapp 目录

• 将工程名称及根目录名称调整为 HZERO 规范，如 hzero-hap

• 调整完的目录结构如下

  

POM依赖调整

• parent 依赖 hzero-hap-parent

  <parent>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-parent</artifactId>
      <version>0.1.0-SNAPSHOT</version>
  </parent>
  

• 修改自身坐标

  artifactId: 改为与项目名称相同
  packaging: 由 `war` 改为 `jar`
  
  <groupId>com.hand</groupId>
  <artifactId>hzero-hap</artifactId>
  <packaging>jar</packaging>
  

• 删除 hap 模块依赖、全模块依赖，只保留项目依赖的其它非 hap 组件

• 添加 hzero-hap 组件，hzero-hap 组件对原 hap 模块化组件做了兼容处理

  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-core</artifactId>
  </dependency>
  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-workflow</artifactId>
  </dependency>
  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-report</artifactId>
  </dependency>
  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-front-html</artifactId>
  </dependency>
  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-front-kendo</artifactId>
  </dependency>
  <dependency>
      <groupId>org.hzero.hap</groupId>
      <artifactId>hzero-hap-attachment</artifactId>
  </dependency>
  

• 添加 hzero 基础组件

  <!-- hzero starter -->
  <dependency>
      <groupId>org.hzero.starter</groupId>
      <artifactId>hzero-starter-config-client</artifactId>
  </dependency>
  
  <!-- hzero boot -->
  <dependency>
      <groupId>org.hzero.boot</groupId>
      <artifactId>hzero-boot-scheduler</artifactId>
  </dependency>
  

• 添加数据库驱动，根据实际使用的数据库添加对应的驱动即可

  <!-- 数据库驱动 -->
  <dependency>
      <artifactId>mysql-connector-java</artifactId>
      <groupId>mysql</groupId>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>com.oracle</groupId>
      <artifactId>ojdbc7</artifactId>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>com.microsoft.sqlserver</groupId>
      <artifactId>sqljdbc4</artifactId>
      <optional>true</optional>
  </dependency>
  

• 添加容器依赖、注册中心客户端依赖、监控依赖等

  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-undertow</artifactId>
  </dependency>
  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <exclusions>
          <exclusion>
              <artifactId>spring-boot-starter-tomcat</artifactId>
              <groupId>org.springframework.boot</groupId>
          </exclusion>
      </exclusions>
  </dependency>
  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
  <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
  </dependency>
  

• 删除 build、profiles 标签

• 添加 maven 仓库

  <repositories>
      <repository>
          <id>choerodon-release-repository</id>
          <url>https://nexus.choerodon.com.cn/repository/choerodon-release</url>
      </repository>
      <repository>
          <id>choerodon-snapshot-repository</id>
          <url>https://nexus.choerodon.com.cn/repository/choerodon-snapshot</url>
      </repository>
      <repository>
          <id>HzeroRelease</id>
          <name>Hzero-Release Repository</name>
          <url>http://nexus.saas.hand-china.com/content/repositories/Hzero-Release/</url>
          <releases>
              <enabled>true</enabled>
          </releases>
          <snapshots>
              <enabled>false</enabled>
          </snapshots>
      </repository>
      <repository>
          <id>HzeroSnapshot</id>
          <name>Hzero-Snapshot Repository</name>
          <url>http://nexus.saas.hand-china.com/content/repositories/Hzero-Snapshot/</url>
          <releases>
              <enabled>false</enabled>
          </releases>
          <snapshots>
              <enabled>true</enabled>
              <updatePolicy>always</updatePolicy>
          </snapshots>
      </repository>
  </repositories>
  

• 添加 springboot 打包插件

  <build>
      <plugins>
          <plugin>
              <groupId>org.springframework.boot</groupId>
              <artifactId>spring-boot-maven-plugin</artifactId>
              <configuration>
                  <skip>false</skip>
              </configuration>
              <executions>
                  <execution>
                      <goals>
                          <goal>repackage</goal>
                      </goals>
                  </execution>
              </executions>
          </plugin>
      </plugins>
  </build>
  

• 至此，pom 依赖就调整完成，完整版 pom.xml 文件可从下载的文件中获取

配置文件调整

• 在 resources/ 资源目录下，将 application.yml 和 bootstrap.yml 配置文件复制进去

• bootstrap.yml 重点需自行调整如下配置：

  • 服务端口

    server:
      port: 9090
    management:
      server:
        port: 9091
    

  • 多环境配置：如果有多个环境的配置，可建多个环境的 application.yml 配置文件，如 application-dev.yml、application-uat.yml，然后配置启用的配置文件

    spring:
      profiles:
        active: ${SPRING_PROFILES_ACTIVE:uat}
    

  • 注册中心地址

    eureka:
      client:
        serviceUrl:
          defaultZone: ${EUREKA_DEFAULT_ZONE:http://dev.hzero.org:8000/eureka}
    

• application.yml 重点需自行调整如下配置：

  • 服务名称

    spring:
      application:
        name: hzero-hap
    

  • 数据库连接：不同的数据库选择不同的 url 配置

    spring:
      datasource:
        # mysql: jdbc:mysql://db.hzero.org:3306/hzero_qms?useUnicode=true&characterEncoding=utf-8&useSSL=false
        # oracle: jdbc:oracle:thin:@db.hzero.org:1521:XE
        # sql-server: jdbc:sqlserver://db.hzero.org:1433;DatabaseName=hzero_qms
        url: ${SPRING_DATASOURCE_URL:jdbc:mysql://db.hzero.org:3306/hzero_qms?useUnicode=true&characterEncoding=utf-8&useSSL=false}
        username: ${SPRING_DATASOURCE_USERNAME:hzero}
        password: ${SPRING_DATASOURCE_PASSWORD:hzero}
              
    # 数据库类型：mysql/oracle/mssql
    db:
      type: mysql    
    

  • Redis 连接

    spring:
      redis:
        host: ${SPRING_REDIS_HOST:redis.hzero.org}
        port: ${SPRING_REDIS_PORT:6379}
        database: ${SPRING_REDIS_DATABASE:1}
        password: ${SPRING_REDIS_PASSWORD:}
    
    # 原 hap 配置
    redis:
      ip: ${SPRING_REDIS_HOST:redis.hzero.org}
      db: ${SPRING_REDIS_DATABASE:1}
      port: ${SPRING_REDIS_PORT:6379}
      password: ${SPRING_REDIS_PASSWORD:}
    

  • 配置跨域访问地址及网关地址

    hzero:
      origin:
        # 允许跨域的地址：因为 hap 页面是嵌入 hzero 前端，因此 hap 服务需允许前端跨域访问，配置前端地址
        allow-from: ${HZERO_ORIGIN_ALLOW_FROM:http://hzeronf.saas.hand-china.com}
      # 网关地址  
      gateway-domain: ${HZERO_GATEWAY_DOMAIN:http://hzeronb.saas.hand-china.com}  
    

  • 数据屏蔽配置：如果是表都在一个库下，需禁用数据屏蔽（默认启用）

    hzero:
      data:
        permission:
          enabled: ${HZERO_ENABLE_DATA_PERMISSION:true}
    

• 新建 com.hand.hap.config 包，将 HapExtraDataManager.java 路由配置类复制进去，如果要修改成其它路由，可自行修改

• 将应用程序启动类 HapApplication.java 复制到 com.hand 包下

• 清理 xml 配置，删除 spring 目录(包含 applicationContext.xml 等配置)，如果有自定义 bean 配置，可使用 springboot 的配置方式配置

• 删除 profiles 目录，多环境配置可建多个不同环境的 application.yml 配置文件并指定 spring.profiles.active 实现

• 删除 quartz.properties，任务调度使用 hzero 调度客户端替换

HZERO环境准备

• 为了将 HAP 项目迁移至 HZERO 平台，至少先准备一套 HZERO 运行环境。如果没有 HZERO 环境，可参考文档搭建：服务器本地安装

• 在网关服务(hzero-gateway)的 application.yml 中添加如下配置：主要目的是跳过 hap 静态资源的权限校验

  hzero:
    gateway:
      helper:
        helper-skip-paths:
          - /hap/lib/**
          - /hap/static/**
          - /hap/resources/**
  

• 为了进行后面的工作，请先将 HAP 项目的数据库迁移至 HZERO 数据库下，可以为 HAP 项目建一个单独的 schema，如：hzero_hap

代码批量处理

• HAP 升级到 HZERO 会涉及到一些包结构、类名、API 等代码的改动，可使用工具批量处理项目代码。主要处理的内容包含如下：

  • 一些类的替换，如：将 com.hand.hap.system.dto.BaseDTO 替换成 io.choerodon.mybatis.entity.BaseDTO
  • 在 Controller 类上加 @RequestMapping("/v1/{organizationId}") 注解，将接口改造成HZERO规范且带租户ID的API
  • 在 Controller 类上加 @Api(tags = SwaggerApiTag.XXX) 注解，描述 Swagger 标签
  • 在 Controller 方法上加 @Permission(level = ResourceLevel.ORGANIZATION) 注解，将接口设置为租户级API
  • 在 Controller 方法上加 @ApiOperation(value = "XXX") 注解，描述方法
  • 将 html 或 view 文件中包含 /common 接口的 script 请求加上 access_token 参数

• 接下来将使用工具批量处理HAP代码，首先修改 HAP升HZERO工具.sh 脚本中的配置：

  # 配置已经迁移至HZERO平台下的HAP数据库信息
  # hap.dir：配置 hap 项目的目录路径
  # hap.context-path：与 hap 项目的 server.servlet.context-path 保持一致
  
  java -Dspring.datasource.url="jdbc:mysql://db.hzero.org:3306/hzero_hap?useUnicode=true&characterEncoding=utf-8&useSSL=false" \
      -Dspring.datasource.username=hzero \
      -Dspring.datasource.password=hzero \
      -DLOG_LEVEL=info \
      -Dhap.dir=E:/tmp/hzero-hap/src/main \
      -Dhap.context-path=/hap \
      -jar tool-jar/hzero-hap-tool.jar
  

• 接着在 sh 客户端中运行 HAP升HZERO工具.sh，工具启动成功后，浏览器访问 http://localhost:8088/code-fix，处理代码

• 执行完成后，可在 ./output/code-fix/ 目录下看到两个文件：

  • SwaggerApiTag.java：生成 Controller 的 Swagger Api Tag
  • handle-line.txt：记录处理代码的文件
  • code-fix-multi-language.json：需手动调整多语言的地方
  • code-fix-table.json：需手动调整表查询的地方
  • code-fix-url.json：需手动调整页面API的地方

• 将 SwaggerApiTag.java 文件复制到 com.hand.hap.config 包下

• 如果项目上覆盖了 hap 基础包的源码，需对照基础包源码手动处理。重点：如果覆盖了 com.hand.hap.system.controllers.BaseController 和 WEB-INF/view/include/header.html，需将原文件拿出来重新覆盖，再加上定制的修改。其它覆盖的文件可向 HZERO 平台获取。

• 批量工作处理完后，剩下的需要手动调整代码，先调整客户端的一些替换工作，再构建项目手动处理报错的代码。

消息发送改造

HAP 消息(邮件、短信、站内信等)需替换成使用 HZERO 消息，如果服务中用到了消息发送，可按如下步骤替换。

• 首先服务中需加入 hzero-boot-message 消息客户端依赖

  <dependency>
      <groupId>org.hzero.boot</groupId>
      <artifactId>hzero-boot-message</artifactId>
  </dependency>
  

• HZERO 消息具体使用方式请参考：消息服务、消息服务客户端

• 需要发送消息的地方，注入 org.hzero.boot.message.MessageClient，使用 MessageClient 即可发送 邮件、短信、站内信等。

任务调度改造

HAP 任务调度需替换成 HZERO 任务调度，如果服务中用到了任务调度，可按如下步骤替换。

• 首先服务中需加入 hzero-boot-scheduler 调度客户端依赖

  <dependency>
      <groupId>org.hzero.boot</groupId>
      <artifactId>hzero-boot-scheduler</artifactId>
  </dependency>
  

• HZERO 任务调度具体使用方式请参考：调度服务、调度服务客户端

• 调度类替换

  • 原调度类声明：

    import com.hand.hap.job.AbstractJob;
    import com.hand.hap.task.info.ExecutionInfo;
    import com.hand.hap.task.service.ITask;
    
    public class DemoJob extends AbstractJob implements ITask{
    
        @Override
        public void execute(ExecutionInfo executionInfo) throws Exception {
            // ...
        }
        @Override
        public void safeExecute(JobExecutionContext context) throws Exception {
            // ...
        }
    }
    

  • 修改成如下：execute 或者 safeExecute 都替换成如下 execute 方法

    import java.util.Map;
    import org.hzero.boot.scheduler.infra.annotation.JobHandler;
    import org.hzero.boot.scheduler.infra.enums.ReturnT;
    import org.hzero.boot.scheduler.infra.handler.IJobHandler;
    import org.hzero.boot.scheduler.infra.tool.SchedulerTool;
    
    @JobHandler("对应执行器中的jobHandler")
    public class DemoJob implements IJobHandler {
    
        @Override
        public ReturnT execute(Map<String, String> map, SchedulerTool tool) {
            // ...
            return ReturnT.SUCCESS;
        }
    }
    

• execute 方法改造

  • 任务执行参数：获取参数由 executionInfo.getParam() 替换为直接从 map 获取
  • 任务执行人：获取执行人由 executionInfo.getUsername() 替换为用 DetailsHelper 获取任务创建人的租户ID、角色ID、用户ID，或者tool.getBelongTenantId()获取任务所属租户
  • 当前任务信息：获取当前任务详情由 executionInfo.getTaskDetail() 替换为 tool.getJobDataDTO()

• 任务监听改造

  • 替换原有监听类 class Xxx implements IExecuteListener，重写任务类方法
  • 将 before(TaskDataInfo taskDataInfo) 方法替换为重写 onCreate(SchedulerTool tool) 方法，在任务开始前执行
  • 将 doException(TaskDataInfo taskDataInfo) 方法重写 onException(SchedulerTool tool) 方法，在任务执行捕获到异常时执行
  • 将 after(TaskDataInfo taskDataInfo)、doFinally(TaskDataInfo taskDataInfo) 替换为重写 onFinish(SchedulerTool tool, ReturnT returnT) 方法，在任务执行结束后执行

• 执行记录改造

  • 替换原有任务记录类 class Xxx implements ExecuteLogConvertStrategy
  • 在任务类 execute 方法中，利用 tool.debug()、tool.info()、tool.warn()、tool.error() 方法记录日志信息，可通过 tool.setFileSuffix() 方法设置文件后缀，也可使用setByteArrayOutputStream 方法自行覆盖日志文件内容

接口服务改造

• 总体方案：HAP的接口管理/服务管理替换为HZERO的接口平台服务

• 迁移方案如下：

  • 历史数据迁移，按照HZERO接口平台的数据格式迁移历史数据.详情请看数据迁移工具介绍
  • 确认租户、客户端、角色等基础数据，维护新的权限体系

• 部分功能改造方案如下：

  • 对于接口管理&服务管理已注册的接口调用，可以维持原来的restTemplate/httpclient或者其它方式，也可以使用HZERO接口平台提供的接口平台客户端进行更便捷的调用
  • 原HAP入站出站信息记录方式@HapInbound和@HapOutbound需要调整，具体如下：
    • @HapInbound功能主要为了记录HAP相关API的请求响应信息，可通过HHZERO平台的操作审计配置实现动态记录相关日志，目前记录了请求时间、请求参数、耗时等信息，未来会增加IP/Referer等信息
    • @HapOutbound功能主要为了记录HAP通过接口管理注册的外部系统API的调用记录，此部分通过HZERO的接口平台服务日志功能来做替换
  • 原HAP接口管理中PLSQL类型的接口配置需要改造为RestAPI或者SOAP形式，然后再注册到HZERO接口平台，目前HZERO接口平台不支持直接注册PLSQL的方式

其它代码调整

• 根据之前扫描的要改动的地方手动调整代码

• code-fix-multi-language.json：需手动调整多语言的地方，如果字段上用到了多语言注解 @MultiLanguageField，需在类上加 @MultiLanguage 注解

• code-fix-table.json：需手动调整表查询的地方，将原 hap 关联查询的表改成 hzero 的表，对应关系可参考文件 HAP-HZERO-表关系.xlsx

• code-fix-url.json：需手动调整页面API的地方，HTML页面中的API调用格式：'${base.contextPath}/file/manager/his/select' 需改为 _basePath + '/file/manager/his/select'；_basePath 增加了 /v1/{organizationId} 前缀

启动服务

• 代码调整完成后，构建 hzero-hap 服务，如果有报错，需手动处理报错的代码

• 构建通过后，通过 HapApplication 启动 hzero-hap 服务，能在注册中心看到 hzero-hap 服务代表服务已经启动成功

  

• 服务启动成功后，在 swagger 上调用 IAM 服务的刷新权限接口，刷新 hzero-hap 服务的权限

  

• 权限刷新成功后，将表 hzero_platform.iam_permission 同步到 hzero_hap 库下，便于后面处理菜单权限关系

数据处理

• 接下来同步 HAP 的基础数据到 HZERO 中，主要包含 菜单、组织架构、员工、用户、值集、快码、多语言 等

• 首先修改 初始化HZERO临时表.sh 脚本配置

  # 配置已经迁移至HZERO平台下的HAP数据库信息
  
  java -Dspring.datasource.url="jdbc:mysql://db.hzero.org:3306/hzero_hap?useUnicode=true&characterEncoding=utf-8&useSSL=false" \
      -Dspring.datasource.username=hzero \
      -Dspring.datasource.password=hzero \
  

• 在 sh 客户端运行 初始化HZERO临时表.sh，初始化 HZERO 的临时表到 hzero_hap 数据库中，便于将HAP数据同步到临时表中

• 接着在 sh 客户端中运行 HAP升HZERO工具.sh，工具启动成功后，浏览器访问 http://localhost:8088/data-sync，同步数据。

• 同步完成后，在 hzero_hap 库的临时表中可以看到同步的数据，在 ./output/data-sync/ 目录下可以看到如下文件：

  • hap-hzero-iam.xlsx ：菜单以及菜单权限
  • hap-hzero-lov.xlsx ：值集
  • hap-hzero-platform.xlsx：平台基础数据
  • html-api.txt：html 页面扫描出的API

• 数据导出 Excel 后，修改 Excel数据导入HZERO.sh 脚本配置：

  # 配置HZERO平台数据库信息
  
  java -Dspring.datasource.url="jdbc:mysql://db.hzero.org:3306/hzero_platform?useUnicode=true&characterEncoding=utf-8&useSSL=false" \
      -Dspring.datasource.username=hzero \
      -Dspring.datasource.password=hzero \
  

• 运行 Excel数据导入HZERO.sh，将 Hap 的 Excel 期初数据导入 HZERO 的 hzero_platform 库中

• 接着同样修改 期初数据导入HZERO.sh 脚本配置再运行，将 base-data 下的 hap 期初数据导入 hzero_platform 库中

• 菜单权限同步后，需要调用IAM如下接口将将权限集挂到超级管理员下，之后才可以分配权限

  

• 运行 HAP升HZERO工具.sh，调用 http://localhost:8088/delete-tmp-table 接口删除 hzero_hap 中的临时表，也可手动删除

• 注意：需自行将 任务调度、邮件消息 相关的数据维护到HZERO

• 注意：由于 hap sys_user 与 hzero iam_user 用户表之间有些不对应，将 sys_user 表中的字段同步到 iam_user 的扩展字段 attribute 上。具体关系如下，如果SQL查询了相关字段需自行调整。

  sys_user.description  ->  iam_user.attribute1
  sys_user.employee_id  ->  iam_user.attribute2
  sys_user.customer_id  ->  iam_user.attribute3
  sys_user.supplier_id  ->  iam_user.attribute4
  sys_user.user_type    ->  iam_user.attribute5
  

升级完成

• 请先备份 hzero_hap 整库的数据，运行 HAP升HZERO工具.sh，调用 http://localhost:8088/delete-hap-table 接口删除 HAP 项目中被 HZERO 取代的表，便于后续测试并发现错误。

• 按以上步骤处理完后，就可以启动服务测试页面及功能，手动调整有错误的地方。测试的时候建议使用超级用户(admin)测试，测试完成后再建系统角色并分配权限。