TypeScript实战之用TS封装Axios

·  阅读 5173
TypeScript实战之用TS封装Axios

持续创作,加速成长!这是我参与「掘金日新计划 · 6 月更文挑战」的第28天,点击查看活动详情

简介

这是TypeScript实战的第三篇文章。前面两篇笔者分别介绍了在VuexPinia中怎么使用TypeScript以及VuexPinia的区别。今天我们再用TypeScript封装一遍Axios。希望能进一步巩固TypeScript的基础知识。

Axios几个常用类型

在使用TypeScript封装Axios之前我们先来看看Axios几个重要的类型。

AxiosRequestConfig

AxiosRequestConfig是我们使用axios发送请求传递参数的类型。当然它也是我们请求拦截器里面的参数类型。

axios(config: AxiosRequestConfig)
复制代码

可以看到,这个config里面的参数还是挺多的。我们常用的有url、method、params、data、headers、baseURL、timeout

export interface AxiosRequestConfig {
  // `url` 是用于请求的服务器 URL
  url?: string;
  
  // `method` 是创建请求时使用的方法
  method?: Method;
  
  // `baseURL` 将自动加在 `url` 前面,除非 `url` 是一个绝对 URL。
  // 它可以通过设置一个 `baseURL` 便于为 axios 实例的方法传递相对 URL
  baseURL?: string;
  
  // `transformRequest` 允许在向服务器发送前,修改请求数据
  // 只能用在 'PUT', 'POST' 和 'PATCH' 这几个请求方法
  // 后面数组中的函数必须返回一个字符串,或 ArrayBuffer,或 Stream
  transformRequest?: AxiosTransformer | AxiosTransformer[];
  
  // `transformResponse` 在传递给 then/catch 前,允许修改响应数据
  transformResponse?: AxiosTransformer | AxiosTransformer[];
  
  // `headers` 是即将被发送的自定义请求头
  headers?: any;
  
  // `params` 是即将与请求一起发送的 URL 参数
  // 必须是一个无格式对象(plain object)或 URLSearchParams 对象
  params?: any;
  
  // `paramsSerializer` 是一个负责 `params` 序列化的函数
  paramsSerializer?: (params: any) => string;
  
  // `data` 是作为请求主体被发送的数据
  // 只适用于这些请求方法 'PUT', 'POST', 和 'PATCH'
  // 在没有设置 `transformRequest` 时,必须是以下类型之一:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - 浏览器专属:FormData, File, Blob
  // - Node 专属: Stream
  data?: any;
  
  // `timeout` 指定请求超时的毫秒数(0 表示无超时时间)
  // 如果请求话费了超过 `timeout` 的时间,请求将被中断
  timeout?: number;
  
  // 超时提示消息
  timeoutErrorMessage?: string;
  
  // `withCredentials` 表示跨域请求时是否需要使用凭证
  withCredentials?: boolean;
  
  // `adapter` 允许自定义处理请求,以使测试更轻松
  adapter?: AxiosAdapter;
  
  // `auth` 表示应该使用 HTTP 基础验证,并提供凭据
  auth?: AxiosBasicCredentials;
  
  // `responseType` 表示服务器响应的数据类型,可以是 'arraybuffer', 'blob', 'document', 'json', 'text', 'stream'
  responseType?: ResponseType;
  
  // `xsrfCookieName` 是用作 xsrf token 的值的cookie的名称
  xsrfCookieName?: string;
  
  // `xsrfHeaderName` 是携带 xsrf 令牌值的 http 标头的名称
  xsrfHeaderName?: string;
  
  // `onUploadProgress` 允许为上传处理进度事件
  onUploadProgress?: (progressEvent: any) => void;
  
  // `onDownloadProgress` 允许为下载处理进度事件
  onDownloadProgress?: (progressEvent: any) => void;
  
  // `maxContentLength` 定义允许的响应内容的最大尺寸
  maxContentLength?: number;
  
  // `validateStatus` 定义对于给定的HTTP 响应状态码是 resolve 或 reject  promise 。
  // 如果 `validateStatus` 返回 `true` (或者设置为 `null` 或 `undefined`),
  // promise 将被 resolve; 否则,promise 将被 rejecte
  validateStatus?: ((status: number) => boolean) | null;
  
  // 请求体最大尺寸
  maxBodyLength?: number;
  
  // `maxRedirects` 定义在 node.js 中 follow 的最大重定向数目
  // 如果设置为0,将不会 follow 任何重定向
  maxRedirects?: number;
  
  // `socketPath` 定义了一个在 node.js 中使用的 UNIX Socket。
  // 只能指定 `socketPath` 或 `proxy`。
  // 如果两者都指定,则使用 `socketPath`。
  socketPath?: string | null;
  
