03-api-integration

API集成规范

🌐 API客户端配置

1. 统一API客户端

参考: src/api/client.ts

// ✅ 推荐: 创建统一的API客户端
const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8080/api/v1';

export const apiClient = {
  get: async <T>(url: string, config?: RequestInit): Promise<T> => {
    const response = await fetch(`${API_BASE_URL}${url}`, {
      ...config,
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        ...getAuthHeaders(),
        ...config?.headers,
      },
    });
    
    return handleResponse<T>(response);
  },
  
  post: async <T>(url: string, data?: unknown, config?: RequestInit): Promise<T> => {
    const response = await fetch(`${API_BASE_URL}${url}`, {
      ...config,
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...getAuthHeaders(),
        ...config?.headers,
      },
      body: JSON.stringify(data),
    });
    
    return handleResponse<T>(response);
  },
  
  // PUT, DELETE等方法...
};

// 获取认证头
const getAuthHeaders = (): Record<string, string> => {
  const token = localStorage.getItem('token');
  return token ? { Authorization: `Bearer ${token}` } : {};
};

// 统一响应处理
const handleResponse = async <T>(response: Response): Promise<T> => {
  if (!response.ok) {
    const error = await response.json().catch(() => ({ message: 'Network error' }));
    throw new ApiError(error.message, response.status);
  }
  
  const data = await response.json();
  return data.data as T;
};

2. 自定义错误类

export class ApiError extends Error {
  constructor(
    message: string,
    public status: number,
    public code?: string
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

📦 API类型定义

1. 请求和响应类型

// 用户相关类型
export interface User {
  id: string;
  username: string;
  email: string;
  avatar?: string;
  role: 'admin' | 'user' | 'guest';
  created_at: string;
  updated_at: string;
}

export interface LoginRequest {
  username: string;
  password: string;
}

export interface LoginResponse {
  token: string;
  refresh_token: string;
  user: User;
}

// API响应包装类型
export interface ApiResponse<T> {
  code: number;
  message: string;
  data?: T;
  errors?: ValidationError[];
}

export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  size: number;
}