• 计费服务客户端


    组件编码 hzero-boot-charge

    一、简介

    1.1 概述

    计费服务接口集成,使用feign调用实现,依赖客户端操作可以避免复杂的Feign调用处理,开发者不用关注客户端与服务端数据交互细节,便于使用和升级维护。

    业务系统可以根据计费服务提供的功能,通过客户端使用计费服务,达到增强业务系统功能的目的。

    1.2 特性

    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);