  // `httpAgent` 和 `httpsAgent` 分别在 node.js 中用于定义在执行 http 和 https 时使用的自定义代理。
  httpAgent?: any;
  httpsAgent?: any;
  
  // 'proxy' 定义代理服务器的主机名称和端口
  proxy?: AxiosProxyConfig | false;
  
  // `cancelToken` 指定用于取消请求的 cancel token
  cancelToken?: CancelToken;
  
  // 将其设置为`false`,它将不会解压缩您的响应,而是保留原始的Content-Encoding头。
  // 默认是true
  decompress?: boolean;
  
  // 控制响应数据是否转换
  transitional?: TransitionalOptions
}
复制代码

AxiosInstance

AxiosInstance是我们使用axios实例对象类型。

我们使用axios.create(config?: AxiosRequestConfig)创建出来的对象都是AxiosInstance类型

export interface AxiosInstance {
  (config: AxiosRequestConfig): AxiosPromise;
  (url: string, config?: AxiosRequestConfig): AxiosPromise;
  defaults: AxiosRequestConfig;
  interceptors: {
    request: AxiosInterceptorManager<AxiosRequestConfig>;
    response: AxiosInterceptorManager<AxiosResponse>;
  };
  getUri(config?: AxiosRequestConfig): string;
  request<T = any, R = AxiosResponse<T>> (config: AxiosRequestConfig): Promise<R>;
  
  // 拥有如下便捷方法
  get<T = any, R = AxiosResponse<T>>(url: string, config?: AxiosRequestConfig): Promise<R>;
  delete<T = any, R = AxiosResponse<T>>(url: string, config?: AxiosRequestConfig): Promise<R>;
  head<T = any, R = AxiosResponse<T>>(url: string, config?: AxiosRequestConfig): Promise<R>;
  options<T = any, R = AxiosResponse<T>>(url: string, config?: AxiosRequestConfig): Promise<R>;
  post<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
  put<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
  patch<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
}
复制代码

可以发现,我们可以使用axios.create、axios.all、axios.spread方法,但是AxiosInstance 上并没有create、all、spread等方法,那我们的axios到底是什么类型呢?

AxiosStatic

export interface AxiosStatic extends AxiosInstance {
  create(config?: AxiosRequestConfig): AxiosInstance;
  Cancel: CancelStatic;
  CancelToken: CancelTokenStatic;
  isCancel(value: any): boolean;
  
  // 并发请求
  all<T>(values: (T | Promise<T>)[]): Promise<T[]>;
  // 切分并发结果
  spread<T, R>(callback: (...args: T[]) => R): (array: T[]) => R;
  isAxiosError(payload: any): payload is AxiosError;
}

declare const axios: AxiosStatic;
复制代码

可以发现,axios其实是AxiosStatic类型,并且继承了AxiosInstance类型。所以是两者的结合。相较axios.create(config?: AxiosRequestConfig)创建出来的实例对象,axios功能是更强大的。

AxiosResponse

AxiosResponse是非常重要的,我们的axios请求返回值类型都是AxiosResponse类型。并且我们可以发现AxiosResponse是一个接口泛型,这个泛型会应用到后端返回的data上。所以这块我们可以根据后端接口返回定义不同的类型传递进去。后面笔者在封装常用方法的时候会细说。

export interface AxiosResponse<T = any>  {
  // 后端接口数据
  data: T;
  // http状态码
  status: number;
  // 来自服务器响应的 HTTP 状态信息
  statusText: string;
  // 响应头
  headers: any;
  // 请求配置信息
  config: AxiosRequestConfig;
  // 请求
  request?: any;
}
复制代码

AxiosError

AxiosError这个类型也是我们必须要知道的。在我们响应拦截器里面的错误就是AxiosError类型。

export interface AxiosError<T = any> extends Error {
  config: AxiosRequestConfig;
  code?: string;
  request?: any;
  response?: AxiosResponse<T>;
  isAxiosError: boolean;
  toJSON: () => object;
}
复制代码

说完了Axios的几个常用类型,接下来我们正式开始使用TS来封装我们的Axios

基础封装

首先我们实现一个最基本的版本,实例代码如下:

// index.ts
import axios from 'axios'
import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'

class Request {
  // axios 实例
  instance: AxiosInstance
  // 基础配置,url和超时时间
  baseConfig: AxiosRequestConfig = {baseURL: "/api", timeout: 60000}

  constructor(config: AxiosRequestConfig) {
    // 使用axios.create创建axios实例,配置为基础配置和我们传递进来的配置
    this.instance = axios.create(Object.assign(this.baseConfig, config))
  }
  
  // 定义请求方法
  public request(config: AxiosRequestConfig): Promise<AxiosResponse> {
    return this.instance.request(config)
  }
}

