文档

存量应用集成BizWorks实践

更新时间:

存量应用集成BizWorks的目的

系统建设复用之前开发好的一些应用的能力,这部分应用期望能够较低成本(少量改造)地与BizWorks平台打通,实现将应用所实现的模型在BizWorks平台可视化、应用的接口在线管理和运行、基于BizWorks资产的管理和分发、在BizWorks进行部署并运营等。

BWAF简介

  • BWAF(BizWorks Application Framework)提供一套Java 注解(Annotation)。用于标记既有代码中“蕴含”的模型。包括关键的基础能力、商业能力,以及可用且存在的核心业务领域模型。

  • 基于BWAF的注解标记之后,通过BizWorks平台的研发过程代码与平台模型的双向联动功能,即可在建模平台看到相应的模型。

  • 在应用运行时,BWAF提供链路日志工具包,自动识别代码中上述关键的注解标记,打印能力运行时日志。这些日志数据会被运营平台采集,从而实现数据在线化,并进行运营管理。

操作步骤

步骤一:创建应用并关联模型

  1. 创建应用。具体操作请参见创建空应用

    创建空应用用于承载存量应用,将存量应用的代码仓库关联到新建的应用中。

  2. 创建一个空的限界上下文,创建与管理限界上下文

    该限界上下文用来承载存量应用所上报的模型。

  3. 在新创建的应用内,关联限界上下文。具体操作,请参见管理模型

    以便于将应用对应的代码所实现的模型,可以通过平台或IDE插件上报到限界上下文中进行可视化管理。

步骤二:在工程中添加POM依赖

以下POM文件示例中BWAF框架的版本信息bizworks.bwaf.version(示例代码中使用的版本为2.3.1)取最新版本。

BWAF注解包

 <dependency>
    <groupId>com.alibaba.bizworks</groupId>
    <artifactId>bwaf-core-specification-common</artifactId>
    <version>${bizworks.bwaf.version}</version>
</dependency>

<dependency>
  <groupId>com.alibaba.bizworks</groupId>
  <artifactId>bwaf-core-specification-ddd</artifactId>
  <version>${bizworks.bwaf.version}</version>
</dependency>

<dependency>
  <groupId>com.alibaba.bizworks</groupId>
  <artifactId>bwaf-core-specification-pbc</artifactId>
  <version>${bizworks.bwaf.version}</version>
</dependency>

BWAF链路日志包

<dependency>
  <groupId>com.alibaba.bizworks</groupId>
  <artifactId>bwaf-core-traffic-logging</artifactId>
  <version>${bizworks.bwaf.version}</version>
</dependency>

步骤三:在代码中标记注解

应用服务@ApplicationService

应用服务注解示例代码如下:


@ApplicationService(name = "活动中心业务域", desc = "韵达活动中心业务域测试")
public interface ActivityServiceApi {


    @ReturnValue(value = "SingleResponse结构验证", name = "SingleResponse结构验证")
    @Method(value = "创建抽奖活动", name = "创建抽奖活动")
    SingleResponse createLotteryActivity(@Parameter(value = "createLotteryActivityRequest描述", name = "createLotteryActivityRequest", required = true) 
                                         @RequestBody BaseRequest<CreateLotteryActivityRequest> createLotteryActivityRequest);
  
  }

此示例中包含了对@ApplicationService,@ReturnValue,@Method,@Parameter注解的使用样例。

应用服务的结构对象@StructureObject

通常应用服务的出入参数如果为Java对象,该Java对象都应被标注为结构对象。

结构对象注解示例代码如下:


@Getter
@Setter
@StructureObject(  name = "客户结构对象DTO", desc = "客户结构对象DTO")
public class BaseRequest<T> implements Serializable {

    @Field(value = "应用的appKey", name = "应用的appKey")
    private String appKey;

    @Field(value = "操作者", name = "操作者")
    private String operator;

}

领域对象@DomainObject(实体对象)及@ValueObject(值对象)

领域对象注解示例代码如下:


@Getter
@Setter
@DomainObject(isAggregateRoot = true, name = "客户", desc = "客户描述")
public class RuleDictE extends BaseEntity {

