api-service.ts — API 服务

文件: web/src/services/api-service.ts

职责

基于 axios 的统一 HTTP 请求封装，提供全应用统一的 API 调用入口。所有数据请求（Store → API）都通过此服务，不直接操作 localStorage。

导出的 API

export const api = {
  get<T = unknown>(url: string, params?: Record<string, unknown>): Promise<T>,
  post<T = unknown>(url: string, data?: Record<string, unknown>): Promise<T>,
  put<T = unknown>(url: string, data?: Record<string, unknown>): Promise<T>,
  delete<T = unknown>(url: string): Promise<T>,
}

方法	参数	返回值	说明
get<T>(url, params?)	url: 请求路径; params?: 查询参数对象	Promise<T>	GET 请求，params 自动序列化为 query string
post<T>(url, data?)	url: 请求路径; data?: 请求体对象	Promise<T>	POST 请求，data 作为 JSON body
put<T>(url, data?)	url: 请求路径; data?: 请求体对象	Promise<T>	PUT 请求
delete<T>(url)	url: 请求路径	Promise<T>	DELETE 请求

配置说明

baseURL

const baseURL = import.meta.env.VITE_API_BASE_URL || "/api/v1";

• 优先使用环境变量 VITE_API_BASE_URL
• 未配置时默认 /api/v1
• 切换后端只需修改此环境变量

实例配置

配置项	值	说明
baseURL	VITE_API_BASE_URL || "/api/v1"	API 基础路径
timeout	10000 (10s)	请求超时时间
headers.Content-Type	application/json	默认请求头

响应拦截器

拦截器自动解包后端统一响应格式 { code, msg, data }：

• code === 0：返回 data 字段，调用方直接拿到业务数据
• code !== 0：Promise.reject(new Error(msg || "请求失败"))，调用方通过 try/catch 捕获
• 网络错误：Promise.reject(error)，同时 console.error 输出错误信息

Mock API 拦截

所有环境（开发/生产）均启用 Mock API。在 web/src/mock/ 中通过 mockjs 拦截 axios 请求，模拟 39 个 RESTful 接口。Mock 数据持久化到 localStorage（tzxq_mock_db），页面关闭时自动保存。

使用示例

import api from "@/services/api-service";

// GET 请求
const userData = await api.get<UserData>("/users/me");
const chars = await api.get<{ list: Character[] }>("/characters", { pageSize: 500 });

// POST 请求
await api.post("/users/settings", { theme: "dark" });

// PUT 请求
await api.put("/users/me", { nickname: "小明" });

// DELETE 请求
await api.delete("/users/records/123");

// 错误处理
try {
  const data = await api.get("/users/me");
} catch (err) {
  console.error("请求失败:", err.message);
}