存量應(yīng)用集成BizWorks實(shí)踐
存量應(yīng)用集成BizWorks的目的
系統(tǒng)建設(shè)復(fù)用之前開發(fā)好的一些應(yīng)用的能力,這部分應(yīng)用期望能夠較低成本(少量改造)地與BizWorks平臺打通,實(shí)現(xiàn)將應(yīng)用所實(shí)現(xiàn)的模型在BizWorks平臺可視化、應(yīng)用的接口在線管理和運(yùn)行、基于BizWorks資產(chǎn)的管理和分發(fā)、在BizWorks進(jìn)行部署并運(yùn)營等。
BWAF簡介
BWAF(BizWorks Application Framework)提供一套Java 注解(Annotation)。用于標(biāo)記既有代碼中“蘊(yùn)含”的模型。包括關(guān)鍵的基礎(chǔ)能力、商業(yè)能力,以及可用且存在的核心業(yè)務(wù)領(lǐng)域模型。
基于BWAF的注解標(biāo)記之后,通過BizWorks平臺的研發(fā)過程代碼與平臺模型的雙向聯(lián)動功能,即可在建模平臺看到相應(yīng)的模型。
在應(yīng)用運(yùn)行時,BWAF提供鏈路日志工具包,自動識別代碼中上述關(guān)鍵的注解標(biāo)記,打印能力運(yùn)行時日志。這些日志數(shù)據(jù)會被運(yùn)營平臺采集,從而實(shí)現(xiàn)數(shù)據(jù)在線化,并進(jìn)行運(yùn)營管理。
操作步驟
步驟一:創(chuàng)建應(yīng)用并關(guān)聯(lián)模型
創(chuàng)建應(yīng)用。具體操作請參見創(chuàng)建空應(yīng)用。
創(chuàng)建空應(yīng)用用于承載存量應(yīng)用,將存量應(yīng)用的代碼倉庫關(guān)聯(lián)到新建的應(yīng)用中。
創(chuàng)建一個空的限界上下文,創(chuàng)建與管理限界上下文。
該限界上下文用來承載存量應(yīng)用所上報的模型。
在新創(chuàng)建的應(yīng)用內(nèi),關(guān)聯(lián)限界上下文。具體操作,請參見管理模型。
以便于將應(yīng)用對應(yīng)的代碼所實(shí)現(xiàn)的模型,可以通過平臺或IDE插件上報到限界上下文中進(jìn)行可視化管理。
步驟二:在工程中添加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>
步驟三:在代碼中標(biāo)記注解
應(yīng)用服務(wù)@ApplicationService
應(yīng)用服務(wù)注解示例代碼如下:
@ApplicationService(name = "活動中心業(yè)務(wù)域", desc = "韻達(dá)活動中心業(yè)務(wù)域測試")
public interface ActivityServiceApi {
@ReturnValue(value = "SingleResponse結(jié)構(gòu)驗(yàn)證", name = "SingleResponse結(jié)構(gòu)驗(yàn)證")
@Method(value = "創(chuàng)建抽獎活動", name = "創(chuàng)建抽獎活動")
SingleResponse createLotteryActivity(@Parameter(value = "createLotteryActivityRequest描述", name = "createLotteryActivityRequest", required = true)
@RequestBody BaseRequest<CreateLotteryActivityRequest> createLotteryActivityRequest);
}
此示例中包含了對@ApplicationService,@ReturnValue,@Method,@Parameter注解的使用樣例。
應(yīng)用服務(wù)的結(jié)構(gòu)對象@StructureObject
通常應(yīng)用服務(wù)的出入?yún)?shù)如果為Java對象,該Java對象都應(yīng)被標(biāo)注為結(jié)構(gòu)對象。
結(jié)構(gòu)對象注解示例代碼如下:
@Getter
@Setter
@StructureObject( name = "客戶結(jié)構(gòu)對象DTO", desc = "客戶結(jié)構(gòu)對象DTO")
public class BaseRequest<T> implements Serializable {
@Field(value = "應(yīng)用的appKey", name = "應(yīng)用的appKey")
private String appKey;
@Field(value = "操作者", name = "操作者")
private String operator;
}
領(lǐng)域?qū)ο驚DomainObject(實(shí)體對象)及@ValueObject(值對象)
領(lǐng)域?qū)ο笞⒔馐纠a如下:
@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 = "創(chuàng)建時間描述", name = "創(chuàng)建時間")
@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 = "創(chuàng)建人描述", name = "創(chuàng)建人")
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 = "規(guī)則模板明細(xì)id描述", name = "規(guī)則模板明細(xì)id")
private Long id;
@Field(value = "規(guī)則名稱", name = "規(guī)則名稱")
private String name;
@Field(value = "規(guī)則模板id描述", name = "規(guī)則模板id")
private Long ruleTemplateId;
@Field(value = "規(guī)則字典code描述", name = "規(guī)則字典code")
private String ruleDictCode;
@Field(value = "字段類型描述", name = "字段類型")
private String ruleDictType;
}
此示例中包含了對@DomainObject,@ValueObject,@Field注解的使用樣例。
領(lǐng)域服務(wù)@DomainService
領(lǐng)域服務(wù)注解示例代碼如下:
@Component
@Slf4j
@DomainService(name = "活動領(lǐng)域服務(wù)", desc = "活動領(lǐng)域服務(wù)描述")
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注解的使用樣例。
商業(yè)能力@BusinessCapabilityService
商業(yè)能力注解示例代碼如下:
@BusinessCapabilityService(desc = "ActivityServiceApi desc", name = "ActivityServiceApi name")
public interface ActivityServiceApi {
@ReturnValue(value = "SingleResponse結(jié)構(gòu)驗(yàn)證", name = "SingleResponse結(jié)構(gòu)驗(yàn)證")
@Method(value = "創(chuàng)建抽獎活動", name = "創(chuàng)建抽獎活動")
SingleResponse createLotteryActivity(@Parameter(value = "createLotteryActivityRequest描述", name = "createLotteryActivityRequest", required = true)
@RequestBody BaseRequest<CreateLotteryActivityRequest> createLotteryActivityRequest);
}
此示例中包含了對@BusinessCapabilityService,@ReturnValue,@Method,@Parameter注解的使用樣例。
商業(yè)能力的結(jié)構(gòu)對象@StructureObject
通常商業(yè)能力服務(wù)的方法出入?yún)?shù)若為Java對象,該Java對象都應(yīng)被標(biāo)注為結(jié)構(gòu)對象。
商業(yè)能力結(jié)構(gòu)對象注解示例代碼如下:
@JsonInclude(JsonInclude.Include.NON_NULL)
@Getter
@Setter
@StructureObject( name = "客戶結(jié)構(gòu)對象DTO", desc = "客戶結(jié)構(gòu)對象DTO")
public class User<T> implements Serializable {
@Field(value = "應(yīng)用的appKey", name = "應(yīng)用的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平臺存在的限界上下文、商業(yè)能力。
限界上下文對標(biāo)的是舊版本中的業(yè)務(wù)域概念。
在如下圖所示位置(應(yīng)用根目錄下./bizworks/路徑下
),添加bizworks.yml
文件。
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服務(wù)地址 | 無。 |
bizworks.project.code | 項(xiàng)目code | 無。 |
bizworks.application.code | 應(yīng)用code | 無。 |
bizworks.application.archPattern | 腳手架類型 | 無。 |
bizworks.application.version | 應(yīng)用版本 | 無。 |
bizworks.modules.type | 類型 |
|
bizworks.modules.code | 編碼 | 業(yè)務(wù)域或商業(yè)能力的編碼。 |
bizworks.modules.packages | 包路徑 | 代碼掃描的包路徑。 |
步驟五:代碼掃描
使用BizWorks中心應(yīng)用的代碼掃描功能,您可以參考以下文檔完成上述改造的代碼分析,進(jìn)行掃描及合并。
平臺上代碼掃描:掃描代碼與合并模型
IDE插件代碼掃描:代碼模型掃描上報
IDE插件上報接口:代碼接口上報
規(guī)約掃描并QuickFix:觸發(fā)檢查和快速修復(fù)本地代碼
成功完成該步驟后,應(yīng)用中的關(guān)鍵模型就同步到了BizWorks平臺上,在建模平臺實(shí)現(xiàn)可視化。
步驟六:在BizWorks平臺部署運(yùn)行應(yīng)用
應(yīng)用通過BizWorks平臺部署運(yùn)行。具體操作,請參見部署中心應(yīng)用實(shí)例。
BizWorks平臺會為應(yīng)用注入必要的運(yùn)行時配置。BWAF框架提供的鏈路日志工具包在運(yùn)行時打印能力被調(diào)用的鏈路日志,這些日志被平臺采集,在運(yùn)營平臺實(shí)現(xiàn)能力數(shù)據(jù)在線化。
附錄
應(yīng)用集成BWAF后在本地或其他平臺部署方案介紹
如果需要在本地或其他非BizWorks平臺部署運(yùn)行(本地部署或其他),則需要通過環(huán)境變量或應(yīng)用配置的方式,補(bǔ)充幾個必要的運(yùn)行時信息,用于BWAF鏈路日志的關(guān)鍵內(nèi)容組裝和打印。
租戶標(biāo)識
環(huán)境變量:BW_TENANT_ID
應(yīng)用配置:bizworks.tenantId
項(xiàng)目編碼
環(huán)境變量:BW_PROJECT_CODE
應(yīng)用配置:bizworks.projectId
應(yīng)用編碼
環(huán)境變量:BW_APPLICATION_CODE
應(yīng)用配置:bizworks.appId
應(yīng)用版本
環(huán)境變量:BW_APPLICATION_VERSION
應(yīng)用配置:bizworks.appVersion
示例代碼如下:
bizworks:
appId: tracecenter
appVersion: v1.2.1
tenantId: 1234567890987654321
projectId: poc