使用ShuanQCli快速开发对接接口

ShuanQCli工具介绍

ShuanQCli是用C++开发的控制台应用程序，用于给一些支持调用可执行程序的开发工具进行快速开发对接，调用它你可以不需要自行编写代码实现http请求、必要参数处理、传输加密、传输签名、返回验签、返回解密、防劫持验证、数据包过期验证等功能，它可以一键帮你实现这些，ShuanQCli应用程序已开源可在官方群文件或网盘内进行下载源码或者成品文件，支持多系统支持http/https请求，一些基于Unix操作系统如Linux、macOS、Android等可下载c++源码进行编译为可执行程序用法和Windows一致，以下我就以Windows环境进行使用演示

ShuanQCli工具的基本用法介绍

ShuanQCli工具是不能直接打开运行的，你需要在运行它之前将相关的参数传递给它才会为你工作，你可以在命令行窗口进行运行和传参

使用之前你需要先配置一下后台的功能才能与它进行交互对接使用

 /*
    以下是后台接口通信与加密配置需要设置的东西：
    接口传输验签方式：MD5
    接口响应验签方式：MD5
    接口响应验签参数字串计算规则：方式3
    接口数据传输加密算法：RC4
    接口数据传输加密后的编码方式：十六进制
    接口参数名传输是否加密：加密
    接口参数值传输是否加密：加密
    接口响应数据加密：加密
    栓Q网络验证系统官网：http://shuanq.cn
    当前对接案例作者QQ：775294825

    演示站点后台：http://demo.shuanq.cn
    账号：admin
    密码：123456
*/

在Windows中运行

双击打开ShuanQCli可执行程序，你会发现除了一闪而过的黑框，其余什么也没有也没有任何反映，那是因为程序已经运行完毕自动退出了，要想查看运行时发生了什么，你可以打开cmd输入文件名运行ShuanQCli可执行程序，你会看见会它输出内容了，但也仅仅只是输出了无用的内容，因为你没有给它传入相关的参数所以它并不会进行任何的操作处理，你可以在之前的命令后面输入空格然后输入--help，查看参数帮助

输入--help后可以看见它输出了10个选项(参数)，并告诉你参数名称，以及每个参数的说明，本身有对接过栓Q验证系统的相信对这些参数并不陌生，都是一些配置参数

参数详细说明：

