干货分享：Vue 3和TypeScript结合进行API封装

'# 干货分享：Vue 3和TypeScript结合进行API封装

一、背景与问题

在大型Vue 3项目中，API调用往往面临以下挑战：

1. 重复代码：每个请求都需要重复编写axios调用逻辑
2. 类型管理困难：后端接口变更时需要手动更新类型定义
3. 错误处理分散：不同组件中错误处理逻辑不一致
4. 状态管理混乱：请求加载/完成/错误状态难以统一管理
5. 接口统一性：不同模块接口格式不统一，增加维护成本

传统做法中，开发者通常直接在组件中调用axios，但这种方式在大型项目中会带来维护成本和类型安全问题。通过结合TypeScript的强类型特性，我们可以构建一个统一的API封装体系，实现以下目标：

• 统一接口格式
• 强类型校验
• 自动错误处理
• 状态管理集成
• 灵活的请求拦截

二、基本原理

Vue 3的组合式API与TypeScript的结合，使得我们可以构建一个基于接口的请求系统。核心原理包括：

1. 接口定义：使用TypeScript接口描述接口的结构
2. 类型守卫：通过类型断言和类型守卫确保数据类型
3. 泛型应用：使用泛型处理不同类型的响应数据
4. 响应拦截器：统一处理错误、加载状态和数据转换
5. 依赖注入：通过provide/inject实现API服务的全局访问

三、环境准备

# 创建Vue 3项目
npm create vue@latest
# 选择TypeScript支持

# 安装依赖
npm install axios

// tsconfig.json 配置
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": ".",
    "types": ["node", "jest"]
  }
}

四、核心实现

1. 接口定义与类型守卫

// src/types/api.ts
interface ApiResponse<T> {
  code: number;
  message: string;
  data: T | null;
  success: boolean;
}

// 类型守卫
function isApiResponse<T>(value: unknown): value is ApiResponse<T> {
  return (
    typeof value === 'object' &&
    value !== null &&
    'code' in value &&
    'message' in value &&
    'data' in value &&
    'success' in value
  );
}

2. 基础API封装

// src/api/base.ts
import axios from 'axios';
import { isApiResponse } from './types';

const api = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
});

// 请求拦截器
api.interceptors.request.use((config) => {
  // 添加请求头
  config.headers['Content-Type'] = 'application/json';
  return config;
});

// 响应拦截器
api.interceptors.response.use(
  (response) => {
    if (isApiResponse(response.data)) {
      // 处理成功响应
      return response.data.data;
    }
    throw new Error('Unexpected response format');
  },
  (error) => {
    // 统一错误处理
    const message = error.response?.data?.message || 'Server error';
    console.error('API Error:', message);
    return Promise.reject(message);
  }
);

export default api;

3. 通用请求方法封装

// src/api/utils.ts
export async function get<T>(url: string): Promise<T> {
  try {
    const response = await api.get<T>(url);
    return response;
  } catch (error) {
    throw new Error(`GET request failed: ${url}`);
  }
}

export async function post<T>(url: string, data: unknown): Promise<T> {
  try {
    const response = await api.post<T>(url, data);
    return response;
  } catch (error) {
    throw new Error(`POST request failed: ${url}`);
  }
}

五、完整案例：用户管理模块封装

1. 接口定义

// src/types/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'user';
  createdAt: Date;
}

export interface UserListResponse extends ApiResponse<User[]> {
  total: number;
}

2. API封装

// src/api/user.ts
import { get, post } from './utils';

export async function fetchUsers(page: number = 1): Promise<User[]> {
  const response = await get<UserListResponse>('/api/users?page=${page}');
  return response;
}

export async function createUser(user: Omit<User, 'id'>): Promise<User> {
  const response = await post<User>('/api/users', user);
  return response;
}

3. 组件使用示例

<!-- src/views/UserList.vue -->
<template>
  <div>
    <table>
      <thead>
        <tr>
          <th>ID</th>
          <th>Name</th>
          <th>Email</th>
          <th>Role</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="user in users" :key="user.id">
          <td>{{ user.id }}</td>
          <td>{{ user.name }}</td>
          <td>{{ user.email }}</td>
          <td>{{ user.role }}</td>
        </tr>
      </tbody>
    </table>
    <button @click="fetchUsers">Refresh</button>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import { fetchUsers } from '../api/user';

export default defineComponent({
  setup() {
    const users = ref<User[]>([]);
    
    const refresh = async () => {
      try {
        users.value = await fetchUsers();
      } catch (error) {
        console.error('Failed to fetch users:', error);
      }
    };
    
    return {
      users,
      refresh,
    };
  },
});
</script>

六、源码解析

1. 响应拦截器机制

api.interceptors.response.use(
  (response) => {
    if (isApiResponse(response.data)) {
      return response.data.data;
    }
    throw new Error('Unexpected response format');
  },
  (error) => {
    const message = error.response?.data?.message || 'Server error';
    console.error('API Error:', message);
    return Promise.reject(message);
  }
);

