奇门ISV测试方案说明文档.docx

奇门对接方案说明文档前言奇门对接流程：接口开发阅读白皮书和测试说明文档，完成所需接口的开发，不仅是接口开发，还包括对应的业务功能。挡板自测也称二方联调，首先配置自测的参数，然后完成和奇门挡板的自测。三方联调自测通过之后开始三方联调，首先配置联调的参数，然后进行ERP-奇门-WMS联调。商家验收联调通过后，在奇门预发环境配置真实的参数，商家发布真实商品进行验收。系统上线经奇门确认商家验收通过后，可切换到奇门的正式环境，上线完成。整个奇门ERP与WMS互相调用的时序图如下所示，分正向和反向。所谓的正向，我们约定为ERP发起，调用WMS的接口，接口实现方是WMS（如：商品同步接口，出库单创建和入库单创建接口等）；同理，反向即WMS发起，调用ERP的接口，接口实现方是ERP（如：出库、入库确认接口，缺货通知接口等）。在挡板自测环节：（1）ERP测试正向：ERP发起接口调用，奇门挡板会模拟WMS向ERP返回响应；（2）ERP测试反向，需要ERP模拟WMS向自己发起调用请求，测试自己的ERP系统是否能接收到请求并正确响应。WMS挡板自测同理。如果代码还没有实现调用的方法，可以利用chrome浏览器或者火狐浏览器的插件Rest Client来测试。关于Rest Client安装，可以在浏览器应用中心里搜索rest client关键字，随便安装一个即可，chrome浏览器下载应用有时候网络不畅，换个时间段多试几次，火狐相对好一些。下载界面如下：测试的方法如下：1. 关于配置参数首先解释一下奇门的环境和ISV的环境。奇门总共有三个环境，分别是日常环境（即沙箱环境），预发环境和线上环境，其中日常环境配置的都是测试数据，预发和线上配置的都是真实数据。对接过程中，参数配置遵循的原则如下。其中，商家验收通过之后，奇门确认没有问题，可以切换到线上环境：在奇门的参数配置中主要涉及到下面几个重要参数：1) ERP_APPKEY2) ERP_URL3) WMS_APPKEY4) WMS_URL5) CUSTOMER_ID奇门的作用是针对不同的应用（比如一个ERP）发起的请求，正确的路由给其对应的另一方（比如对应的WMS），如下图。那么奇门路由的策略是怎样的呢？下面是一段标准的调用URL的例子：/router/qimen/service?method=*×tamp=2015-04-26 20:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*其中，各个字段的含义，请见下表：字段名含义域名/router/qimen/service是奇门测试环境的域名地址，自测和联调的时候都是使用这个域名，注意，千万不要直接写成对方ISV应用的服务地址Method调用的方法timestamp使用当前调用接口的时间，做encode编码 format暂时只支持xmlappkey调用方自己的appkey，即来源appkeysignMD5加密，加密策略参看附录1customerId是仓储为这个用户分配的唯一的用户帐号，自测和联调的时候由奇门统一分配，等到切到预发和正式环境的时候，使用仓储自己分配真实的值，注意，对于一个WMS，这个customerId一定要保证唯一言归正传，奇门如何根据这一段URL来做路由的呢？奇门首先会根据调用url中的customerId来找这个用户配置的ERP信息和对应的WMS信息，因此customerId一定要唯一。需要配置参数的地方有三个，这里分别介绍一下：注：Q:什么是沙箱appkey，怎么获取？A:登陆开放平台，进入控制台，找到对接奇门要使用的应用，应用设置里有沙箱环境的参数。2. 关于挡板自测2.1 ERP端：2.1.1 ERP自测正向调用ERP端做正向接口调用，奇门测试挡板会模仿WMS返回信息，挡板自测调用地址如下(只需修改红色标示的method方法字段)：/router/qimen/service?method=taobao.qimen.entryorder.cancel×tamp=2015-04-26 20:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是ERP的appkey；sign签名:采用md5不可逆加密方法，具体操作见附录2；v字段：我们是通过v来区分1.0版本（白皮书v1.5）和2.0版本（白皮书v2.0），不同的v，调用的奇门测试挡板是不一样的，请注意！暂时只有1.0和2.0两种。以后进行三方联调之后，v的值如何定义由双方自行协商了。2.1.2 ERP自测反向调用ERP需模拟WMS发起请求，访问url和WMS调用奇门的url一致，奇门测试环境调用地址如下，其中，需要修改红色标示的method方法字段：/router/qimen/service?method=taobao.qimen.entryorder.report×tamp=2015-04-26 00:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是wms的appkey；2.2. WMS端：2.2.1 WMS自测正向调用WMS需模拟ERP发起请求，访问url和ERP调用奇门的url一致，奇门测试环境调用地址如下，其中，需要修改红色标示的method方法字段：/router/qimen/service?method= taobao.qimen.entryorder.query×tamp=2015-04-26 00:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是ERP的appkey。2.2.2 WMS自测反向流程奇门挡板会模仿ERP返回信息，奇门测试环境调用地址如下(只需修改红色标示的method方法字段)：/router/qimen/service?method=taobao.qimen.entryorder.report×tamp=2015-04-26%2000:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是WMS的appkey；附录1 sign签名算法：我们用ERP调用奇门URL演示加密算法：/router/qimen/service?method=taobao.qimen.entryorde.rquery×tamp=2015-04-26 00:00:07&format=xml&app_key=testerp_appkey&v=2.0&sign=abc&sign_method=md5&customerId=stub-cust-code1、输入参数为method= taobao.qimen.entryorder.query timestamp=2015-04-26 00:00:07 format=xml app_key= testerp_appkey v=2.0 sign_method=md5 customerId =test2、按首字母升序排列app_key= testerp_appkeycustomerId = stub-cust-codeformat=xmlmethod= taobao.qimen.entryorder.querysign_method=md5 timestamp=2015-04-26 00:00:07 v=2.0 3、连接字符串连接参数名与参数值,并在首尾加上secret，此处假设secret=test，如下： testapp_keytesterp_appkeycustomerIdstub-cust-codeformatxmlmethodtaobao.qimen.entryorder.querysign_methodmd5timestamp2015-04-26 00:00:07v2.0bodytest其中：body用请求中的body内容代替4、生成签名 sign32位大写MD5值- D06D88CB34B2EC0E5C9BAB396C9542B65、拼装URL请求将所有参数值转换为UTF-8编码，然后拼装，通过浏览器访问该地址，即成功调用一次接口，如下:/router/qimen/service?method=taobao.qimen.entryorder.query×tamp=2015-04-26 00:00:07&format=xml&app_key=testerp_appkey&v=2.0&sign= D06D88CB34B2EC0E5C9BAB396C9542B6 &sign_method=md5&customerId=stub-cust-code奇门对于sign签名的校验逻辑：ERP通过自己的secret做了sign签名，奇门在收到请求的时候，同时也用这个ERP的secret去做签名校验，校验通过之后，再去拿即将路由到的WMS的secret进行重新加密，然后将新的sign发给WMS，由于WMS只知道自己的secret签名，所以奇门在sign上做了一次转换，这样WMS在收到的请求中就可以用自己的secret做一次签名校验。签名算法示例：package md5;import java.io.UnsupportedEncodingException;import .URLDecoder;import java.security.MessageDigest;import java.security.NoSuchAlgorithmException;import java.util.Arrays;import java.util.HashMap;import java.util.Map;/* * Created by jiqian.zzp on 2015/7/6. */public class QimenSign public static void main(String args) String url = /top/router/qimen/service? + method=your_method& + timestamp=2015-04-26%2000:00:07& + format=xml& + app_key=your_appkey& + v=your_version& + sign=your_sign& + sign_method=md5& + customerId=your_customerId; String body = your_body; String secretKey = your_secretKey; QimenSign sign = new QimenSign(); String md5 = sign.sign(url, body, secretKey); System.out.println(md5);/6A4B6FCFAFE80280565406E110C27DC8 public String sign(String url, String body, String secretKey) Map params = getParamsFromUrl(url); / 1. 第一步，确保参数已经排序 String keys = params.keySet().toArray(new String0); Arrays.sort(keys); / 2. 第二步，把所有参数名和参数值拼接在一起(包含body体) String joinedParams = joinRequestParams(params, body, secretKey, keys); /your_secretKeyapp_keyyour_appkeycustomerIdyour_customerIdformatxmlmethodyour_methodsign_methodmd5timestamp2015-04-26 00:00:07vyour_versionyour_bodyyour_secretKey System.out.println(joinedParams); / 3. 第三步，使用加密算法进行加密（目前仅支持md5算法） String signMethod = params.get(sign_method); if (!md5.equalsIgnoreCase(signMethod) /TODO return null; byte abstractMesaage = digest(joinedParams); / 4. 把二进制转换成大写的十六进制 String sign = byte2Hex(abstractMesaage); return sign; private Map getParamsFromUrl(String url) Map requestParams = new HashMap(); try String fullUrl = URLDecoder.decode(url, UTF-8); String urls = fullUrl.split(?); if (urls.length = 2) String paramArray = urls1.split(&); for (String param : paramArray) String params = param.split(=); if (params.length = 2) requestParams.put(params0, params1); catch (UnsupportedEncodingException e) / TODO return requestParams; private String byte2Hex(byte bytes) char hexDigits = 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F ; int j = bytes.length; char str = new charj * 2; int k = 0; for (byte byte0 : bytes) strk+ = hexDigitsbyte0 4 & 0xf; strk+ = hexDigitsbyte0 & 0xf; return new String(str); private byte digest(String message) try MessageDigest md5Instance = MessageDigest.getInstance(MD5); md5Instance.update(message.getBytes(UTF-8); return md5Instance.digest(); catch (UnsupportedEncodingException e) /TODO return null; catch (NoSuchAlgorithmException e) /TODO return null; private String joinRequestParams(Map params, String body, String secretKey, String sortedKes) StringBuilder sb = new StringBuilder(secretKey); / 前面加上secretKey for (String key : sortedKes) if (sign.equals(key) continue; / 签名时不计算sign本身 else String value = para