计费服务客户端
组件编码
hzero-boot-charge
一、简介
1.1 概述
计费服务接口集成,使用feign调用实现,依赖客户端操作可以避免复杂的Feign调用处理,开发者不用关注客户端与服务端数据交互细节,便于使用和升级维护。
业务系统可以根据计费服务提供的功能,通过客户端使用计费服务,达到增强业务系统功能的目的。
1.2 特性
- 基于计费服务实现:hzero-charge
1.3 组件坐标
<dependency>
<groupId>org.hzero.boot</groupId>
<artifactId>hzero-boot-charge</artifactId>
<version>${hzero.boot.version}</version>
</dependency>
二、使用指南
2.1 计费客户端使用方法
在代码中自动注入计费客户端:
org.hzero.boot.charge.infra.sdk.ChargeSdk
2.1.1 计费规则查询
/**
* 分页查询计费规则
*
* @param organizationId 租户
* @param pageRequest 分页参数对象
* @param ruleQueryParamDto 计费规则查询参数对象
* @return 查询到的计费规则
*/
Page<RuleHeaderDTO> queryRule(Long organizationId, PageRequest pageRequest, RuleQueryParamDTO ruleQueryParamDto);
2.1.2 账单生成
/**
* 生成账单
*
* @param organizationId 租户
* @param billGenerationParamDto 生成账单参数对象
* @return 生成账单结果对象
*/
BillingResultDTO generateBill(Long organizationId, BillGenerationParamDTO billGenerationParamDto);
2.1.3 账单查询
/**
* 通过账单编号获取账单(账单编号是计费服务返回的账单编号)
*
* @param organizationId 租户
* @param billNum 账单编号,计费服务返回的账单编号
* @return 账单查询结果
*/
BillDTO getBill(Long organizationId, String billNum);
/**
* 通过来源账单编号获取账单(账单编号是当前系统生成账单时使用的唯一编号)
*
* @param organizationId 租户
* @param sourceBillNum 来源账单编号(在当前系统编号下唯一)
* @return 账单查询结果
*/
BillDTO getSourceBill(Long organizationId, String sourceBillNum);
2.2 客户端配置参数
# 客户端【来源系统编号】,需要在计费服务的来【源系统配置】中创建
# 将【来源系统编号】配置在此处,用于标识客户端所在系统
# 每次请求客户端会带上该参数用作【来源系统】校验
hzero.boot.charge.system-num
三、开发指南
3.1 账单回调逻辑开发
当在计费服务
完成账单支付
之后,计费服务
会自动发起账单回调
,用于将账单的支付结果状态
返还给来源系统
,计费服务
会根据来源系统配置
的账单回调URL
进行账单支付结果的回调(该回调URL
在计费服务
的来源系统配置
处进行维护)。
计费客户端已经封装了通用的用于回调的功能,在计费客户端默认增加了账单回调的路由,默认的回调路由为/v1/bill/callback
,该路由的执行方法会调用org.hzero.boot.charge.app.service.IBillCallbackService
来执行具体的回调业务逻辑。
3.1.1 回调路由控制器:org.hzero.boot.charge.api.controller.v1.CallbackController
/**
* 账单回调API 管理
*
* @author bergturing 2020/02/28 10:39
*/
@Api(tags = BootChargeSwaggerApiConfig.BILL_CALLBACK)
@RestController("billCallbackController.v1")
@RequestMapping("/v1/bill")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class CallbackController extends BaseController {
/**
* 账单回调服务对象
*/
private final IBillCallbackService billCallbackService;
@ApiOperation("账单支付结果回调执行逻辑")
@Permission(level = ResourceLevel.SITE)
@PostMapping("/callback")
public ResponseEntity<BillCallbackResult> callback(@RequestBody BillCallbackParam billCallbackParam) {
// 参数校验
this.validObject(billCallbackParam);
// 执行回调逻辑
return Results.success(this.billCallbackService.callback(billCallbackParam));
}
}
3.1.2 回调业务逻辑接口:org.hzero.boot.charge.app.service.IBillCallbackService
/**
* 账单回调服务接口
*
* @author bergturing 2020/02/28 15:07
*/
public interface IBillCallbackService {
/**
* 账单回调执行逻辑
*
* @param billCallbackParam 账单回调参数对象
* @return 账单回调结果
*/
BillCallbackResult callback(@Nonnull BillCallbackParam billCallbackParam);
}
3.1.3 回调业务逻辑实现
以上是回调的抽象设计,在实际业务场景中,业务系统
只需要继承实现抽象类org.hzero.boot.charge.app.service.AbstractBillCallbackService
来完成回调的实际业务逻辑,该抽象类封装了调用时处理的通用逻辑,并处理了一些常见的异常,业务系统只需要关注实现如下两个方法即可:
/**
* 判断当前回调是否已经完成回调
* 有具体需要进行判断的业务逻辑需求,重写该方法
*
* @param billCallbackParam 账单回调参数对象
* @return 账单回调结果对象
*/
protected boolean isCalled(@Nonnull BillCallbackParam billCallbackParam) {
log.debug("If You Need To Add Logic To Complete The Callback, Please Override The Method. Bill Callback Param ==> {}", billCallbackParam);
// 默认未完成回调
return false;
}
/**
* 执行具体的回调逻辑
*
* @param billCallbackParam 账单回调参数对象
* @return 账单回调结果对象
*/
protected abstract BillCallbackResult doCallback(@Nonnull BillCallbackParam billCallbackParam);