经验总结：typescript 和 axios 项目中大量接口该怎样管理和组织

引言

本文旨在先容一种方法，用于在 typescript 和 axios 的项目中，有效的组合和管理大量的 API 接口以及 interface。
假如我们根据 API 文档对全部的接口做了初步分类，大体如下：

1. scm(某业务模块)
2. ├── inventory(库存业务)
3. │    ├── warehouse # 仓库资源
4. │    ├── material  # 物料资源
5. │    ├── unit      # 计量单位资源
6. │    └── ...
7. ├── order(订单业务)
8. │     ├── order    # 订单资源
9. │     ├── customer # 客户资源
10. │     └── ...
11. └── ...

复制代码

具体来说，对于单个但资源后端提供了一系列 CRUD 操作接口， 以warehouse为例：
类型方法&路径列表<GET /api/scm/warehouse/>创建<OST /api/scm/warehouse/>详情<GET /api/scm/warehouse/1/>整体更新<UT /api/scm/warehouse/1/>部分更新<ATCH /api/scm/warehouse/1/>删除<DELETE /api/scm/warehouse/1/> 在项目中，我们会有大量的资源，每种资源又会产生很多接口，对接这些接口我们必要创建很多请求函数，因此怎样管理这些请求函数变得尤为重要。本文将先容一种高效的组织方法，话不多说，让我们开始吧。
一、封装 axios

我们不讨论对axios的深度封装，这里只做最简朴的处理：

1. // utils/request.ts
2. import { useTokenStore } from "@/stores/auth/token";
3. import axios from "axios";
5. // 后端API统一的返回结构
6. export type Result<T> = {
7.   status: string;
8.   code: number;
9.   message: string[];
10.   result: T;
11. };
13. const tokenStore = useTokenStore();
14. const access = tokenStore.getToken.access;
16. // 配置新建一个 axios 实例
17. const instance = axios.create({
18.   baseURL: import.meta.env.VITE_API_URL || "http://localhost:8000",
19.   timeout: 60000,
20. });
22. // 添加请求拦截器
23. instance.interceptors.request.use(
24.   function (config) {
25.     // 添加token
26.     if (access) {
27.       config.headers.Authorization = `Bearer ${access}`;
28.     }
29.     return config;
30.   },
31.   function (error) {
32.     // 对请求错误做些什么
33.     return Promise.reject(error);
34.   }
35. );
37. // 添加响应拦截器
38. instance.interceptors.response.use(
39.   function (response) {
40.     // 2xx 范围内的状态码都会触发该函数。
41.     // 对响应数据做点什么
42.     return response;
43.   },
44.   function (error) {
45.     // 超出 2xx 范围的状态码都会触发该函数。
46.     // 对响应错误做点什么
47.     return Promise.reject(error);
48.   }
49. );
51. export default instance;

复制代码

二、对接接口

在引言中我们先容了全部的资源接口，以及其分类：

1. scm(某业务模块)
2. ├── inventory(库存业务)
3. │    ├── warehouse # 仓库资源
4. │    ├── material  # 物料资源
5. │    ├── unit      # 计量单位资源
6. │    └── ...
7. ├── order(订单业务)
8. │     ├── order    # 订单资源
9. │     ├── customer # 客户资源
10. │     └── ...
11. └── ...

复制代码

根据分类，我们创建下面的目录接口来存放请求函数：

1. /vue-project
2. ├── /src
3. │   └── /api
4. │        ├── ...
5. │        └── /scm
6. │            ├── inventory.ts  （示例所在）
7. │            ├── order.ts
8. │            ├── ...
9. │            └── index.ts

复制代码

以warehouse资源为例，我们要为其全部的资源操作接口创建请求方法、要为其全部接口的请求体和相应体创建interface：

1. // .../scm/inventory.ts
2. import request, { type Result } from "@/utils/request";
4. const baseUrl = "/api/scm";
6. // 仓库接口
7. // ----------------------------------------------------
8. export interface WarehouseBaseIn {
9.   name: string;
10.   code: string;
11. }
13. export interface WarehouseBaseOut {
14.   id: number;
15.   name: string;
16.   code: string;
17.   created_by: number;
18.   created_at: string;
19. }
21. export interface WarehousePatchIn {
22.   name?: string;
23.   code?: string;
24. }
26. export const warehouse = {
27.   list: () =>
28.     // 获取列表
29.     request<Result<WarehouseBaseOut[]>>({
30.       url: baseUrl + "/warehouse/",
31.       method: "GET",
32.     }),
33.   create: (data: WarehouseBaseIn) =>
34.     // 创建
35.     request<Result<WarehouseBaseOut[]>>({
36.       url: baseUrl + "/warehouse/",
37.       method: "POST",
38.       data,
39.     }),
40.   retrieve: (id: string) =>
41.     // 按ID查询
42.     request<Result<WarehouseBaseOut[]>>({
43.       url: baseUrl + `/warehouse/${id}/`,
44.       method: "GET",
45.     }),
46.   put: (id: string, data: WarehouseBaseIn) =>
47.     // 全部更新
48.     request<Result<WarehouseBaseOut[]>>({
49.       url: baseUrl + `/warehouse/${id}/`,
50.       method: "PUT",
51.       data,
52.     }),
53.   patch: (id: string, data: WarehousePatchIn) =>
54.     // 部分更新
55.     request<Result<WarehouseBaseOut[]>>({
56.       url: baseUrl + `/warehouse/${id}/`,
57.       method: "PATCH",
58.       data,
59.     }),
60.   destroy: (id: string) =>
61.     // 删除
62.     request<Result<any>>({
63.       url: baseUrl + `/warehouse/${id}/`,
64.       method: "Delete",
65.     }),
66. };
68. // 除了warehouse之外，inventory文件中实际上还会有更多的接口。
69. // 比如: material、unit等等，封装的方法都是类似的。
70. // ...

复制代码

对单个资源的封装可以总结为如下布局：

1. const source = {
2.     list: function...,
3.     create: function...,
4.     retrieve: function...,
5.     put: function...,
6.     patch: function...,
7.     destroy: function...
8. }

复制代码

回首我们的目录布局：

1. /vue-project
2. ├── /src
3. │   └── /api
4. │        ├── ...
5. │        └── /scm
6. │            ├── inventory.ts   （示例所在）
7. │            ├── order.ts
8. │            ├── ...
9. │            └── index.ts

复制代码

上述的目录布局，使得我们可以对大量的资源举行分类组织，而为了方便请求函数调用，我们还必要在index.ts中对请求函数举行汇总。

1. // .../scm/index.ts
2. import { warehouse, material, unit,... } from './inventory'
3. import { order, customer, ... } from './order'
5. const api = {
6.   inventory: {
7.     warehouse,
8.     material,
9.     unit,
10.     ...
11.   },
12.   order: {
13.     order,
14.     customer,
15.     ...
16.   }
17. }
19. export default api

复制代码

使用方法如下，并且可以或许充分得到 ide 提示：

1. import api from "@/api/scm";
3. // 使用.时ide的提示会很友好
4. api.inventory.warehouse.list();
5. api.inventory.material.list();
6. api.order.customer.list();
7. api.order.order.list();

复制代码

总结

对资源接口做好分类，将请求函数组织在合理的目录布局中，有助于进步代码的可维护性和可扩展性。同时对请求函数举行统一封装和组织，使得对请求的调用更加方便。