签入版本

2026-09-16 10:11:44 +08:00
parent bf08cf1248
commit 20d8a85989
205 changed files with 34363 additions and 0 deletions
@@ -0,0 +1,185 @@
+# 前端 API 层
+
+前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。
+
+## 文件位置
+
+```
+ui/src/api/system/position.ts
+```
+
+## 完整代码
+
+```typescript
+import { http } from '@/utils/http/axios';
+
+/**
+ * @description: 岗位列表（分页）
+ */
+export function getPositionList(params?) {
+  return http.request({
+    url: '/position/page',
+    method: 'GET',
+    params,
+  });
+}
+
+/**
+ * 获取全部岗位列表（无分页，用于下拉选择）
+ * @param params 参数
+ * @returns 返回结果
+ */
+export function getPositionAllList(params?) {
+  return http.request({
+    url: '/position/list',
+    method: 'GET',
+    params,
+  });
+}
+
+/**
+ * @description: 根据ID获取详情
+ */
+export function getPositionDetail(positionId) {
+  return http.request({
+    url: '/position/detail/' + positionId,
+    method: 'get',
+  });
+}
+
+/**
+ * @description: 添加岗位
+ */
+export function positionAdd(data: any) {
+  return http.request({
+    url: '/position/add',
+    method: 'POST',
+    data,
+  });
+}
+
+/**
+ * @description: 更新岗位
+ */
+export function positionUpdate(data: any) {
+  return http.request({
+    url: '/position/update',
+    method: 'PUT',
+    data,
+  });
+}
+
+/**
+ * @description: 删除岗位
+ */
+export function positionDelete(positionId) {
+  return http.request({
+    url: '/position/delete/' + positionId,
+    method: 'DELETE',
+  });
+}
+
+/**
+ * @description: 批量删除岗位
+ */
+export function positionBatchDelete(data: any) {
+  return http.request({
+    url: '/position/batchDelete',
+    method: 'DELETE',
+    data,
+  });
+}
+```
+
+## 代码解析
+
+### HTTP 客户端
+
+```typescript
+import { http } from '@/utils/http/axios';
+```
+
+`http` 是项目封装的 Axios 实例，自动处理：
+- 请求拦截：添加 JWT Token（`Authorization: Bearer xxx`）
+- 响应拦截：统一处理错误码、弹出提示
+- 基础路径：自动拼接 `/api/v1` 前缀
+
+### 请求方式
+
+```typescript
+http.request({
+  url: '/position/page',   // 接口路径（不含 /api/v1 前缀）
+  method: 'GET',           // HTTP 方法
+  params,                  // GET 参数（拼接到 URL 查询字符串）
+})
+```
+
+| 参数 | 用途 |
+|:----|:----|
+| `url` | 接口路径，与后端 router 定义的 path 对应 |
+| `method` | HTTP 方法：GET / POST / PUT / DELETE |
+| `params` | GET 请求参数（拼接到 URL） |
+| `data` | POST/PUT/DELETE 请求体（JSON） |
+
+### 函数命名规范
+
+| 模式 | 示例 | 说明 |
+|:----|:----|:----|
+| `get{Module}List` | `getPositionList` | 分页列表查询 |
+| `get{Module}AllList` | `getPositionAllList` | 全量列表查询 |
+| `get{Module}Detail` | `getPositionDetail` | 详情查询 |
+| `{module}Add` | `positionAdd` | 新增 |
+| `{module}Update` | `positionUpdate` | 更新 |
+| `{module}Delete` | `positionDelete` | 单条删除 |
+| `{module}BatchDelete` | `positionBatchDelete` | 批量删除 |
+
+### 参数传递区别
+
+```typescript
+// GET：参数通过 params 传递（拼接到 URL 查询字符串）
+http.request({ url: '/position/page', method: 'GET', params })
+
+// POST/PUT/DELETE：参数通过 data 传递（放入请求体 JSON）
+http.request({ url: '/position/add', method: 'POST', data })
+
+// 路径参数：直接拼接到 URL
+http.request({ url: '/position/delete/' + positionId, method: 'DELETE' })
+```
+
+## 页面中的调用方式
+
+```vue
+<script setup>
+import { getPositionList, positionDelete, positionBatchDelete } from '@/api/system/position';
+
+// 分页查询
+const result = await getPositionList({ pageNo: 1, pageSize: 10, name: '测试' });
+
+// 详情查询
+const detail = await getPositionDetail(1);
+
+// 新增
+await positionAdd({ name: '新岗位', status: 1, sort: 0 });
+
+// 更新
+await positionUpdate({ id: 1, name: '修改后', status: 1, sort: 1 });
+
+// 单条删除
+await positionDelete(1);
+
+// 批量删除
+await positionBatchDelete([1, 2, 3]);
+</script>
+```
+
+## 开发要点
+
+1. **一个模块一个文件**：放在 `ui/src/api/{group}/` 目录下
+2. **URL 不含 `/api/v1` 前缀**：`http` 自动拼接
+3. **GET 用 `params`，POST/PUT/DELETE 用 `data`**：参数传递方式不同
+4. **路径参数直接拼接到 URL**：如 `/position/delete/` + id
+5. **批量删除的参数是数组**：`data: [1, 2, 3]`
+
+## 总结
+
+前端 API 层使用封装后的 `VAxios` 发送请求，URL 使用相对路径（不含 `/api/v1` 前缀），函数命名采用 `名词+动词` 格式。GET 请求用 `params`，POST/PUT/DELETE 用 `data`，响应拦截器自动处理错误。