XHTTP

xhttp 模块是基于 axios 二次封装，在 axios 的基础上增加了一些适配后台管理系统的功能。

功能

axios 功能参考官方文档：起步 | Axios中文文档 | Axios中文网 (axios-http.cn)

xhttp 除了支持 axios 的基础功能之外，封装了以下功能：

功能	介绍
消息提示	成功/失败/错误等消息和模态弹窗提示在浏览器端使用消息和模态弹窗提示在node 端使用 console 打印
忽略重复请求
超时重试
加入请求时间戳	请求时间戳可以用于调试接口
上传文件默认采用 formdata 格式	上传文件默认配置： `header:{Content-type: FORM_DATA = 'multipart/form-data;charset=UTF-8',}`
固定状态码提示和处理
ajax 错误日志收集钩子	`addAjaxErrorInfo`
全局请求 token
token 校验
token 刷新	传入 token 过期时间和时间间隔，在每次请求之前自动判断当前时间与 token 过期时间差小于指定刷新间隔时间，如果是，自动请求刷新 Token 接口刷新 Token，并将后续请求缓存；待刷新 Token 接口返回后，使用新的 token 请求缓存的请求。
错误清除 token
错误退出登录
格式化返回格式	格式化返回格式
提供请求处理钩子
	请求之前处理配置: `beforeRequestHook`
	请求成功处理: `transformRequestData`
	请求失败处理: `requestCatch`
	请求之前的拦截器: `requestInterceptors`
	请求之后的拦截器: `responseInterceptors`
	请求之前的拦截器错误处理: `requestInterceptorsCatch`
	请求之后的拦截器错误处理: `responseInterceptorsCatch`

默认状态码检查：

状态码	提示文案	操作
400	默认错误，返回服务端返回消息提示
401	用户没有权限（令牌、用户名、密码错误）!
403	用户得到授权，但是访问是被禁止的!
404	网络请求错误,未找到该资源!
405	网络请求错误,请求方法未允许!
408	网络请求超时!
500	服务器错误,请联系管理员!
501	网络未实现!
502	网络错误!
503	服务不可用，服务器暂时过载或维护!
504	网络超时!
505	http版本不支持该请求!

安装

可以引入 sewen-ui 库

npm install sewen-ui

也可以直接单独使用 xhttp 库

npm install xhttp

使用

TypeScript

引入 xhttp 库:

import { createXhttp } from 'sewen-ui/xhttp'

export default createXhttp({
    tokenKey: 'test-token', // token key值，传入token key值，默认使用内部获取方法
    tokenExpires: 1, // token 过期时间
    storageType: 'cookie', // 存储token 方法
    addAjaxErrorInfo: (error) => {
        console.log("🚀 ==========错误日志收集方法===========", error)
    },
    getToken: () => {
        console.log('==============获取本地token 方法============')
        return '1234567890'
    },
    logout: () => {
        console.log('==============logout 退出登录方法============')
    },
    statusMap: {
        400: {
            msg: '400状态码',
            callback: () => {
                console.log('=============400状态码相关处理函数===============')
            },
        },
        401: {
            msg: '401状态码',
            callback: () => {
                console.log('=============401状态码相关处理函数===============')
            },
        },
        402: {
            msg: '402状态码',
            callback: () => {
                console.log('=============402状态码相关处理函数===============')
            },
        },
        404: {
            msg: '404状态码',
            callback: () => {
                console.log('=============404状态码相关处理函数===============')
            },
        },
        500: {
            msg: '500状态码',
            callback: () => {
                console.log('=============404状态码相关处理函数===============')
            },
        }
    }
},
    {
        requestOptions: {
            urlPrefix: 'api'
        }
    });

使用 xhttp 库：

import defHttp from '@/packages/http/index'

interface AccountInfoModel {
    email: string;
    name: string;
    introduction: string;
    phone: string;
    address: string;
}

export function setAccountInfo(params: AccountInfoModel) {
    return defHttp.post<AccountInfoModel>(
        {
            url: '/acount/post',
            params,
        },
        {
            errorMessageMode: 'modal',
        },
    );
}

export function getAccountInfo(params: AccountInfoModel) {
    return defHttp.get(
        {
            url: '/acount/get',
            params
        },
        {
            successMessageMode: 'message',
            errorMessageMode: 'message',
        },
    );
}

请求参数

