TS 封装 Axios

标签：Axios 封装 string TS 泛型 axios 类型 config

前言

Axios 的二次封装是一项基础工作，主要目的就是将一些常用的功能进行封装，简化后续网络请求的发送。

JS 版本的封装大家都已经非常熟悉了，可以信手拈来。但是使用 TypeScript 对 Axios 进行封装，稍微就复杂了些。主要是由于 TS 引入了类型系统，带来了一些类型的束缚。对于 TS 不太熟悉的小伙伴就容易绕晕。

因此本文适合的阅读对象：熟悉 axios 封装，但在 TypeScript 中不知该如何下手。

明确我们的封装目标：能用上TypeScript 带来的好处，类型检查（安全性） 和语法提示（便捷性） 。

本文将从泛型入手，然后了解 Axios 中的部分类型，延续 JS 版本的极简风，教你封装出一个可用的清爽版 Axios。

初始化项目

使用 create-vue 脚手架初始化项目：

1.   npm create vue ts-axios
2.   // 或者
3.   pnpm create vue ts-axios
4.   复制代码

选择添加 TypeScript ：

image-20221015234134695

之后进入项目目录并安装依赖：

1.   npm install
2.   // 或者
3.   pnpm install
4.   复制代码

安装其他依赖

示例会用到一些组件，所以安装下组件库：

1.   pnpm add axios
2.   pnpm add ant-design-vue
3.   复制代码

接口 mock

使用插件 mock 一个登录接口和一个用户信息接口，方便测试请求。

上篇文章《一个登录案例包学会 Pinia》^[2]介绍了在 vite 中 mock 数据的简单用法，本文不再赘述。

安装插件并进行配置：

1.   pnpm add vite-plugin-mock mockjs -D
2.   复制代码

1.   // vite.config.ts
2.    
3.   import vue from '@vitejs/plugin-vue'
4.   import { viteMockServe } from 'vite-plugin-mock'
5.    
6.   export default defineConfig({
7.     plugins: [
8.       vue(),
9.       viteMockServe()
10.     ],
11.    
12.   })
13.   复制代码

建立 mock 文件，一个登录接口返回 token，一个用户信息接口返回用户名等信息，还有一个模拟出现业务错误的接口。

1.   // mock/user.ts
2.    
3.    
4.   export default [
5.     // 用户登录
6.     {
7.       url: "/api/user/login",
8.       method: "post",
9.       response: (res) => {
10.         return {
11.           code: 0,
12.           message: 'success',
13.           data: {
14.             token: "Token"
15.           }
16.         }
17.       }
18.     },
19.     // 获取用户信息
20.     {
21.       url: "/api/user/info",
22.       method: "get",
23.       response: (res) => {
24.         return {
25.           code: 0,
26.           message: 'success',
27.           data: {
28.             id: "2467751560226270",
29.             username: "昆吾kw",
30.             avatar: "https://p3-passport.byteimg.com/img/user-avatar/3745b7eb198f2357155cd88eb7930f35~180x180.awebp",
31.             description: "前端开发",
32.           }
33.         }
34.       }
35.     },
36.    
37.     // 一个失败的请求
38.     {
39.       url: "/api/error",
40.       method: "get",
41.       response: (res) => {
42.         return {
43.           code: 1,
44.           message: '密码错误',
45.           data: null
46.         }
47.       }
48.     }
49.   ]
50.   复制代码

泛型

泛型的英文是Generic，意思是“通用的”，“一般的“。

在程序设计，泛型中可以理解为 “泛指的类型”，不确定的类型，或者通用的类型。

理解泛型

泛型的概念很像函数中的参数。为了更方便的理解什么是泛型，可以用函数参数做一个类比。

函数在定义时，我们并不知道参数的值到底是多少。只有当函数调用时，才能确定。

1.   function print(a) {
2.       console.log(a)
3.   }
4.    
5.   print('hello')
6.   print('world')
7.   复制代码

泛型的含义也是如此。只不过，参数不确定的是值，泛型不确定的是类型。

泛型的使用场景有很多种，比如泛型函数，泛型类，泛型接口。我们只看泛型函数。

如何定义泛型函数呢？如下：

1.   function add<T>(a:T, b:T): T {
2.       return a + b
3.   }
4.   复制代码

这段代码定义了一个 add 函数，在函数名后来使用了一对尖括号来声明泛型，使用 T（Type 的缩写）来表示一个泛型。之后参数的类型，就不再具体指定是 string 还是 number ，亦或是其他具体的类型，而是用 T 表示。函数的返回值类型同样使用 T 表示。