参数	类型	必填	说明
--host	string	是	后台配置-后台地址是你搭建好栓Q验证系统的站点地址(协议头+域名,如http://demo.shuanq.cn)
--appId	string	是	后台配置-应用ID 填写你要对接的应用的ID(在后台应用列表可见应用ID)
--appKey	string	是	后台配置-应用密钥填写你要对接的应用的密钥(在后台应用列表可见应用密钥)
--rc4Key	string	是	后台配置-算法密钥-rc4 数据传输加密算法rc4算法的密钥(在接口通信与加密配置里可生成rc4密钥)
--signatureTimeLimitMinimum	int	是	本地配置-允许时差最小值允许每次请求的返回值过期时差最小值(一般为90-300，取决你自己多少都可以)
--signatureTimeLimitMaximum	int	是	本地配置-允许时差最大值允许每次请求的返回值过期时差最大值(一般为90-300，取决你自己多少都可以)
--requestApi	string	是	请求接口,你要请求哪个接口地址(不需要带上前缀协议头域名等)
--requestParams	string	否	请求接口所携带的参数值列表字符串(如a=b&b=c&c=d&d=e)
--requestParamsSplitString	string	否	请求参数分割字符串，默认值为&符号，假如你传入的是;号且要传入的请求参数是a=b&b=c&c=d&d=e，原本应该执行--requestParams a=b&b=c&c=d&d=e，实际应该执行--requestParams a=b;b=c;c=d;d=e
--requestParamsKVSplitString	string	否	请求参数键值分割字符串，默认值为=号,假如你传入的是>号且要传入的请求参数是a=b&b=c&c=d&d=e，原本应该执行--requestParams a=b&b=c&c=d&d=e，实际应该执行--requestParams a>b&b>c&c>d&d>e，如果你传入了请求参数分割字符串为;号，那么实际应该执行--requestParams a>b;b>c;c>d;d>e

我们不妨进行调用测试一下，请求获取应用信息接口，那么应该执行：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/app/get_app_info

这个命令的意思是后台地址是http://demo.shuanq.cn，应用ID为4，应用密钥是ec559db68538fefc3838452ab443d772，算法密钥是766d8bb7219cff1a3acd4bfd94807f54，允许时差最大最小值都是90秒，要请求的接口地址是/api/app/get_app_info

执行后，ShuanQCli工具会帮你封装好该接口的请求相关的信息并发送请求然后返回输出结果，你会看见它输出了一段JSON字符串，解析后可以看见一些重要的信息(如果什么都没有输出那么就是你传入的参数配置不正确很有可能与后台配置的对不上)

为什么没有传递请求参数也可以请求成功？那是因为获取应用信息这个接口除了应用ID参数以外没有别的必填参数了，那appid参数我也没有传入呀为什么也能请求接口获取成功？那是因为ShuanQCli工具在请求之前会自动帮你填充好“全局接口的公共参数”比如appid、签名参数-时间戳、签名参数-签名值等，因此也就不需要传入公共参数ShuanQCli会帮你处理好

那，如何验证ShuanQCli工具会自动添加公共参数呢，就拿单码应用卡密登录检查接口来说吧，它所需要的必要参数为appid(公共参数)、card=卡密(接口参数)，默认接口地址为/api/card_app/check，也就是说我们需要执行的命令是：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/card_app/check

解析JSON后可以看见请求是成功了，接口业务码返回的并不是成功码，并且也可以看群接口返回的message信息是卡密不能没空，因为我们并没有传递任何参数呀

那么该像这种必须要我们自己传入参数的接口调用时如何传入参数呢？
调用单码登录接口，通常要传的参数是card=用户的卡密&machine_code=用户的机器码，假设实际参数和值为：card=shuanq&machine_code=test，在命令后面加上--requestParams选项然后再加一个空格再输入card=shuanq&machine_code=test，即可将参数传给ShuanQCli工具，ShuanQCli工具会帮你处理好签名、加密等,(注意每个选项都是以空格隔开的)，如图：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/card_app/check --requestParams card=shuanq&machine_code=test

运行命令后发现报错了，那是因为执行的命令里面有命令行工具不允许的字符比如 & | $ %等

解决办法很简单，给参数内容加上双引号，代表这是一个字符串，命令：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/card_app/check --requestParams="card=shuanq&machine_code=test"

可以自定义参数分割符号吗？为什么就一定要使用&符号来分割参数呢，还记得上面的参数选项吗，里面有个选项是requestParamsSplitString就可以自定义分割符号，我们可以在命令后面加入这个--requestParamsSplitString=";" 代表我们的分割符号不再是默认的&而是;号，由于分割每个参数的键值的等号也可能会出现问题，并且后面加上--requestParamsKVSplitString=":" 代表我们键值分割符号不是=号而是:号，那么最终应该执行命令是：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/card_app/check --requestParams="card:shuanq;machine_code:test" --requestParamsSplitString=";" --requestParamsKVSplitString=":"

请求其他也可也是用一用发方法，所有接口都是通用的，如果你在开发中调用也是跟在命令行里输入命令调用一样的方法，详情可见下方小案例用Python语言调用开发测试

在linux中运行

在linux中运行和在Windows中运行的调用方法是一模一样的，只不过文件名字不一样，我这边下载了ShuanQCli工具的c++源码在linux系统编译后得到了ShuanQCli这个二进制文件，然后我们直接运行它，输入./ShuanQCli，你会发现和Windows的是一样的

同样的输入--help出现参数选项帮助

同样的调用获取应用信息接口测试

同样的调用单码登录接口并传参测试

更多接口可自行测试，和Windows用法是一样的，只不过ShuanQCli文件名字不一样而已

ShuanQCli返回结构字段说明

示例调用返回结果：

{
    "isException":false,
    "requestResult":true,
    "responseCode":1,
    "responseMessage":"登录成功",
    "requestDataSignatureVerify":true,
    "requestSafeCodeVerify":true,
    "requestDataTimeDifferenceVerify":true,
    "decryptResponseData":"{"cardInfo":{"id":33,"card":"ShuanQ","time_type":6,"time_value":1,"addtime":1663291829,"endtime":253370736000,"usetime":1664298731,"status":1,"private_data":[],"token":"7b226964223a33332c22737461727454696d65223a313637333632313230347d","point":0},"surplusTime":{"second":251696854536,"minute":55,"hour":0,"day":2913158},"expireTimeStr":"9999-01-01 00:00:00","moreOtherData":{"api_extra_data":"","request_safe_code":"xcgthkkmbpuvyipgxkgvxmxkwlegzatn"}}"
}

字段名	类型	说明
isException	bool	是否异常
requestResult	bool	请求是否成功
responseCode	integer	接口业务码
responseMessage	string	接口返回信息
requestDataSignatureVerify	bool	响应返回值签名验证是否通过
requestSafeCodeVerify	bool	本次请求防劫持验证是否通过
requestDataTimeDifferenceVerify	bool	响应返回值时差验证是否通过
decryptResponseData	string(object)	接口返回的data业务信息(这是解密后的dataJson，可使用这里的数据进行业务逻辑开发)

使用ShuanQCli工具进行调试开发与对接案例

ShuanQCli工具可不是用来在命令行里面调用调试用的，那可就大材小用并且没有任何用处了，开发ShuanQCli工具是为了给很多开发语言、脚本对接栓Q验证时没有那么困难并且能对接上各种加密验签等功能不需要自己去进行开发，ShuanQCli工具会帮您搞定对接相关的代码逻辑

在Python语言进行调用开发对接

这里我写了一段非常基础的Python代码调用ShuanQCli工具并且捕获到调用结果打印测试，测试结果没有问题

这里测试传递参数让工具输出选项参数帮助，也是可以的(乱码不管它,编码问题没处理)

调用获取应用信息看看，我们在上面用命令行的方式执行命令是：

.\ShuanQCli-Windows-x64.exe --host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/app/get_app_info

那么在Python只需要拼接上这一段参数内容可以调用了--host=http://demo.shuanq.cn --appId=4 --appKey=ec559db68538fefc3838452ab443d772 --rc4Key=766d8bb7219cff1a3acd4bfd94807f54 --signatureTimeLimitMinimum=90 --signatureTimeLimitMaximum=90 --requestApi=/api/app/get_app_info

可以看见调用成功并且取得了结果

调用单码登录试试看，可以看见也是没有问题的

那调用的确是没有问题，但你不觉得很奇怪吗，比如这两个命令，头部命令好像是一模一样的，现在只是调用这两个接口，后续你可能调用更多的接口，你就得写很多的命令，而且头部都一样的，还特别的长，导致开发不好阅读代码

那为何不优化一下呢？比如定义一个全局公共的命令行头，只有结尾不一样而已，到时候调用命令的时候加上这个头然后自己再写结尾的命令不就行了吗，比如以下写法：

这样可简单多了也很好阅读，我们可以模拟实战开发一下，进行请求判断验签判断等出来，比如调用单码登录

其他接口也是一样的用法，这里就不多写了，可以自行研究尝试

最终的Python代码：

import os
import json

# 使用ShuanQCli工具以下是后台 接口通信与加密配置 需要设置的东西：
# 接口传输验签方式：MD5
# 接口响应验签方式：MD5
# 接口响应验签参数字串计算规则：方式3
# 接口数据传输加密算法：AES
# 接口数据传输加密后的编码方式：十六进制
# 接口参数名传输是否加密：加密
# 接口参数值传输是否加密：加密
# 接口响应数据加密：加密
# 栓Q网络验证系统官网：http://shuanq.cn
# 当前对接案例作者QQ：775294825 | 3333337752
#
# 演示站点后台：http://demo.shuanq.cn
# 账号：admin
# 密码：123456
ShuanQCliAppPath = 'C:\\Users\\Administrator\\Desktop\\ShuanQCli-Windows-x64.exe'  # ShuanQCli.exe文件路径

ShuanQ_Host = "http://demo.shuanq.cn"  # 后台配置-站点地址
ShuanQ_AppId = "4"  # 后台配置-应用ID-在应用列表获得
ShuanQ_AppKey = "ec559db68538fefc3838452ab443d772"  # 后台配置-应用密钥-在应用列表获得
ShuanQ_Rc4Key = "766d8bb7219cff1a3acd4bfd94807f54"  # 后台配置-算法密钥aes-在 接口通信与加密配置 里生成
ShuanQ_SignatureTimeLimitMinimum = 90  # 本地配置-允许请求时差最小值-单位为秒
ShuanQ_SignatureTimeLimitMaximum = 90  # 本地配置-允许请求时差最大值-单位为秒

# 公共命令行头
commonCommandHeader = ShuanQCliAppPath + " --host=" + ShuanQ_Host + " --appId=" + ShuanQ_AppId + " --appKey=" + ShuanQ_AppKey + " --rc4Key=" + ShuanQ_Rc4Key + " --signatureTimeLimitMinimum=" + ShuanQ_SignatureTimeLimitMinimum.__str__() + " --signatureTimeLimitMaximum=" + ShuanQ_SignatureTimeLimitMaximum.__str__()

command = commonCommandHeader + " --requestApi=/api/app/get_app_info"  # 获取应用信息的命令
result = os.popen(command).read()  # 调用命令执行并获取执行结果
print("调用获取应用信息结果：" + result)  # 打印结果


def cardLogin():
    command = commonCommandHeader + " --requestApi=/api/card_app/check --requestParams=\"card=shuanq&machine_code=test\""  # 单码登录的命令
    result = os.popen(command).read()  # 调用命令执行并获取执行结果
    if result == "":
        print("调用命令失败")
        return
    print("调用单码登录信息结果：" + result)  # 打印结果
    resultJson = json.loads(result)  # 解析JSON
    if resultJson["isException"]:  # 出现异常
        print("调用命令出现异常")
        return
    if not resultJson["requestResult"]:  # 响应数据验签检测未通过
        print("请求接口失败")
        return
    if resultJson["responseCode"] != 1:  # 接口业务码响应非成功-将服务器返回信息提示
        print(resultJson["responseMessage"])
        return
    if not resultJson["requestDataSignatureVerify"]:  # 响应数据验签检测未通过
        print("响应数据验签失败")
        return
    if not resultJson["requestSafeCodeVerify"]:  # 防劫持验证检测未通过
        print("检测到数据被劫持篡改了")
        return
    if not resultJson["requestDataTimeDifferenceVerify"]:  # 响应数据检测验证不通过
        print("响应数据异常，与服务器时差相差过多")
        return
    dataJson = resultJson["decryptResponseData"] # 到原始未加密的dataJson数据
    print("解密后的dataJson:" + dataJson)
    responseDataJson = json.loads(dataJson)  # 获取解密后的data json对象
    expireTimeStr = responseDataJson["expireTimeStr"]  # 卡密到期时间字符串
    cardTimeType = responseDataJson["cardInfo"]["time_type"]  # 得到卡密时长类型
    cardTimeValue = responseDataJson["cardInfo"]["time_value"]  # 得到卡密时长值
    cardToken = responseDataJson["cardInfo"]["token"]  # 得到本次登录的token
    print("登录成功，到期时间:" + expireTimeStr)


cardLogin()  # 调用单码登录方法

在其他语言、脚本进行调用开发对接

不管是Python语言还是其他语言或脚本工具都是可以像上面Python那样的写法调用ShuanQCli工具进行接口对接开发，不管您会不会Python，建议您都看一次上面的在Python语言进行调用开发对接 这个案例，只要你的开发语言、脚本实现了调用命令行并获取到结果就可以使用ShuanQCli工具进行对接开发！

最后修改时间： 2 年前