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 接口总览）。 :::

文件组织

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

标准模板

// 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（公开接口）

组件中使用

<script setup lang="ts">
import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
import { useMessage, useDialog } from 'naive-ui';

const message = useMessage();
const dialog = useDialog();
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) => {
  dialog.warning({
    title: '提示',
    content: '确认删除？',
    positiveText: '确定',
    negativeText: '取消',
    onPositiveClick: async () => {
      await exampleDelete(id);
      message.success('删除成功');
      fetchData();
    },
  });
};

// 批量删除
const handleBatchDelete = async (ids) => {
  await exampleBatchDelete({ ids });
  message.success('删除成功');
  fetchData();
};
</script>

编写检查清单

检查项	说明
URL 与后端路由一致	逐字符核对 `routes/api.php`（二级路径模块名如 `file/template`）
HTTP 方法正确	特别注意 `batchDelete`=DELETE（带 body）、`runOnce/pause/resume`=GET
认证接口不需要带公开标记	拦截器自动加 Bearer 头，公开接口同样可用
导入用 FormData	`Content-Type` 交给浏览器自动带 boundary，勿手写
导出处理返回值	后端返回文件地址（字符串），直接打开下载

5.6 KiB Raw Permalink Blame History Unescape Escape