mirror of
https://github.com/zuiidea/antd-admin
synced 2026-10-30 05:13:43 +00:00
zuiideaandCursor
b8bb7713b3
Document API_PREFIX, folder structure, templates, and E2E script usage in en/zh. Co-authored-by: Cursor <cursoragent@cursor.com>
37 lines
2.0 KiB
Plaintext
37 lines
2.0 KiB
Plaintext
---
|
||
title: 开发代理与 Mock
|
||
description: MSW、API 基地址与对接真实后端
|
||
---
|
||
|
||
# 开发代理与 Mock
|
||
|
||
## MSW（开发默认）
|
||
|
||
模板在开发环境使用 **MSW** 拦截 HTTP，**handlers** 位于 `src/mocks/handlers`。无后端即可演示登录、菜单、用户 CRUD 等。
|
||
|
||
**Worker 目录**由 `package.json` 的 **`msw.workerDirectory`** 配置为 `public`，与 [public 目录](/styles-and-assets/public-folder) 说明一致。
|
||
|
||
## API 层（模板约定）
|
||
|
||
数据流：**Zod schema → `src/api/<module>/index.ts` 中的 `defineApi` → 路由/组件只调用资源函数**（如 `listUsers`、`login`）。页面不要 import axios 或 `@/api/request`。
|
||
|
||
```text
|
||
src/api/
|
||
├── request.ts # axios、响应 envelope、token 刷新
|
||
├── schemas.ts # 兼容 re-export；新代码用 @/api/shared 与各 module schemas
|
||
├── shared/ # API_PREFIX、分页/查询/菜单等共用 schema
|
||
├── auth/ # paths、schemas、登录与 hydrateSession
|
||
└── users/ # schemas、CRUD、userQueryKeys、路径常量
|
||
```
|
||
|
||
- REST 前缀：**`API_PREFIX`**（`src/api/shared/prefix.ts`，默认 `/api`）。`AUTH_ENDPOINTS`、`USERS_PATH` 与 **MSW handlers** 共用同一套常量。
|
||
- 新增资源：对照 **`users`**，见各应用 **`.agents/skills/add-resource/SKILL.md`** 与 **`AGENTS.md`**。
|
||
|
||
## 对接真实 API
|
||
|
||
模板传输层为 **`src/api/request.ts`（axios）**：`baseURL` 来自环境变量 **`VITE_API_BASE_URL`**（见 `src/utils/constants.ts`）。业务调用请走 **`src/api/<module>/index.ts`** 导出的 `defineApi` 函数，不要在页面里直连 axios。
|
||
|
||
将 `VITE_API_BASE_URL` 指向真实网关，并按环境关闭或绕过 MSW 初始化（具体开关以模板 `main.tsx` / 环境变量为准）。
|
||
|
||
跨域时需由**浏览器可访问**的网关配置 **CORS**；或通过开发代理将 **`API_PREFIX`（默认 `/api`）** 转发到后端（在 `vite.config.ts` 配置 `server.proxy`，按团队规范填写目标地址）。
|