Skip to content

home

Jump to bottom
李春寅 edited this page Jan 31, 2019 · 29 revisions

班布聚合API JAVA SDK

这份开源代码是班布聚合平台对接的工具包 http://www.asbamboo.com/page/developer 。

需求: SDK使用 JAVA SE 1.8 开发

你可以参考 https://github.com/asbamboo/java-sdk-demo 的实现来使用这个SDK。

使用这个SDK，第一步你需要初始化配置信息

只有在配置信息正确的情况下，才能使SDK实现班布聚合平台接口对接。

asbamboo.java.sdk.Configure 是这个SDK的配置信息类。你的程序运行时，首先需要初始化这个类中的成员变量。

API_URL: 接口请求的url, 默认请求平台的开发环境https://developer.asbamboo.com/api. 因此当你的程序需要正式发布时配置信息应该被修改为正式环境的url。 (重要)
API_APP_KEY: 平台系统内创建的应用的app_key (重要，必须配置)
API_SECRET: 与API_APP_KEY对应的app_secret (重要，必须配置)
API_FORMAT: 响应内容格式，目前仅支持json。默认值json。
API_VERSION: API接口版本，目前仅支持v1.0，默认值v1.0。
HTTP_REQUEST_TIMEOUT: api接口请求超时的时长（单位是毫秒），默认值30000
PROJECT_LOG_PATH: SDK打印的日志信息，默认值为System.getProperty("user.dir").concat(File.separator).concat("var").concat(File.separator).concat("project.log")，如果将它设置为null，则不打印日志。

接口请求与响应值的使用

SDK为每个接口编写了对应的request类和response类，request类用于设置请求参数，response类用于解析响应值。

每个接口都有一个request请求类：

  • 该类位于 package asbamboo.java.sdk.model
  • 类名为接口名(api_name)去掉点，每个单词首字母大写+Request后缀。如接口trade.pay的类名为TradePayRequest。
  • 设置请求参数的方法为前缀set+字段名（去掉下划线并且首字母用大写）。如trade.pay接口设置channel参数, tradePayRequest.setChannel("ALIPAY_QRCD");
  • 接口的公共参数不需要设置，SDK会自动为request设置公共参数，并且自动生成签名Sign字段。
  • 大部分接口在业务参数设置完成后调用request.post()方法请求接口，request.post()方法返回一个 response 。
  • 当通过表单提交的方式请求接口，页面会发生跳转（如api_name=trade.pay,channel=ALIPAY_PC）。此时请求请求的方式有点特殊，需要使用request.submit()方法，submit方法请求后没有reponse响应，需要通过notify_url或者return_url接收notify消息，处理响应结果。
  • 无论是request.post()还是request.submit()都需要使用try{...}catch(Exception e){...}处理

request.post()方法，返回一个reponse响应值解析类：

  • 该类位于 package asbamboo.java.sdk.model
  • 类名为接口名(api_name)去掉点，每个单词首字母大写+Response后缀。如接口trade.pay的类名为TradePayResponse。
  • 接收到响应值进行逻辑处理时，首先需要看reponse.getIsSuccess()是否为true。如果等于false那么本次请求是没有成功的。
  • 当response.getIsSuccess()方法得到false时，response.getMessage()方法可以得到错误消息。
  • response.getHttpCode()方法，获取本次请求的响应http code。
  • response.getHttpBody()方法，获取本次请求的响应值（未经过解析的）。
  • response.getHttpHeaders()方法，获取本次请求的响应Http header消息，返回值类型 Map<String, List<String>>。
  • response.getDecodedData()方法，获取本次请求的响应值（经过解析的后的 HashMap<String, Object>）。
  • response.getDataCode()方法，获取本次请求的响应值中的code参数。
  • 获取响应值中的某个字段的方法为前缀get+字段名（去掉下划线并且首字母用大写）。如trade.pay接口设置channel参数, tradePayRequest.getChannel()，该方法返回一个 String 类型的响应值。特别的，如果响应的http code不是200，那么调用get方法可能会发生异常。

notify通知的使用

SDK提供了为notify通知响应结果解析的类，notify通知是接口请求时通过参数notify_url或者return_url接收的响应结果。

  • notify类位于package asbamboo.java.sdk.notify下
  • 类名为接口名(api_name)去掉点，每个单词首字母大写+Notify后缀。如接口trade.pay的Notify类名为TradePayNotify。
  • 获取响应值中的某个字段的方法为前缀get+字段名（去掉下划线并且首字母用大写）。如trade.pay接口设置channel参数, tradePayRequest.getChannel()，该方法返回一个 String 类型的响应值。
  • 每个每个notify类都有一个checkSign()方法。你的程序逻辑必须事前判断notify.checkSign是否等于true，确定这是由 api.asbamboo.com 给你推送的消息。

比如你使用TradePayNotify的代码，应该像这样：

TradePayNotify notify = new TradePayNotify(request);
if(notify.checkSign()){
   // ...
   // notify.getIntradeNo(); //聚合系统内的订单号
   // notify.getChannel(); //支付渠道
   // ...
}

签名Sign的使用

asbamboo.java.sdk.Sign 类提供了三个签名生成的方法：

  • Sign.generate(HashMap<String, Object> data) 用于接口请求时生成sign参数
  • 参数data是 HashMap<String, Object>
  • 方法的响应值是签名字符串 String 类型
  • 方法会抛出异常Exception
  • Sign.genrateByResponse(HashMap<String, Object> response) 用于校验接口响应值签名Sign
  • 参数response，是接口响应值经过asbamboo.java.sdk.decode(接口响应值)以后得到的HashMap<String, Object>
  • 方法的响应值是签名字符串 String 类型
  • 方法会抛出异常Exception
  • Sign.genrateByNotify(HttpServletRequest request) 用于校验Notify通知的签名Sign

  • HttpServletRequest request 是notify接收的的request

  • 方法的响应值是签名字符串 String 类型

  • 方法会抛出异常Exception

  • 当 notify_url 是一个带有 query string 的 url, 时需要调用Sign.genrateByNotify(HttpServletRequest request, List<String> ex_parameters),将query string部分的key通过ex_parameters传入方法，表示该参数不参数签名。如https://your_notify?your_query_type=your_query_value，需要这样请求

    List<String> ex_parameters = new ArrayList<String>();
ex_parameters.add("your_query_type");
Sign.genrateByNotify(request, ex_parameters);
SDK 中包含的接口：

http://www.asbamboo.com

Clone this wiki locally