签入版本
This commit is contained in:
小蚂蚁云
@@ -1,125 +1,111 @@
|
||||
# 9.13 API 模块编写规范
|
||||
# 9.14 API 模块编写规范
|
||||
|
||||
:::tip 概述
|
||||
本节定义前端 API 模块的编写规范，包括命名规范、请求方式和文件组织。
|
||||
api 模块是前端与后端契约的镜像：按业务域分组、一模块一文件、函数对应后端动作。命名与写法以 `ui/src/api/tool/example.ts` 为参考实现。
|
||||
:::
|
||||
|
||||
## 命名规范
|
||||
|
||||
| 类型 | 规范 | 示例 |
|
||||
|------|------|------|
|
||||
| 文件名 | 小驼峰，与后端模块对应 | `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 参数或 `data` | 单条用 URL，批量用 data |
|
||||
|
||||
## 文件组织
|
||||
|
||||
```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
|
||||
└── tool/ # 工具模块
|
||||
└── example.ts
|
||||
ui/src/api/{域}/{模块}.ts
|
||||
```
|
||||
|
||||
## 标准模板
|
||||
域与 views 一一对应（system/content/data/monitor/tool/file/setting...）。公共聚合接口放 common/。
|
||||
|
||||
## 命名约定（以 example 为参照）
|
||||
|
||||
| 动作 | 命名模式 | example 实际函数 |
|
||||
|---|---|---|
|
||||
| 分页 | get{模块}Page | getExamplePage |
|
||||
| 列表 | get{模块}List | getExampleList |
|
||||
| 详情 | get{模块}Detail | getExampleDetail |
|
||||
| 新增 | {模块}Add | exampleAdd |
|
||||
| 修改 | {模块}Update | exampleUpdate |
|
||||
| 删除 | {模块}Delete | exampleDelete |
|
||||
| 批量删除 | {模块}BatchDelete | exampleBatchDelete |
|
||||
| 导入/导出 | {模块}Import / {模块}Export | exampleImport / exampleExport |
|
||||
|
||||
查询类以 `get` 开头，命令类直接以模块名开头。
|
||||
|
||||
## 标准写法（摘自 ui/src/api/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 });
|
||||
/**
|
||||
* 获取案例演示分页列表
|
||||
*
|
||||
* @param params 查询参数，包含 pageNo、pageSize 及业务筛选条件
|
||||
* @returns 分页结果，含 records、total、size、current、pages
|
||||
*/
|
||||
export function getExamplePage(params?: Record<string, any>) {
|
||||
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' });
|
||||
}
|
||||
|
||||
// 新增
|
||||
/**
|
||||
* 添加案例演示
|
||||
*
|
||||
* @param data 案例演示数据
|
||||
* @returns 新记录的 ID
|
||||
*/
|
||||
export function exampleAdd(data: any) {
|
||||
return http.request({ url: '/example/add', method: 'POST', data });
|
||||
return http.request({
|
||||
url: '/example/add',
|
||||
method: 'POST',
|
||||
data,
|
||||
});
|
||||
}
|
||||
|
||||
// 修改
|
||||
export function exampleUpdate(data: any) {
|
||||
return http.request({ url: '/example/update', method: 'PUT', data });
|
||||
}
|
||||
|
||||
// 删除
|
||||
/**
|
||||
* 删除案例演示
|
||||
*
|
||||
* @param id 案例演示ID
|
||||
* @returns 操作结果
|
||||
*/
|
||||
export function exampleDelete(id) {
|
||||
return http.request({ url: '/example/delete/' + id, method: 'DELETE' });
|
||||
return http.request({
|
||||
url: '/example/delete/' + id,
|
||||
method: 'DELETE',
|
||||
});
|
||||
}
|
||||
|
||||
// 批量删除
|
||||
/**
|
||||
* 批量删除案例演示
|
||||
*
|
||||
* @param data 含 ids 数组的对象，形如 { ids: [1, 2, 3] }
|
||||
* @returns 操作结果
|
||||
*/
|
||||
export function exampleBatchDelete(data: any) {
|
||||
return http.request({ url: '/example/batchDelete', method: 'DELETE', data });
|
||||
return http.request({
|
||||
url: '/example/batchDelete',
|
||||
method: 'DELETE',
|
||||
data,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 常见扩展操作
|
||||
## 规范要点
|
||||
|
||||
| 操作 | 函数名示例 | HTTP 方法 |
|
||||
|------|-----------|----------|
|
||||
| 重置密码 | `userResetPwd(data)` | POST |
|
||||
| 导入 | `{module}Import(data: FormData)` | POST（multipart/form-data） |
|
||||
| 导出 | `{module}Export(params)` | GET |
|
||||
| 刷新缓存 | `dictRefreshCache()` | GET |
|
||||
| 获取菜单 | `getMenus()` | GET |
|
||||
| 获取字典项 | `getDictItemList(code)` | GET |
|
||||
| 要点 | 说明 |
|
||||
|---|---|
|
||||
| import 来源 | `import { http } from '@/utils/http/axios'` |
|
||||
| URL 不带 /api | 前缀由 VITE_GLOB_API_URL_PREFIX 统一拼接 |
|
||||
| 只导出函数 | 每函数带 JSDoc（参数/返回说明）；不放状态、不 catch |
|
||||
| DELETE 带 body | 批量删除用 `method: 'DELETE', data`（后端 UnmarshalBody 支持） |
|
||||
| 文件类接口 | 导入传 FormData；导出返回文件 URL 字符串 |
|
||||
| 与 RouteSpec 同步 | 后端加接口 → api 模块加函数，同一 PR |
|
||||
|
||||
## 组件中使用
|
||||
## 禁则
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { getExamplePage, exampleDelete } from '@/api/tool/example';
|
||||
import { ElMessage, ElMessageBox } from 'element-plus';
|
||||
- 不在 api 模块拼完整 URL 域名（部署可变）
|
||||
- 不在 api 模块做数据变换（变换归页面或工具函数）
|
||||
- 不绕过 http 封装直接用 axios 实例
|
||||
|
||||
const tableData = ref([]);
|
||||
## 相关
|
||||
|
||||
// 查询
|
||||
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();
|
||||
};
|
||||
</script>
|
||||
```
|
||||
- [9.4 HTTP 请求封装](/zh/frontend/http.html)
|
||||
- [6.22 示例模块（example）](/zh/modules/example.html)
|
||||
|
||||
Reference in New Issue
Block a user