// 导出Request,可以用来自定义传递配置来创建实例
export const Request

// 默认导出Request实例
export default new Request({})
复制代码

在实际项目中有了基本的请求方法还是远远不够的,我们还需要封装拦截器和一些常用方法。

拦截器封装

拦截器封装只需要在类中对axios.create()创建的实例调用interceptors下的两个拦截器即可,实例代码如下:

// index.ts
constructor(config: AxiosRequestConfig) {
  this.instance = axios.create(Object.assign(this.baseConfig, config))
  
  this.instance.interceptors.request.use(
    (config: AxiosRequestConfig) => {
      // 一般会请求拦截里面加token,用于后端的验证
      const token = localStorage.getItem("token") as string
      if(token) {
        config.headers!.Authorization = token;
      }
      
      return config
    },
    (err: any) => {
      // 请求错误,这里可以用全局提示框进行提示
      return Promise.reject(err)
    },
  )
  
  this.instance.interceptors.response.use(
    (res: AxiosResponse) => {
      // 直接返回res,当然你也可以只返回res.data
      // 系统如果有自定义code也可以在这里处理
      return res
    },
    (err: any) => {
      // 这里用来处理http常见错误,进行全局提示
      let message = "";
      switch (err.response.status) {
        case 400:
          message = "请求错误(400)";
          break;
        case 401:
          message = "未授权,请重新登录(401)";
          // 这里可以做清空storage并跳转到登录页的操作
          break;
        case 403:
          message = "拒绝访问(403)";
          break;
        case 404:
          message = "请求出错(404)";
          break;
        case 408:
          message = "请求超时(408)";
          break;
        case 500:
          message = "服务器错误(500)";
          break;
        case 501:
          message = "服务未实现(501)";
          break;
        case 502:
          message = "网络错误(502)";
          break;
        case 503:
          message = "服务不可用(503)";
          break;
        case 504:
          message = "网络超时(504)";
          break;
        case 505:
          message = "HTTP版本不受支持(505)";
          break;
        default:
          message = `连接出错(${err.response.status})!`;
      }
      // 这里错误消息可以使用全局弹框展示出来
      // 比如element plus 可以使用 ElMessage
      // ElMessage({
      //   showClose: true,
      //   message: `${message},请检查网络或联系管理员!`,
      //   type: "error",
      // });
      // 这里是AxiosError类型,所以一般我们只reject我们需要的响应即可
      return Promise.reject(err.response)
    },
  )
}
复制代码

在这里我们分别对请求拦截器和响应拦截器做了处理。

在请求拦截器我们给请求头添加了token

在响应拦截器,我们返回了整个response对象,当然你也可以只返回后端返回的response.data,这里可以根据个人喜好来处理。其次对http错误进行了全局处理。

常用方法封装

在基础封装的时候我们封装了一个request通用方法,其实我们还可以更具体的封装get、post、put、delete方法,让我们使用更方便。

并且,我们前面分析到,AxiosResponse其实是一个泛型接口,他可以接受一个泛型并应用到我们的data上。所以我们可以在这里再定义一个后端通用返回的数据类型。

比如假设我们某个项目后端接口不管请求成功与失败,返回的结构永远是code、message、results的话我们可以定义一个这样的数据类型。

type Result<T> = {
  code: number,
  message: string,
  result: T
}
复制代码

然后传递个各个方法

public get<T = any>(
  url: string, 
  config?: AxiosRequestConfig
): Promise<AxiosResponse<Result<T>>> {
  return this.instance.get(url, config);
}

public post<T = any>(
  url: string,
  data?: any,
  config?: AxiosRequestConfig
): Promise<AxiosResponse<Result<T>>> {
  return this.instance.post(url, data, config);
}

public put<T = any>(
  url: string,
  data?: any,
  config?: AxiosRequestConfig
): Promise<AxiosResponse<Result<T>>> {
  return this.instance.put(url, data, config);
}

public delete<T = any>(
  url: string,
  config?: AxiosRequestConfig
): Promise<AxiosResponse<Result<T>>> {
  return this.instance.delete(url, config);
}
复制代码

这样当我们调用接口的时候就可以看到我们返回的data的类型啦。就是我们定义的Result类型。

image.png

所以我们可以直接得到自动提示

image.png

上面调用接口的时候并没有传递接口数据类型,所以我们的resultany类型,要想要每个接口都有类型提示,我们还需要给方法传递泛型。

我们再改进下,我们再定义一个login接口返回值类型loginType

type loginType = {
  token: string;
};
复制代码

然后再调用方法的地方传递进去,然后我们再看看返回值data的类型。

image.png

可以看到他是Result<loginType>类型,这个loginType就是result的类型。

所以我们的result还可以进一步的得到提示

