http 数据请求

数据请求功能插件的应用说明

安装

安装依赖

# 安装聚合包
npm i @plugins-core/main
# 安装独立功能库
npm i @plugins-core/http

代码中引用

// 聚合包
import { HttpRequest } from '@plugins-core/main'
const {
  Http,
  httpSetup,
  EXCEPTION_BUSINESS,
  EXCEPTION_AUTH_INVALID
} = HttpRequest

// 独立包
import {
  Http,
  httpSetup,
  EXCEPTION_BUSINESS,
  EXCEPTION_AUTH_INVALID
} from '@plugins-core/http'

旧版包

npm i @plugins/core

代码中引用

import { HttpRequest } from '@plugins-core/main'
const { Http, httpSetup, EXCEPTION_BUSINESS, EXCEPTION_AUTH_INVALID } = HttpRequest

项目中的适配

// src/config/settings/http.js

import { Message, MessageBox } from 'element-ui'
import { HttpRequest } from '@plugins-core/main'
// 业务项目中的系统退出登录函数
import { doAuth } from '@/business/system/auth'

const { Http, httpSetup, EXCEPTION_BUSINESS, EXCEPTION_AUTH_INVALID } = HttpRequest

// 定义项目应用的配置参数，在大多数情况下，仅需要配置 'baseUrl' 与 'exception' 两个属性
const options = {
  baseUrl: process.env.VUE_APP_API_URL,
  exception (message, type) {
    // 业务异常信息显示
    if (type === EXCEPTION_BUSINESS) {
      Message({
        message: message,
        duration: 5000,
        type: 'error'
      })
      return
    }

    // 系统异常处理
    MessageBox.alert(message, '错误', {
      type: 'error',
      center: true,
      showClose: false,
      callback () {
        // 用户登录权限失效处理（登录会话超时、用户权限变更等场景）
        if (type === EXCEPTION_AUTH_INVALID) {
          doAuth()
        }
      }
    })
  }
}

// 使用配置参数生成 http request 实例
const instance = new Http(options)

// 获取并输出 http 动作相应功能函数以及其他功能函数
export const {
  http,
  get,
  post,
  put,
  patch,
  del,
  // 强制取消所有正在执行的数据请求
  cancel,
  // 检查用户登录会话是否有效
  isSessionTimeout
} = httpSetup(instance)

/**
 * Http request 插件的全局安装
 * @deprecated
 */
export default {
  install (Vue) {
    Object.defineProperty(Vue.prototype, '$http', { value: http })
  }
}

注意

全局注册的 $http 对象不再推荐使用，其将在后续的项目中将移除该全局注册对象；若在项目中出现，仅出于兼容现有组件模块的目的

配置参数完整列表

{
  /**
   * 访问地址的基础前缀，若实际访问地址是以 http/https 开始，则使用实际地址，忽略前缀设定
   * @default `/`
   */
  baseUrl: string,
  /**
   * 执行刷新 refresh token 的 api 位置
   * @default `/auth/refresh-token`
   */
  refreshUrl: string,
  /**
   * 执行刷新时传递 refresh token 使用的请求参数名
   * @default `refreshToken`
   */
  paramRefreshToken: string
  /**
   * 登录会话有效时长，单位为分钟
   * @default 0
   */
  expiresIn: number,
  /**
   * 数据字段适配模型，用于适配服务器返回的数据字段，大多数情况下，应按照标准协议要求返
   * 回指定数据格式，但部分历史项目需要进行适配，此处提供了可兼容旧数据格式的方式
   * @default `accessToken`
   */
  keyAccessToken: string,
  /**
   * 会话超时时间字段名
   * @default `expiresIn`
   */
  keyExpiresIn: string,
  /**
   * 单次请求超时时间，单位：毫秒
   * @default 20000
   */
  timeout: number,
  /**
   * 异常状态信息处理
   * 业务错误/用户登录授权失效/系统错误时的相关信息展示
   *
   * @param {string} message - 错误/异常信息内容
   * @param {number} type - 错误/异常类型
   */
  exception (message: string, type: number): void
}

keyAccessToken 与 keyExpiresIn 属性作为数据字段适配模型，用于适配服务器返回的数据字段

大多数情况下，应要求服务端按 登录授权数据格式 返指定数据格式，但部分历史项目需要进行适配，此处提供了可兼容旧数据格式的方式，但 access 作为登录权限专用节点的要求是不变的

特别关注

在 RESTful API 接口规范 全面应用后，从实例中生成的 http 函数与 install 全局安装应被移除

意味着除了对旧有项目保持兼容外，不应再使用通用数据请求函数 http 以及全局安装后的 this.$http 来进行数据请求操作

API

httpMethod (url: string, data?: object, options?: object): Promise

http 数据请求接口调用方式，适用于 上述 示例中导出的所有请求类型对象 post、get、put、patch、del

• url

目标请求地址，地址分为两种类型：相对地址 和 完整地址。在使用 相对地址时，请注意检查位于 src/config/settings/http.js 文件的全局设置中 baseUrl 的指定位置，该变量在绝大多数情况下，指向了环境变量 .env 文件中设置的位置

• data

提交的数据参数

• options

配置参数，主要用于特殊情况下需要覆盖 axios 原生配置的情况，多数情况下不需要进行设置

应用实例

// 访问当前域服务
post('/user/list', { groupId: 1 })
  .then(resp => { ... })
  .catch(resp => { ... })

// 访问其他域服务
put('http://aaa.com/user/list', { groupId: 1 })
  .then(resp => { ... })
  .catch(resp => { ... })

/**
 * 应用 axios 原生参数
 * 第三个参数传递了 axios 插件的原生参数内容，实例中为指定本次请求的超时时间为 20 秒
 */
post('/file/upload', { groupId: 1 }, { timeout: 20000 })

项目中的应用

在完成了上文的项目适配后，接口使用的方式应引用该模块输出的函数进行使用，以下对 用户管理 功能的 CRUD 模块进行举例

// src/api/user.js 文件位置，通常应存放于 src/api 目录下

import { get, post, put, del } from '@/config/settings/http'

export function userAdd (data) {
  return post('/user/add', data)
}

export function userUpdate (data) {
  return put(`/user/update/${data.id}`, data)
}

export function userDetail (data) {
  return get(`/user/detail/${data.id}`)
}

export function userDelete (data) {
  return del(`/user/del/${data.id}`)
}

业务模块中的应用

在原则上，要求所有需要进行数据交互的操作，均在项目的 src/api/ 目录下进行定义并在业务功能中引用

特别注意

在 非特殊需求情况下，要完全避免在业务功能中直接使用 axios、HttpRequest 功能库以及 this.$http 全局安装的入口执行数据请求操作