terjoy-api

API for terjoy frontend.

Dependencies

• apib，请求方法库，基于 axios。
• crypto-js，加密方法库，提供 3DES 加解密算法和 Base64 编码的支持。

Install

npm

npm install terjoy-api --save

yarn

yarn add terjoy-api

Usage

import API from 'terjoy-api'
const api = new API(options)

Options

参数名	类型	说明
appType	string	业务系统标识
appVersion	string	业务系统版本
versionCode	string	业务系统版本编码
appKey	string	系统密钥
secretSeed	string	密钥种子（长度限定为 24）
baseUrl	string	请求的基地址
baseLoginUrl	string	登录接口的请求基地址
gatewayUrl	string	网关地址
getId	function	获取当前会话编号，确保在实际执行的时候返回一个有效字符串。
getKey	function	获取当前会话密钥，确保在实际执行的时候返回一个有效字符串。
handleMessage	function	业务系统接口请求未成功时进行调用该方法，参数为接口里面返回的 msg 字段。
handleError	function	接口请求失败时调用该方法，参数为请求失败时的错误对象。
debug	boolean	输出请求的日志（供开发调试使用）

其中，appType、appVersion、versionCode、appKey、secretSeed 为必传参数。

options 示例：

const api = new API({
  appType: '...',
  appVersion: '...',
  versionCode: '...',
  appKey: '...',
  secretSeed: '...',
  baseUrl: '...',
  getId: () => sessionStorage.getItem('sessionId'),
  getKey: () => sessionStorage.getItem('sessionKey'),
  handleMessage: (msg) => {
    console.warn(msg)
  },
  handleError: (error) => {
    console.error(error)
  }
})

api

api#request

调用 request 方法可以发起一个请求，该请求中的数据会进行加解密操作。

api.request(options)

• options.method 如果不给定，则默认为 POST 请求。
• options.data 应该是一个数据对象，用于指定传递给接口的参数。
• options.params 参数会被合并到 options.data 中，并在合并完成后进行移除。
• options 的其他参数将会原封不动的传给 axios 实例。
• 接口请求完成且判定为成功，如果返回的字段中包含 data 字段，将进行解密操作。

api#gateway

调用 gateway 方法将直接经过网关请求数据，是基于 request 方法的再封装。

api#inner

调用 inner 方法可以进行内部请求的调用，此时的请求方法默认为 POST，请求参数不会经过处理。通常用于内网接口的直接调用。

api#axios

api.axios 是对 axios 的引用。

api#login

api.login 为向后台发起登录请求的接口，接收的参数为进行登录的用户名和密码。

因编译的运行时的原因，v3 版本将 async/await 机制修改为常规的 Promise。

登录优先向 baseLoginUrl 参数发起请求，如果不存在则向 baseUrl 参数发起请求。如果都没有，将抛出一个错误。

登录分为三个步骤：

1. 向服务器请求登录的密钥，请求路径可由 genKeyPath 参数指定，默认为 /gen/key。
2. 发起登录请求，请求路径可由 loginPath 参数指定，默认为 /login。
3. 向服务器请求用于解密返回数据的密钥，请求路径可由 genUncPath 参数指定，默认为 /gen/unc。

登录为一个异步过程，如果中途出错，将会抛出错误。如果接口请求未出错，接口异步返回的结果为一个数组，由下面三个部分组成：

1. status，布尔值，登录是否成功。
2. step，整数，进行到第几步。如果为 4 表示请求已经成功。
3. result，当前接口获取到的结果。

注意，请求成功并不意味着登录成功。

登录代码示例：

...
      this.$api.login(this.loginForm.name, this.loginForm.password).then(res => {
        const [isSuccess, step, result] = res
        if (isSuccess) {
          // 登录成功
          ...
        } else {
          ...
          this.$message.warning('登录失败！' + result.msg || '')
        }
      }).catch(res => {
        ...
        this.$message.warning('请求失败，请稍候再试')
      })
...

内置模块

提供部分内置模块，使用方式为直接引入即可，如：

import API from 'terjoy-api'
 
import 'terjoy-api/lib/admin'
import 'terjoy-api/lib/pay'

在进行 API 的实例化时，会一并实例化注册过的模块，模块的实例将直接挂载到 API 的实例上。

const api = new API(options)
 
api.Admin...
 
api.Pay...

内置模块接收一个名为 base${name}Url 的参数，可以覆盖 baseUrl 参数。

当前内置模块以及所提供的方法请参阅下面的 Methods 章节。

外部模块

本项目支持引入外部编写的模块，方法如下：

1. 创一个模块文件（这里假设名称为 foo.js），编写如下代码：