这样就声明了一个泛型函数。

接着就是泛型函数的调用：

1.   add<number>(1, 2)
2.    
3.   add<string>('a', 'b')
4.   复制代码

和普通函数的调用一样，只不过在函数名后面再次使用一对尖括号，来传递了具体的类型。

通过和参数的类比，详细大家能体会到泛型的含义了。所谓泛型，就是在定义时不确定，而在使用时确定的一种类型。泛型的好处就是提高了代码的复用性，减少了代码的冗余。

有了对泛型的初步认识后，下面就可以去进入正题，去看看 TypeScript 如何封装 Axios 了。

本文的思路

我们不再按照创建实例、配置参数、设置拦截器、封装公共请求方法、封装 API 的顺序去实现封装代码。而是打破常规，从类型入手。

Axios 中的重要类型

查看第三方库的类型声明

Axios 提供了完备的类型声明。声明文件可以直接去看 node_modules/axios/index.d.ts 这个文件：

image-20221015222400669

也可以在编辑器中，按 ctrl，同时鼠标点击 axios 模块跳转过去：

image-20221015222331509image-20221015222440898

要封装好 axios，需要先明白这几个类型是干啥用的。

从一个请求方法入手，看常用的类型

TypeScript 中 class 不仅是类，还可以是类类型。作为前者，它是一个值。作为后者，它是一个类型。

下面的 Axios 就是一个类类型，它声明了一些成员的类型。我们看其中的核心请求方法，request，get ，post ：

1.   export class Axios {
2.     // ......
3.     request<T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
4.       
5.     get<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
6.       
7.     post<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
8.     
9.     // ......
10.   }
11.   复制代码

熟悉 axios 的朋友都知道，axios.get，axios.post 这些方法其实是对 axios.request 的一层封装。所以我们就看 request 方法的声明。

request 方法有三个泛型，T ，R 和 D，接收一个 AxiosRequestConfig 类型的参数作为配置对象，返回值的类型是一个接收泛型R 的 Promise 类型。

1.   request<T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
2.   复制代码

这三个泛型，T 的含义是什么？要去看 R。R 的含义是什么？要去看它的默认类型 AxiosResponse ：

1.   export interface AxiosResponse<T = any, D = any> {
2.    data: T;
3.    status: number;
4.    statusText: string;
5.    headers: RawAxiosResponseHeaders | AxiosResponseHeaders;
6.    config: AxiosRequestConfig<D>;
7.    request?: any;
8.   }
9.   复制代码

看到这个结构，我们知道了，原来 AxiosResponse 就是在设置响应拦截器中用到的那个 response 对象的类型。

同时也就知道了泛型 T 就是服务器返回的数据的类型。因为服务器究竟返回什么类型，代码是不知道的，所以它的默认类型是 any。

回到头来再来看 request 方法的定义，现在就能明白了，它接收的第一个泛型 T 就是将来服务器返回数据的类型，R 就是这个数据经过 axios 包装一层得到的 response 对象的类型，而 request 方法的返回值是一个 Promise，其值就是成功态的 R，也就是 response对象。

第三个泛型 D，这里就不再说了。你可以用同样的方法，找出它又是谁的类型，然后发在评论区。

AxiosRequestConfig 类型

先看下它的类型声明：

1.   export interface AxiosRequestConfig<D = any> {
2.     url?: string;
3.     method?: Method | string;
4.     baseURL?: string;
5.     headers?: RawAxiosRequestHeaders;
6.     // .....
7.   }
8.   复制代码

相信大家能看出来，它其实就是 axios 的配置对象的类型。在设置请求拦截器和封装公共请求方法时会用到。

AxiosInstance

该类型为 axios.create 方法创建出的实例的类型。后面直接用到。

AxiosError

该类型为请求发送过程中出现错误产生的错误对象的类型：

1.   export class AxiosError<T = unknown, D = any> extends Error {
2.     constructor(
3.         message?: string,
4.         code?: string,
5.         config?: AxiosRequestConfig<D>,
6.         request?: any,
7.         response?: AxiosResponse<T, D>
8.     );
9.    
10.     config?: AxiosRequestConfig<D>;
11.     code?: string;
12.     request?: any;
13.     response?: AxiosResponse<T, D>;
14.     isAxiosError: boolean;
15.     status?: number;
16.     toJSON: () => object;
17.     cause?: Error;
18.     // ......
19.   }
20.   复制代码

我们会用到其中的 response 属性，它表示响应对象，需要根据它的 HTTP 状态码做一些处理。

