62 lines
1.9 KiB
Plaintext
62 lines
1.9 KiB
Plaintext
---
|
||
alwaysApply: false
|
||
---
|
||
# portal-ui API调用规范
|
||
|
||
## 1. 接口路径要求
|
||
- 所有调用 **portal-ui** 的接口必须使用 `/api` 开头（与后端 Java Controller 中的 `@RequestMapping("/api/...")` 对应）。
|
||
- 示例：
|
||
```ts
|
||
// 正确
|
||
const res = await api.get('/api/assets/list', { params })
|
||
|
||
// 错误（不要省略 /api）
|
||
const res = await api.get('/assets/list', { params })
|
||
```
|
||
|
||
## 2. API封装规范
|
||
- 统一使用项目中已封装的 `api` 实例（通常位于 `src/api/index.ts` 或 `src/utils/request.ts`）。
|
||
- 不要直接使用 `axios` 创建新实例。
|
||
- 请求方法统一使用：
|
||
- `GET`、`POST`、`PUT`、`DELETE`
|
||
- 复杂查询优先使用 `POST` + 请求体。
|
||
|
||
## 3. 类型定义要求
|
||
- 所有请求和响应必须定义 **TypeScript 接口**（放在 `src/types/` 或对应模块的 `types.ts` 中）。
|
||
- 命名规范：
|
||
- 请求：`ListAssetsParams`、`CreateAssetRequest`
|
||
- 响应：`ListAssetsResponse`、`ApiResponse<T>`
|
||
- 示例：
|
||
```ts
|
||
export interface ListAssetsParams {
|
||
isTop?: 'Y' | 'N'
|
||
beginTime?: string
|
||
endTime?: string
|
||
pageNum?: number
|
||
pageSize?: number
|
||
}
|
||
|
||
export interface ListAssetsResponse {
|
||
code: number
|
||
data: {
|
||
list: AssetItem[]
|
||
total: number
|
||
}
|
||
message: string
|
||
}
|
||
```
|
||
|
||
## 4. 错误处理规范
|
||
- 使用统一的错误处理拦截器（项目已有全局拦截）。
|
||
- 业务错误统一抛出或使用 `ElMessage.error()` / `a-message`。
|
||
- 网络错误、超时、401/403 等状态码必须有清晰的用户提示。
|
||
- 重要操作（删除、收藏等）必须添加二次确认。
|
||
|
||
## 5. 其他最佳实践
|
||
- 使用 `async/await`，避免 `.then().catch()` 链式调用。
|
||
- Loading 状态统一使用 `loading` 变量 + Ant Design `a-spin`。
|
||
- 分页相关参数统一使用 `pageNum` / `pageSize`。
|
||
- 所有API调用必须添加中文注释说明用途。
|
||
|
||
**所有前端与后端交互的代码必须严格遵守以上规则。**
|