import{_ as i,o as a,c as t,a2 as n}from"./chunks/framework.B-QBKwc1.js";const g=JSON.parse('{"title":"API 模块编写规范","description":"本节定义前端 API 模块的编写规范，包括命名规范、请求方式和文件组织。","frontmatter":{},"headers":[],"relativePath":"zh/frontend/api-module.md","filePath":"zh/frontend/api-module.md"}'),h={name:"zh/frontend/api-module.md"};function k(l,s,p,e,d,r){return a(),t("div",null,[...s[0]||(s[0]=[n(`

9.13 API 模块编写规范 ​

概述

本节定义前端 API 模块的编写规范，包括命名规范、请求方式和文件组织。

命名规范 ​

类型规范示例
文件名小驼峰，与后端模块对应example.ts
查询函数get{Module}Page / get{Module}List / get{Module}DetailgetExamplePage
新增函数{module}AddexampleAdd
修改函数{module}UpdateexampleUpdate
删除函数{module}Delete / {module}BatchDeleteexampleDelete
导入函数{module}ImportexampleImport
导出函数{module}ExportexampleExport

请求方式 ​

操作HTTP 方法参数传递说明
查询GETparams（URL 参数）分页/列表/详情
新增POSTdata（请求体）JSON 格式
修改PUTdata（请求体）JSON 格式，含 id
删除DELETEURL 参数单条（id 在路径中）
批量删除DELETEdata（请求体 {ids:[]}）本项目统一 DELETE + body

与常见 REST 风格的差异

本项目 batchDelete 为 DELETE（请求体仍传 ids 数组——DELETE 方法携带 body）；resetPwd 为 PUT，account 等扩展操作为 POST——以后端 routes/api.php 实际路由为准（见 8.7 API 接口总览）。

文件组织 ​

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 });
}

拦截器已解包

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
刷新 TokenpostRefresh({ 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 头，公开接口同样可用
导入用 FormDataContent-Type 交给浏览器自动带 boundary，勿手写
导出处理返回值后端返回文件地址（字符串），直接打开下载
`,18)])])}const y=i(h,[["render",k]]);export{g as __pageData,y as default};