方法	参数	参数可选值	说明
`get(options,msgOpt)`	options		axios 请求参数
	msgOpt	errorMessageMode、successMessageMode	消息类型参数
	`msgOpt.errorMessageMode`	modal、message、none	错误消息提示
	`msgOpt.successMessageMode`	modal、message、none	成功消息提示

响应数据

默认服务端返回默认为以下数据格式：

{
    'code': 0, // 0 表示成功，-1 表示失败
    'message': '返回消息',
    'result': {} // 响应结构
    }
}

如果服务端返回接口无法返回以上固定格式，则需要在 createXhttp 第一个参数传入 formatResponse 方法，对返回的数据格式进行格式化。

如服务端返回如下格式：

{
    "Code": 200, // 状态码
    "Msg": "OK", // 提示信息
    "Data": {} // 数据
}

则在创建 http 实例时，配置如下：

import { createXhttp } from 'sewen-ui/xhttp'

export default createXhttp({
    tokenKey: 'test-token', // token key值，传入token key值，默认使用内部获取方法
    tokenExpires: 1, // token 过期时间
    formatResponse: (data)=> {//参数 formatResponse 方法，对返回的数据格式进行格式化。
        return { // 将服务端返回的数据格式化
            code: data.Code,
            message: data.Msg,
            result: data.Data
        }
    } , // 存储token 方法
},
{
    requestOptions: {
        urlPrefix: 'api'
    }
});

默认配置参数

createXhttp(transformOpt: transformOptType, axiosOpt: Partial<CreateAxiosOptions>) 方法参数

transformOpt 参数

参数	功能	类型	默认值
`Message`（可选）	消息提示组件	`Function`
`Modal`（可选）	模态弹窗提示组件	`Function`
`tokenKey`（可选）	登录 token Key 值	`string`	`Bearer`
`tokenExpires`（可选）	登录 token 过期时间	`number`	7 天
`storageType`（可选）	token 存储类型	`localStorage` 或 `sessionStorage` 或 `cookie`	`localStorage`
`getToken`（可选）	获取 token 方法	`Function`
`setToken`（可选）	设置 token 方法	`Function`
`logout`（可选）	退出登录方法	`Function`
`addAjaxErrorInfo`（可选）	添加 ajax 错误日志方法	`Function`
`statusMap`（可选）	状态码和处理方法 map 对象	`Record<number, any>`
`refreshTokenConfig`（可选）	刷新 token 相关配置	`refreshTokenType`	默认为空，不自动刷新 Token
`authorizationKey`	token 验证 key 值	`string`	`Authorization`

refreshTokenConfig 参数

refreshTokenConfig 默认为空，不刷新 Token，传入 refreshTokenConfig 相关配置后，根据传入 token 过期时间和时间间隔，在每次请求之前自动判断当前时间与 token 过期时间差小于指定刷新间隔时间，如果是，自动请求刷新 Token 接口刷新 Token，并将后续请求缓存；待刷新 Token 接口返回后，使用新的 token 请求缓存的请求。

refreshTokenConfig 相关配置：

参数	类型	说明
url （必填）	string	刷新 token url
interval （必填）	number	token 刷新间隔（单位为毫秒）
expires（选填）	number	token 过期时间（单位为毫秒）
tokenExpiresKey（必填）	string	token 过期时间本地存储的 key，如果没有传入expires，则自动从本地通过 tokenExpiresKey 获取 token 过期时间
refreshIdKey（选填）	string	token 刷新id 本地存储的 key，如果没有传入 refreshIdKey，则在刷新 token 时不会向后端传递 refreshId 参数
refreshId（选填）	string	token 刷新id，如果不传，则不会向刷新 token 接口传入该参数
params（选填）	object	刷新 token 接口额外参数

刷新 token 配置使用方法：

创建登录 xHttp 请求:

import { createXhttp } from 'sewen-ui/xhttp'

