548df7020c
- Add environment configs for dev/staging/prod environments - Implement centralized axios request utility with standardized error handling - Add shared TypeScript types for API responses and requests - Create comprehensive API client modules for all core endpoints - Configure vue router with all application page routes - Add icon fonts, static assets, and loading animations - Set up project documentation and collaboration guidelines - Remove deprecated uni-app bridge component files
132 lines
2.7 KiB
Markdown
132 lines
2.7 KiB
Markdown
# 统一请求库使用说明
|
||
|
||
统一请求库实现位置：
|
||
|
||
- `src/utils/request.ts`
|
||
- 类型定义：`src/shared/request-types.ts`
|
||
|
||
## 环境变量
|
||
|
||
必须配置：
|
||
|
||
- `VITE_API_BASE_URL`：接口基础地址（例如 `https://api.example.com`）
|
||
|
||
可选配置：
|
||
|
||
- `VITE_API_TIMEOUT_MS`：请求超时毫秒数（默认 15000）
|
||
|
||
## 上下文注入（header 来源）
|
||
|
||
请求库会在请求时自动注入以下 header（有值才注入）：
|
||
|
||
- `Authorization: Bearer <token>`（可通过 `skipAuth: true` 跳过）
|
||
- `clientId`
|
||
- `X-Latitude`
|
||
- `X-Longitude`
|
||
- `language`
|
||
|
||
你需要在业务合适时机写入上下文（内存态）：
|
||
|
||
```ts
|
||
import {
|
||
setAuthToken,
|
||
setClientId,
|
||
setLocation,
|
||
setLanguage,
|
||
} from "@/utils/request";
|
||
|
||
setClientId("your-client-id");
|
||
setAuthToken("token-string");
|
||
setLocation(30.12345, 120.12345);
|
||
setLanguage("zh-CN");
|
||
```
|
||
|
||
说明：
|
||
|
||
- `language` 如果未显式设置，会尝试从 i18n 的 `getCurrentLocale()` 获取
|
||
|
||
## 发起请求
|
||
|
||
### request<T>（兼容旧代码风格，返回 { code, message, data }）
|
||
|
||
```ts
|
||
import { request } from "@/utils/request";
|
||
|
||
const res = await request<{ records: unknown[] }>({
|
||
method: "GET",
|
||
url: "/xxx/list",
|
||
params: { pageNum: 1, pageSize: 10 },
|
||
});
|
||
|
||
console.log(res.data.records);
|
||
```
|
||
|
||
### requestData<T>（推荐新代码风格，只返回 data）
|
||
|
||
```ts
|
||
import { requestData } from "@/utils/request";
|
||
|
||
const data = await requestData<{ records: unknown[] }>({
|
||
method: "GET",
|
||
url: "/xxx/list",
|
||
params: { pageNum: 1, pageSize: 10 },
|
||
});
|
||
|
||
console.log(data.records);
|
||
```
|
||
|
||
### 跳过 Authorization
|
||
|
||
```ts
|
||
import { request } from "@/utils/request";
|
||
|
||
await request<string>(
|
||
{
|
||
method: "GET",
|
||
url: "/public/ping",
|
||
},
|
||
{ skipAuth: true },
|
||
);
|
||
```
|
||
|
||
### 临时追加 headers
|
||
|
||
```ts
|
||
import { request } from "@/utils/request";
|
||
|
||
await request(
|
||
{ method: "POST", url: "/xxx", data: { a: 1 } },
|
||
{ headers: { "X-Debug": "1" } },
|
||
);
|
||
```
|
||
|
||
## 错误处理（只抛错，不做 Toast）
|
||
|
||
请求失败会抛出一个 `RequestError`（符合 `NormalizedError` 结构），可根据 `kind` 分流：
|
||
|
||
- `business`：后端返回 `{ code, message, data }` 且 `code !== 0`
|
||
- `http`：HTTP 状态码错误（如 401/403/500）
|
||
- `network`：断网/超时等（无 response）
|
||
- `unknown`：返回结构不符合预期等其它情况
|
||
|
||
示例：
|
||
|
||
```ts
|
||
import type { NormalizedError } from "@/shared/request-types";
|
||
import { requestData } from "@/utils/request";
|
||
|
||
try {
|
||
await requestData({ method: "GET", url: "/xxx" });
|
||
} catch (e) {
|
||
const err = e as NormalizedError;
|
||
if (err.kind === "business") {
|
||
// err.message / err.code
|
||
} else if (err.kind === "http") {
|
||
// err.httpStatus
|
||
} else if (err.kind === "network") {
|
||
// err.message
|
||
}
|
||
}
|
||
```
|
||
|