知道了上面这几个类型，接下来就可以着手封装 Axios 了。

开始封装

先提前打个预防针，因为封装的很简单，没有用到类，没有过多的处理业务逻辑。估计看完后你会感觉索然无味。

毕竟我们最初的目的就是用上 TypeScript 的类型能力：类型检查和代码提示。

而且我相信，太复杂的封装，可能会阻碍对类型系统的学习，反而得不偿失。

新建一个 src/utils/request.ts 文件，在这个文件中对 Axios 进行封装。

Result 类型

从服务器返回的数据的类型通常长这样子：

1.   {
2.      code: 0,
3.      message: 'ok',
4.      data: {} 
5.   }
6.   复制代码

定义一个接口 Result 来表示它，其中 data 的类型不确定，所以就要用到泛型了：

1.   /* 服务器返回数据的的类型，根据接口文档确定 */
2.   export interface Result<T=any> {
3.     code: number,
4.     message: string,
5.     data: T
6.   }
7.   复制代码

这是一个泛型接口。和泛型函数差不多，在定义时声明一个泛型，用这个泛型去规范成员的类型。将来使用该接口的时候，再去确定泛型的具体类型。

接下来就可以写代码了。

创建实例

这个大家都非常熟悉了，不再赘述。

1.   import axios from 'axios'
2.   import type { AxiosInstance } from 'axios'
3.    
4.   const service: AxiosInstance = axios.create({
5.     baseURL: '/api',
6.     timeout: 30000
7.   })
8.   复制代码

请求拦截器

这个大家也很熟悉，主要在这里处理请求发送前的一些工作，比如给 HTTP Header 添加 token ，开启 Loading 效果，设置取消请求等。

1.   import type { AxiosError, AxiosRequestConfig } from 'axios'
2.   import { message as Message } from 'ant-design-vue'
3.    
4.   /* 请求拦截器 */
5.   service.interceptors.request.use((config: AxiosRequestConfig) => {
6.     //  伪代码
7.     // if (token) {
8.     //   config.headers.Authorization = `Bearer ${token}`;
9.     // }
10.     return config
11.   }, (error: AxiosError) => {
12.     Message.error(error.message);
13.     return Promise.reject(error)
14.   })
15.   复制代码

响应拦截器

响应拦截器大家也很熟悉了。简单说一下做了哪些事情：

• 根据自定义错误码判断请求是否成功，然后只将组件会用到的数据，也就是上面的 Result 中的 data 返回

• 如果错误码判断请求失败，此时为业务错误，比如用户名不存在等，在这里进行提示

• 如果网络错误，则进入第二个回调函数中，根据不同的状态码设置不同的提示消息进行提示

1.   import type { AxiosError, AxiosResponse } from 'axios'
2.   import { message as Message } from 'ant-design-vue'
3.    
4.   /* 响应拦截器 */
5.   service.interceptors.response.use((response: AxiosResponse) => {
6.     const { code, message, data } = response.data
7.    
8.     // 根据自定义错误码判断请求是否成功
9.     if (code === 0) {
10.       // 将组件用的数据返回
11.       return data
12.     } else {
13.       // 处理业务错误。
14.       Message.error(message)
15.       return Promise.reject(new Error(message))
16.     }
17.   }, (error: AxiosError) => {
18.     // 处理 HTTP 网络错误
19.     let message = ''
20.     // HTTP 状态码
21.     const status = error.response?.status
22.     switch (status) {
23.       case 401:
24.         message = 'token 失效，请重新登录'
25.         // 这里可以触发退出的 action
26.         break;
27.       case 403:
28.         message = '拒绝访问'
29.         break;
30.       case 404:
31.         message = '请求地址错误'
32.         break;
33.       case 500:
34.         message = '服务器故障'
35.         break;
36.       default:
37.         message = '网络连接故障'
38.     }
39.     
40.     Message.error(message) 
41.     return Promise.reject(error)
42.   })
43.   复制代码

公共请求方法

这里是本文的重点，也是 TS 封装 Axios 的重点。使用 TS 无非要获得良好的代码提示，我们在调用接口时编辑器能提示出该接口的返回值有哪些。

1.   /* 导出封装的请求方法 */
2.   export const http = {
3.     get<T=any>(url: string, config?: AxiosRequestConfig) : Promise<T> {
4.       return service.get(url, config)
5.     },
6.    
7.     post<T=any>(url: string, data?: object, config?: AxiosRequestConfig) :Promise<T> {
8.       return service.post(url, data, config)
9.     },
10.    
11.     put<T=any>(url: string, data?: object, config?: AxiosRequestConfig) :Promise<T> {
12.       return service.put(url, data, config)
13.     },
14.    
15.     delete<T=any>(url: string, config?: AxiosRequestConfig) : Promise<T> {
16.       return service.delete(url, config)
17.     }
18.   }
19.   复制代码