export default createXhttp({
    tokenKey: 'test-token', // token key值，传入token key值，默认使用内部获取方法
    tokenExpires: 1, // token 过期时间
    storageType: 'cookie', // 存储token 方法
    refreshTokenConfig: { // token 自动刷新配置
        url: '/refresh-token', // 刷新 token url
        interval: 20 * 60 * 1000, // token 刷新时间间隔为 20 分钟
        tokenExpiresKey: 'test-tokenExpiresKey', // token 过期时间存储 key
        refreshIdKey: 'test-refreshIdKey', // 存储 refreshId 刷新 token id 的 key, 选填，不传入则不会向刷新token 接口中传入 refreshId 参数
       // expires: null, // 登录请求接口中，token 过期时间为空
       // refreshId: null, // 登录请求接口中，refreshId 刷新 token id 为空
      
    },
    addAjaxErrorInfo: (error) => {
        console.log("🚀 ==========错误日志收集方法===========", error)
    },

    logout: () => {
        console.log('==============logout 退出登录方法============')
    }
},
    {
        requestOptions: {
            urlPrefix: 'api'
        }
    });

定义登录和刷新 token 方法：

import xHttp from '@/packages/http/index'

interface loginModel {
    name: string; // 用户名
    password: string; // 密码
}

interface tokenRefreshModel {
    expire: string; // token 过期时间
    token: string; // token
    refreshId: string; // 刷新token id
}

export function login(params: loginModel) {
    return xHttp.post<loginModel>(
        {
            url: '/login',
            params,
        },
        {
            errorMessageMode: 'modal',
        },
    );
}

export function refreshToken(params: tokenRefreshModel) {
    return xHttp.get(
        {
            url: '/refresh-token',
            params
        },
        {
            successMessageMode: 'message',
            errorMessageMode: 'message',
        },
    );
}

3.使用 Http 登录请求获取 token 并存储 token、token 过期时间和刷新 token id，并存入本地：

import { login } from '你的api路径/login'
import Cookies from 'js-cookie'

const {
    expire, // token 过期时间
    token, // token
    refreshId,// 刷新token id
} = await login()

// 存储 token, 注意存储的 token key和存储方案需要在 createXhttp 参数相同！
Cookies.set('test-token', token);
//存储 token 过期时间，注意存储的 token 过期时间和存储方案需要在 createXhttp 参数相同！
Cookies.set('test-tokenExpiresKey', expire);
// 存储刷新 token id，注意存储的刷新 token id 和存储方案需要在 createXhttp 参数相同！
Cookies.set('test-refreshIdKey', refreshId);

刷新 token 接口说明

刷新 token 接口默认为 post 请求，返回接口格式默认如下：

 {
 'code': 0,
 'message': '刷新 token 消息提示',
 'result': {
     'token': `刷新后的 token`,
     'expires': '刷新后的过期时间，默认接收时间戳'
  }
}

axiosOpt 参数

参数	功能	默认值
axios 配置
`authenticationScheme`	HTTP 验证	authentication schemes，e.g: Bearer authenticationScheme: 'Bearer',
`timeout`	接口超时等待时间	10 * 1000
`headers`	http 头参数	`{ 'Content-Type': ContentTypeEnum.JSON }` 如果是form-data格式： `{ 'Content-Type': ContentTypeEnum.FORM_URLENCODED }`
`transform`	数据处理方式
`requestOptions`	请求选项
`requestOptions.joinPrefix`	是否将 prefix 添加到url	`true`
`requestOptions.isReturnNativeResponse`	是否返回原生响应头比如：需要获取响应头时使用该属性	`false`
`requestOptions.isTransformResponse`	需要对返回数据进行处理	`true`
`requestOptions.joinParamsToUrl`	post请求的时候添加参数到 url	`false`
`requestOptions.formatDate`	格式化提交参数时间	`true`
`requestOptions.errorMessageMode`	消息提示组件	`message`(可选参数： `none 或 modal 或message`)
`requestOptions.apiUrl`	接口地址	`''`
`requestOptions.urlPrefix`	接口拼接地址	`''`
`requestOptions.joinTime`	是否加入时间戳	`true`
`requestOptions.ignoreCancelToken`	忽略重复请求	`true`
`requestOptions.withToken`	是否携带token	`true`
`requestOptions.retryRequest`	请求重试配置
`requestOptions.retryRequest.isOpenRetry`	是否开启请求重试	`true`
`requestOptions.retryRequest.count`	请求重试次数	`5`
`requestOptions.retryRequest.waitTime`	请求重试等待时间	`100`

贡献者

Sewen

Creator

XHTTP #

功能 #

安装 #

使用 #

TypeScript #

请求参数 #

响应数据 #

默认配置参数 #

transformOpt 参数 #

refreshTokenConfig 参数 #

刷新 token 接口说明 #

axiosOpt 参数 #

贡献者 #