    @Field(value = "主键id描述", name = "主键id")
    private Long id;
    @Field(value = "名称描述", name = "名称")
    private String name;
    @Field(value = "编码描述", name = "编码")
    private String code;
    @Field(value = "value描述", name = "value")
    private String value;
    @Field(value = "描述", name = "描述")
    private String description;
    @Field(value = "是否删除描述", name = "是否删除")
    private Byte deleted;
    @Field(value = "创建时间描述", name = "创建时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;
    @Field(value = "修改时间描述", name = "修改时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date modifyTime;
    @Field(value = "创建人描述", name = "创建人")
    private String createBy;
    @Field(value = "修改人描述", name = "修改人")
    private String modifyBy;
}

@ValueObject( name = "值对象", desc = "值对象描述")
public class RuleTemplateDetailE extends BaseEntity {

	/**
	 * 序列号
	 */
	private static final long serialVersionUID = 1L;
	@Field(value = "规则模板明细id描述", name = "规则模板明细id")
	private Long id;
	@Field(value = "规则名称", name = "规则名称")
	private String name;
	@Field(value = "规则模板id描述", name = "规则模板id")
	private Long ruleTemplateId;
	@Field(value = "规则字典code描述", name = "规则字典code")
	private String ruleDictCode;
	@Field(value = "字段类型描述", name = "字段类型")
	private String ruleDictType;
	
	
}

此示例中包含了对@DomainObject,@ValueObject,@Field注解的使用样例。

领域服务@DomainService

领域服务注解示例代码如下:


@Component
@Slf4j
@DomainService(name = "活动领域服务", desc = "活动领域服务描述")
public class ActivityDomainService {

    /**
     * 1.更新活动
     * 2.推送redis
     *
     * @param activityE
     * @return
     */
    @ReturnValue(value = "SingleResponse描述", name = "SingleResponse")
    @Method(value = "更新活动描述", name = "更新活动")
    public Boolean updateActivity(@Parameter(desc = "Activity描述", name = "Activity", required = true) Activity activity) {
       
        return true;
    }


}

此示例中包含了对@DomainService,@ReturnValue,@Method,@Parameter注解的使用样例。

商业能力@BusinessCapabilityService

商业能力注解示例代码如下:


@BusinessCapabilityService(desc = "ActivityServiceApi desc", name = "ActivityServiceApi name")
public interface ActivityServiceApi {


    @ReturnValue(value = "SingleResponse结构验证", name = "SingleResponse结构验证")
    @Method(value = "创建抽奖活动", name = "创建抽奖活动")
    SingleResponse createLotteryActivity(@Parameter(value = "createLotteryActivityRequest描述", name = "createLotteryActivityRequest", required = true)
                                         @RequestBody BaseRequest<CreateLotteryActivityRequest> createLotteryActivityRequest);

	
	
}

此示例中包含了对@BusinessCapabilityService,@ReturnValue,@Method,@Parameter注解的使用样例。

商业能力的结构对象@StructureObject

通常商业能力服务的方法出入参数若为Java对象,该Java对象都应被标注为结构对象。

商业能力结构对象注解示例代码如下:


@JsonInclude(JsonInclude.Include.NON_NULL)
@Getter
@Setter
@StructureObject( name = "客户结构对象DTO", desc = "客户结构对象DTO")
public class User<T> implements Serializable {

    @Field(value = "应用的appKey", name = "应用的appKey")
    private String appKey;

    @Field(value = "操作者", name = "操作者")
    private String operator;

    @Field(value = "操作者所属的组织id", name = "操作者所属的组织id")
    private String operatorOrgId;

    @Field(value = "操作者所属的组织类型", name = "操作者所属的组织类型")
    private String operatorOrgType;


}

此示例中包含了对@StructureObject,@Field注解的使用样例。

步骤四:在工程中添加bizworks.yml配置文件

在代码里配置完BWAF注解之后,需要在bizworks.yml里配置BizWorks平台存在的限界上下文、商业能力。

说明

限界上下文对标的是旧版本中的业务域概念。

在如下图所示位置(应用根目录下./bizworks/路径下),添加bizworks.yml文件。image

bizworks.yml文件代码示例如下:

bizworks:
  server: "http://xxx"
  project:
    code: "zhangb23830"
  application:
    code: "app830-01"
    archPattern: "ddd"
    version: "v1.0.0"
  modules:
  - type: "MODULE_CENTER"
    code: "UatTestContext01"
    packages:
    - "bizworks.app83001.businessdomain.uattestcontext01"
  - type: "BUSINESS_CAPABILITY"
    code: "Business01"
    packages:
    - "bizworks.app83001.businesscapability.business01"

bizworks.yml文件中的属性含义如下表所示:

属性

含义

说明

bizworks.server

BizWorks服务地址

无。

bizworks.project.code

项目code

无。

bizworks.application.code

应用code

无。

bizworks.application.archPattern

脚手架类型

无。

bizworks.application.version

应用版本

无。

bizworks.modules.type

类型

  • 限界上下文(原业务域):MODULE_CENTER

  • 商业能力:BUSINESS_CAPABILITY

bizworks.modules.code

编码

业务域或商业能力的编码。

bizworks.modules.packages

包路径

代码扫描的包路径。

步骤五:代码扫描

使用BizWorks中心应用的代码扫描功能,您可以参考以下文档完成上述改造的代码分析,进行扫描及合并。

成功完成该步骤后,应用中的关键模型就同步到了BizWorks平台上,在建模平台实现可视化。

步骤六:在BizWorks平台部署运行应用

应用通过BizWorks平台部署运行。具体操作,请参见部署中心应用实例

BizWorks平台会为应用注入必要的运行时配置。BWAF框架提供的链路日志工具包在运行时打印能力被调用的链路日志,这些日志被平台采集,在运营平台实现能力数据在线化。

附录

应用集成BWAF后在本地或其他平台部署方案介绍

如果需要在本地或其他非BizWorks平台部署运行(本地部署或其他),则需要通过环境变量或应用配置的方式,补充几个必要的运行时信息,用于BWAF链路日志的关键内容组装和打印。

  • 租户标识

    • 环境变量:BW_TENANT_ID

    • 应用配置:bizworks.tenantId

  • 项目编码

    • 环境变量:BW_PROJECT_CODE

    • 应用配置:bizworks.projectId

  • 应用编码

    • 环境变量:BW_APPLICATION_CODE

    • 应用配置:bizworks.appId

  • 应用版本

    • 环境变量:BW_APPLICATION_VERSION

    • 应用配置:bizworks.appVersion

示例代码如下:

bizworks:
  appId: tracecenter
  appVersion: v1.2.1
  tenantId: 1234567890987654321
  projectId: poc

  • 本页导读 (1)