• 该拦截器会检查响应数据是否符合ApiResponse类型
• 如果符合则返回data字段，否则抛出错误
• 错误处理逻辑统一，避免重复代码

2. 类型守卫的使用

function isApiResponse<T>(value: unknown): value is ApiResponse<T> {
  return (
    typeof value === 'object' &&
    value !== null &&
    'code' in value &&
    'message' in value &&
    'data' in value &&
    'success' in value
  );
}

• 通过检查对象的属性是否存在来判断类型
• 保证类型安全，避免运行时类型错误
• 可以扩展支持更多类型检查

3. 通用请求方法封装

export async function get<T>(url: string): Promise<T> {
  try {
    const response = await api.get<T>(url);
    return response;
  } catch (error) {
    throw new Error(`GET request failed: ${url}`);
  }
}

• 包裹了axios的get方法
• 统一处理错误
• 返回类型明确

七、进阶使用

1. 分页请求优化

export async function fetchUsers(page: number = 1): Promise<User[]> {
  const response = await get<UserListResponse>('/api/users?page=${page}');
  return response;
}

• 参数类型校验
• 自动处理分页参数
• 返回类型明确

2. 重试机制实现

export async function retryRequest<T>(url: string, maxRetries: number = 3): Promise<T> {
  let retries = 0;
  while (retries < maxRetries) {
    try {
      const response = await get<T>(url);
      return response;
    } catch (error) {
      retries++;
      if (retries < maxRetries) {
        await new Promise((resolve) => setTimeout(resolve, 1000 * retries));
      }
    }
  }
  throw new Error('Request failed after multiple retries');
}

3. 缓存机制实现

const cache = new Map<string, any>();

export async function cachedGet<T>(url: string): Promise<T> {
  if (cache.has(url)) {
    return cache.get(url);
  }
  
  const response = await get<T>(url);
  cache.set(url, response);
  return response;
}

八、性能与工程实践

1. 性能优化

2. 安全风险分析

3. 工程实践建议

• 使用provide/inject实现API服务的全局访问
• 将API模块化按业务划分
• 编写单元测试覆盖核心逻辑
• 使用TypeScript的装饰器增强可维护性
• 配置TypeScript的严格模式
• 使用TypeScript的类型断言处理特殊场景

九、常见问题与踩坑

1. 类型不匹配问题

错误示例：

// 错误：未使用类型断言
const data = await get('/api/users');
console.log(data.name);

问题分析：get方法返回的是Promise<any>，无法访问name属性

解决方案：

// 正确使用类型断言
const data = await get<User[]>('/api/users');
console.log(data[0].name);

2. 错误处理不完善

错误示例：

// 错误：未处理网络错误
async function fetchUsers() {
  const response = await get('/api/users');
  return response;
}

问题分析：未处理网络错误导致程序崩溃

解决方案：

// 正确处理错误
async function fetchUsers() {
  try {
    const response = await get('/api/users');
    return response;
  } catch (error) {
    console.error('Failed to fetch users:', error);
    return [];
  }
}

3. 配置错误导致接口失效

错误示例：

// 错误：未配置baseURL
const api = axios.create({
  // 缺少baseURL配置
});

问题分析：接口请求地址不完整，导致404错误

解决方案：

// 正确配置baseURL
const api = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
});

十、最佳实践

1. 接口统一管理

• 所有API封装到统一的/src/api目录
• 按业务模块划分子目录（如/user, /product等）
• 使用index.ts导出所有接口

2. 类型定义规范

• 所有接口定义放在/src/types目录
• 使用/types/api.ts定义通用接口
• 针对不同业务模块创建专属类型文件

3. 错误处理规范

• 所有API调用都使用统一的错误处理逻辑
• 错误信息统一格式，便于日志分析
• 错误处理返回标准化的错误对象

4. 性能优化策略

• 对高频请求添加缓存
• 对低频请求使用节流/防抖
• 对关键请求添加重试机制
• 使用Webpack的代码分割优化加载速度

5. 安全防护措施

• 所有请求都进行CSRF校验
• 敏感接口使用Token认证
• 前端对用户输入进行过滤和转义
• 对特殊字符进行编码处理
• 使用HTTPS确保数据传输安全

十一、总结

通过将Vue 3与TypeScript结合进行API封装，我们可以构建一个类型安全、可维护性强的API系统。这种封装方案具有以下优势：

1. 类型安全：通过TypeScript的强类型校验，避免运行时类型错误
2. 统一管理：集中管理所有API调用，降低维护成本
3. 错误处理：统一处理网络错误和业务错误
4. 可扩展性：通过接口和类型定义，方便后续扩展
5. 可维护性：代码结构清晰，便于团队协作

但需要注意的是，这种方案并不适用于所有场景：

• 不适用场景：

  • 小型项目或快速原型开发
  • 需要快速迭代的临时项目
  • 对性能要求极高的场景
  • 使用简单前端框架的项目

在实际开发中，建议根据项目规模和团队需求选择合适的封装策略。对于大型项目，建议采用分层的API封装体系，结合状态管理、缓存机制和性能优化策略，构建一个健壮的API调用系统。