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

2. 在实际使用中，在引入（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 端生成二维码 |