image.png

当然每个接口都定义返回值类型固然好,但是会大大加大前端的工作量。我们在写请求方法的时候也可以不传递接口返回值类型,这样result的类型就是any。这个可以根据自身项目需求来选择使用。

看到这小伙伴们是不是都弄懂了呢?如还有疑问欢迎留言。

总结

说了这么多,有些小伙伴们可能有点晕了,下面笔者分享下整个axios的封装。

// index.ts
import axios from "axios";
import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";

type Result<T> = {
  code: number;
  message: string;
  result: T;
};

class Request {
  // axios 实例
  instance: AxiosInstance;
  // 基础配置,url和超时时间
  baseConfig: AxiosRequestConfig = { baseURL: "/api", timeout: 60000 };

  constructor(config: AxiosRequestConfig) {
    // 使用axios.create创建axios实例
    this.instance = axios.create(Object.assign(this.baseConfig, config));

    this.instance.interceptors.request.use(
      (config: AxiosRequestConfig) => {
        // 一般会请求拦截里面加token,用于后端的验证
        const token = localStorage.getItem("token") as string
        if(token) {
          config.headers!.Authorization = token;
        }

        return config;
      },
      (err: any) => {
        // 请求错误,这里可以用全局提示框进行提示
        return Promise.reject(err);
      }
    );

    this.instance.interceptors.response.use(
      (res: AxiosResponse) => {
        // 直接返回res,当然你也可以只返回res.data
        // 系统如果有自定义code也可以在这里处理
        return res;
      },
      (err: any) => {
        // 这里用来处理http常见错误,进行全局提示
        let message = "";
        switch (err.response.status) {
          case 400:
            message = "请求错误(400)";
            break;
          case 401:
            message = "未授权,请重新登录(401)";
            // 这里可以做清空storage并跳转到登录页的操作
            break;
          case 403:
            message = "拒绝访问(403)";
            break;
          case 404:
            message = "请求出错(404)";
            break;
          case 408:
            message = "请求超时(408)";
            break;
          case 500:
            message = "服务器错误(500)";
            break;
          case 501:
            message = "服务未实现(501)";
            break;
          case 502:
            message = "网络错误(502)";
            break;
          case 503:
            message = "服务不可用(503)";
            break;
          case 504:
            message = "网络超时(504)";
            break;
          case 505:
            message = "HTTP版本不受支持(505)";
            break;
          default:
            message = `连接出错(${err.response.status})!`;
        }
        // 这里错误消息可以使用全局弹框展示出来
        // 比如element plus 可以使用 ElMessage
        // ElMessage({
        //   showClose: true,
        //   message: `${message},请检查网络或联系管理员!`,
        //   type: "error",
        // });
        // 这里是AxiosError类型,所以一般我们只reject我们需要的响应即可
        return Promise.reject(err.response);
      }
    );
  }

  // 定义请求方法
  public request(config: AxiosRequestConfig): Promise<AxiosResponse> {
    return this.instance.request(config);
  }

  public get<T = any>(
    url: string,
    config?: AxiosRequestConfig
  ): Promise<AxiosResponse<Result<T>>> {
    return this.instance.get(url, config);
  }

  public post<T = any>(
    url: string,
    data?: any,
    config?: AxiosRequestConfig
  ): Promise<AxiosResponse<Result<T>>> {
    return this.instance.post(url, data, config);
  }

  public put<T = any>(
    url: string,
    data?: any,
    config?: AxiosRequestConfig
  ): Promise<AxiosResponse<Result<T>>> {
    return this.instance.put(url, data, config);
  }

  public delete<T = any>(
    url: string,
    config?: AxiosRequestConfig
  ): Promise<AxiosResponse<Result<T>>> {
    return this.instance.delete(url, config);
  }
}

// 导出Request类,可以用来自定义传递配置来创建实例
export const Request

// 默认导出Request实例
export default new Request({})
复制代码

参考文档

axios 中文文档

系列文章

TypeScript学习之环境搭建

TypeScript学习之数据类型

TypeScript学习之函数

TypeScript学习之接口

TypeScript学习之类

TypeScript学习之类型推断、类型断言、双重断言、非空断言、确定赋值断言、类型守卫、类型别名

TypeScript学习之泛型

TypeScript学习之装饰器

TypeScript学习之模块与命名空间

TypeScript学习之申明文件

TypeScript学习之常用内置工具类型

TypeScript学习之配置文件

后记

感谢小伙伴们的耐心观看,本文为笔者个人学习笔记,如有谬误,还请告知,万分感谢!如果本文对你有所帮助,还请点个关注点个赞~,您的支持是笔者不断更新的动力!

分类:
前端
分类:
前端
收藏成功!
已添加到「」, 点击更改