我们以 get 方法为例，看下为什么这么封装？

1.   get<T>(url: string, config?: AxiosRequestConfig) : Promise<T> {
2.       return service.get(url, config)
3.   }
4.   复制代码

上文说过，axios 的 requet，get 这些方法，返回的都是一个 AxiosResponse 类型的数据。

默认的响应拦截器返回的是完整的 response 对象，类型为 AxiosResponse 。

经过我们的修改，现在响应拦截器只返回 response.data.data，对应的类型就是 AxiosResponse<Result> 中的 T。所以这里的 service.get 方法，其实际返回类型应为 T，但是编辑器并不知道，它仍然认为它返回的是：

image-20221016134207024

所以我们要手动帮助编辑器“修正”类型提示，也就是不依靠 TS 的类型推导，而是主动设置返回类型为 Promise ：

1.   get<T>(url: string, config?: AxiosRequestConfig) : Promise<T> {
2.       return service.get(url, config)
3.   }
4.   复制代码

这样编辑器就准确识别类型了：

image-20221016134438155

这里的泛型 T 表示的服务器返回数据的类型，具体返回什么类型，要到接口调用时才知道。所以下面来到 API 层，去封装请求接口。

为什么要封装公共请求方法

之所以封装这一层公共请求方法，主要目的就是为了帮编译器正确识别类型。方法就是手动设置返回类型。如果直接使用 axios 实例的请求方法，就需要在每次调用时都指定一遍，当接口有几十上百个时，多少会在增加一些工作量。所以就在这里多加一层，提前将类型制定好。

API 层

准备两个文件，一个写类型，一个写接口。

image-20221016135035587

在 api/user/types.ts 文件中，写接口需要的参数的类型，和接口返回数据的类型。这里的类型，要根据接口文档而定。

1.   /* 登录接口参数类型 */
2.   export interface LoginData {
3.     username: string,
4.     password: string,
5.   }
6.    
7.   /* 登录接口返回值类型 */
8.   export interface LoginRes {
9.     token: string
10.   }
11.    
12.   /* 用户信息接口返回值类型 */
13.   export interface UserInfoRes {
14.     id: string,
15.     username: string,
16.     avatar: string,
17.     description: string,
18.   }
19.   复制代码

在 api/user/index.ts 文件中，封装组件用到的接口。

1.   import request, { http } from '@/utils/request'
2.    
3.   import type { LoginData, LoginRes, UserInfoRes} from './types'
4.    
5.   /**
6.    * 登录
7.    */
8.   export function login(data: LoginData) {
9.     return http.post<LoginRes>('/user/login', data);
10.   }
11.    
12.   /**
13.    * 获取登录用户信息
14.    */
15.   export function getUserInfo() {
16.     return http.get<UserInfoRes>('/user/info')
17.   }
18.   复制代码

以 login 方法为例进行说明。它接收 LoginData 类型的参数作为请求参数。在调用接口时，通过泛型指定了该接口的返回值类型：

image-20221016135528697

测试

Axios 代码提示测试

App.vue 组件中有一个登录表单，在这里测试登录接口是否正常。

方法login 可以推导出当前返回值的类型：

image-20221016002008786

返回值 res 的类型也能推导出：

image-20221016002133845

也可以正确使用类型提示：

image-20221016002233899

然后再测试下调用请求用户信息的接口：

image-20221016002441196

如我们所愿，现在 Axios 经过 TypeScript 的封装，可以给出友好的类型提示，这对于开发体验和效率都有很好的提升。

响应拦截器提示测试

测试业务处理错误的请求，假设此次请求用户密码输入错误：

image-20221016132121313

关闭开发服务，测试无网络连接下的请求发送：

image-20221016132156024

小结

本文示例代码已上传到仓库^[3]。

开始只是想说说 TypeScript 封装 Axios 的一个简单实现版本。但没想到最后说了不老少内容，包括：

• TypeScript 泛型的概念

• 第三方库如何看类型声明

• 如何利用类型封装 Axios

 https://blog.csdn.net/lunahaijiao/article/details/128246274

 

 

 

标签：Axios,封装,string,TS,泛型,axios,类型,config
From： https://www.cnblogs.com/yinhao-jack/p/17081383.html