'use strict'
 
import API from 'terjoy-api'
const Base = API.Base
 
class Foo extends Base {
  constructor(options) {
    super(options)
 
    if (options.baseFooUrl) {
      this.baseUrl = options.baseFooUrl
    }
  }
}
 
Base.register({Foo})
 
export default Foo
 

1. 在实际使用中，在引入（import API from 'terjoy-api'） 模块之后，再引入上面编写的模块即可：

import './foo.js';

特别说明，模块的注册方法 .register 是在 Base 类上面实现的。API 继承过去的 .register 方法在使用时会因为作用域的不同会导致在进行调用的时候注册的模块无法挂载。

Vue 插件支持

实例上直接提供 install 方法，供 Vue 进行插件调用：

Vue.use(api)

api 此时已经是实例化之后的对象了，故此不在需要额外传入参数。未来某个版本可能会支持动态引入参数以便于重新构建 API 实例。

调用之后 API 将作为静态属性直接挂载到 Vue 上。

同时会在 Vue 的原型链上添加两个方法：

方法名称	说明
$api	API 实例
$request	请求方法的快捷方式

成功注册的模块，在 Vue 进行插件调用的时候会一并将对应的方法挂载到原型链上，名称为 $$ 后面拼接模块名称的小写。

例如：如果通过 import 'terjoy-api/lib/admin' 引入了 Admin 模块，则在插件调用之后，Vue 的原型链上将会增加一个 $$admin 方法指向该模块的实例。

Methods

User

User 模块提供以下方法的封装：

方法名	说明
getUserInfo	获取用户信息
getUserMenu	获取用户菜单
getRoleList	获取角色列表
getAllMenus	获取当前所有的权限菜单
getRoleMenu	获取角色当前拥有的菜单
setRoleMenu	设置角色的菜单
addMenu	添加菜单
updateMenu	更新菜单
delMenu	删除菜单
addRole	添加角色
updateRole	更新角色
delRole	删除角色
getUserRole	获取用户分配的角色
setUserRole	更新用户的角色

Pay

Pay 模块提供以下方法的封装：

方法名	说明
getAccountList	账户信息查询
lockAccount	客服锁定账户
unlockAccount	客服解锁账户
getAllBankInfo	获取所有银行编码
getNoRecordList	获取未记账记录（无车承运）
getOilChargeInList	油票充值记录查询
setPayPassword	设置新的支付密码
sendVerifySMSCode	重置密码时发送短信验证码
checkPayPassword	检查支付密码强度
verifyPayPassword	验证支付密码
verifySMSCode	验证短信验证码

Admin

Admin 模块提供以下方法的封装：

方法名	说明
getNoRecordList	获取未记账记录（无车承运）
recordIn	对未记账记录进行记账
adjustAmount	根据 tjid 调整余额
shipperBack	厂家或者信息部支付运费退回
queryBankCard	查询个人绑卡情况
unbindBankCard	解绑银行卡
getNocarBalance	查询无车承运银行卡余额
getBankList	查询支持的银行列表
getAccountList	账户信息查询
lockAccount	锁定账户
unlockAccount	锁定账户
resetAccountPassword	重置支付密码
getRecordList	账户转账记录列表
getTransferList	获取财务专用账户转账记录列表
getTransferDetail	获取财务专用账户转账记录详情
initAccount	账户初始化，生成账户、余额以及零钱开户
getComAccountList	查询初始化账户列表（企业账户）
bindBankCardStepOne	绑卡第一步信息录入
verifyBindBySMSCode	个人账户绑卡第二步短信验证
verifyBindByTransfer	个人账户绑卡第二步小额鉴权验证
getBankInfoByCardNo	根据银行卡号获取银行信息
addBank	新增银行
updateBank	修改银行信息
delBank	删除银行
getAllBanks	获取所有银行信息

QRCode

QRCode 模块提供以下方法的封装：

方法名	说明
getAllBusiness	获取所有业务类型列表
getBusinessList	查询业务类型
saveBusiness	创建或修改业务大类
getAllScene	获取场景分类列表
getSceneList	查询场景类型
saveScene	创建或修改场景分类
downloadQRCode	二维码下载
getQRCodeList	个人零钱二维码，企业零钱二维码查询
updateQRCode	修改二维码有效期
deleteQRType	删除二维码类型
getAllQRType	获取二维码类型列表
getQRTypeList	查询二维码类型
saveQRType	创建或修改二维码类型
checkQRCode	二维码信息校验
createQRCode4APP	APP 端生成二维码
createQRCode4WEB	WEB 端生成二维码