158 lines
5.4 KiB
Markdown
158 lines
5.4 KiB
Markdown
# 9.13 API 模块编写规范
|
||
|
||
:::tip 概述
|
||
本节定义前端 API 模块的编写规范，包括命名规范、请求方式和文件组织。
|
||
:::
|
||
|
||
## 命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 文件名 | 小驼峰，与后端模块对应 | `example.ts` |
|
||
| 查询函数 | `get{Module}Page` / `get{Module}List` / `get{Module}Detail` | `getExamplePage` |
|
||
| 新增函数 | `{module}Add` | `exampleAdd` |
|
||
| 修改函数 | `{module}Update` | `exampleUpdate` |
|
||
| 删除函数 | `{module}Delete` / `{module}BatchDelete` | `exampleDelete` |
|
||
| 导入函数 | `{module}Import` | `exampleImport` |
|
||
| 导出函数 | `{module}Export` | `exampleExport` |
|
||
|
||
## 请求方式
|
||
|
||
| 操作 | HTTP 方法 | 参数传递 | 说明 |
|
||
|------|----------|----------|------|
|
||
| 查询 | GET | `params`（URL 参数） | 分页/列表/详情 |
|
||
| 新增 | POST | `data`（请求体） | JSON 格式 |
|
||
| 修改 | PUT | `data`（请求体） | JSON 格式，含 id |
|
||
| 删除 | DELETE | URL 参数 | 单条（id 在路径中） |
|
||
| 批量删除 | **DELETE** | `data`（请求体 `{ids:[]}`） | 本项目统一 DELETE + body |
|
||
|
||
:::warning 与常见 REST 风格的差异
|
||
本项目 `batchDelete` 为 **DELETE**（请求体仍传 `ids` 数组——DELETE 方法携带 body）；`resetPwd` 为 **PUT**，`account` 等扩展操作为 POST——以后端 `routes/api.php` 实际路由为准（见 [8.7 API 接口总览](/zh/api-spec/overview.html)）。
|
||
:::
|
||
|
||
## 文件组织
|
||
|
||
```text
|
||
ui/src/api/
|
||
├── common/index.ts # 公共接口（字典、验证码、菜单等）
|
||
├── index.ts # 全局接口（登录、登出、刷新Token）
|
||
├── system/ # 系统管理模块
|
||
│ ├── user.ts
|
||
│ ├── role.ts
|
||
│ ├── menu.ts
|
||
│ ├── dept.ts
|
||
│ ├── position.ts
|
||
│ └── level.ts
|
||
├── content/ # 内容管理模块
|
||
│ ├── article.ts
|
||
│ ├── category.ts
|
||
│ └── link.ts
|
||
├── data/ # 数据管理模块（字典/配置/参数/公告/城市）
|
||
├── monitor/ # 监控模块（定时任务）
|
||
├── file/ # 文件模板
|
||
└── tool/ # 工具模块
|
||
└── example.ts
|
||
```
|
||
|
||
## 标准模板
|
||
|
||
```typescript
|
||
// ui/src/api/tool/example.ts
|
||
import { http } from '@/utils/http/axios';
|
||
|
||
// 分页查询
|
||
export function getExamplePage(params?) {
|
||
return http.request({ url: '/example/page', method: 'GET', params });
|
||
}
|
||
|
||
// 全量列表
|
||
export function getExampleList(params?) {
|
||
return http.request({ url: '/example/list', method: 'GET', params });
|
||
}
|
||
|
||
// 详情
|
||
export function getExampleDetail(id) {
|
||
return http.request({ url: '/example/detail/' + id, method: 'GET' });
|
||
}
|
||
|
||
// 新增
|
||
export function exampleAdd(data: any) {
|
||
return http.request({ url: '/example/add', method: 'POST', data });
|
||
}
|
||
|
||
// 修改
|
||
export function exampleUpdate(data: any) {
|
||
return http.request({ url: '/example/update', method: 'PUT', data });
|
||
}
|
||
|
||
// 删除
|
||
export function exampleDelete(id) {
|
||
return http.request({ url: '/example/delete/' + id, method: 'DELETE' });
|
||
}
|
||
|
||
// 批量删除（DELETE + 请求体 { ids: [...] }）
|
||
export function exampleBatchDelete(data: any) {
|
||
return http.request({ url: '/example/batchDelete', method: 'DELETE', data });
|
||
}
|
||
```
|
||
|
||
:::tip 拦截器已解包
|
||
`http.request` 的响应拦截器在 `code === 0` 时直接返回 `data`——函数返回值即业务数据（如分页返回 `{records,total,current,size,pages}`），无需再取 `response.data.data`。
|
||
:::
|
||
|
||
## 常见扩展操作
|
||
|
||
| 操作 | 函数名示例 | HTTP 方法 |
|
||
|------|-----------|----------|
|
||
| 重置密码 | `userResetPwd(data)` | POST |
|
||
| 导入 | `{module}Import(data: FormData)` | POST（multipart/form-data，带 Bearer 头） |
|
||
| 导出 | `{module}Export(params)` | GET |
|
||
| 刷新字典缓存 | `dictRefreshCache()` | GET |
|
||
| 获取用户信息 | `getUser()` | GET |
|
||
| 获取菜单 | `getMenus()` | GET |
|
||
| 修改密码 | `updatePassword(data)` | PUT |
|
||
| 获取字典项 | `getDictItemByCode(code)` | GET |
|
||
| 刷新 Token | `postRefresh({ refresh_token })` | POST（公开接口） |
|
||
|
||
## 组件中使用
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
|
||
import { ElMessage, ElMessageBox } from 'element-plus';
|
||
|
||
const tableData = ref([]);
|
||
|
||
// 查询（res 即 data：{records, total, current, size, pages}）
|
||
const fetchData = async () => {
|
||
const res = await getExamplePage({ pageNo: 1, pageSize: 20 });
|
||
tableData.value = res.records;
|
||
};
|
||
|
||
// 删除
|
||
const handleDelete = async (id) => {
|
||
await ElMessageBox.confirm('确认删除？', '提示', { type: 'warning' });
|
||
await exampleDelete(id);
|
||
ElMessage.success('删除成功');
|
||
fetchData();
|
||
};
|
||
|
||
// 批量删除
|
||
const handleBatchDelete = async (ids) => {
|
||
await exampleBatchDelete({ ids });
|
||
ElMessage.success('删除成功');
|
||
fetchData();
|
||
};
|
||
</script>
|
||
```
|
||
|
||
## 编写检查清单
|
||
|
||
| 检查项 | 说明 |
|
||
|------|------|
|
||
| URL 与后端路由一致 | 逐字符核对 `routes/api.php`（二级路径模块名如 `file/template`） |
|
||
| HTTP 方法正确 | 特别注意 `batchDelete`=DELETE（带 body）、`runOnce/pause/resume`=GET |
|
||
| 认证接口不需要带公开标记 | 拦截器自动加 Bearer 头，公开接口同样可用 |
|
||
| 导入用 FormData | `Content-Type` 交给浏览器自动带 boundary，勿手写 |
|
||
| 导出处理返回值 | 后端返回文件地址（字符串），直接打开下载 |
|