terjoy-api v3.0.0

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、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 的原型链上添加两个方法：

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

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

Methods

User

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

Pay

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

Admin

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

QRCode

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