签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,125 @@
+# 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 参数或 `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
+```
+
+## 标准模板
+
+```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' });
+}
+
+// 批量删除
+export function exampleBatchDelete(data: any) {
+  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 |
+
+## 组件中使用
+
+```vue
+<script setup lang="ts">
+import { getExamplePage, exampleDelete } from '@/api/tool/example';
+import { ElMessage, ElMessageBox } from 'element-plus';
+
+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>
+```