9.13 API 模块编写规范

概述

api 模块按域组织（src/api/{域}/{模块}.ts），每接口一个导出函数，内部 http.request 调用。url 对齐后端 gmeta path（无 /api 前缀、无 /v1）。本节给出规范与真实示例。

文件组织

src/api/{域}/{模块}.ts        域与后端模块域一致（system/data/content/monitor/tool）
src/api/common/*.ts          跨域公共接口（city/index/menu/user）
命名：驼峰（fileTemplate.ts、onlineUser.ts、cacheMonitor.ts）
函数命名：get{Mod}Page / get{Mod}Detail / {mod}Add / {mod}Update /
         {mod}Delete / {mod}BatchDelete / {mod}Import / {mod}Export

真实示例（摘自 src/api/tool/example.ts）

import { http } from '@/utils/http/axios';

/**
 * 案例演示模块接口
 *
 * 提供案例演示的增删改查及导入导出接口调用。
 */

/**
 * 获取案例演示分页列表
 *
 * @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,
  });
}

/**
 * 根据 ID 获取案例演示详情
 *
 * @param id 案例演示ID
 * @returns 案例演示详情数据
 */
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,
  });
}

url 对齐规则

前端 api url          后端 gmeta path          说明
'/example/page'   ↔   /api/example/page       baseURL 已含 /api
'/example/detail/' + id ↔ /api/example/detail/:id   路由参数拼接
'/config/item/page' ↔  /api/config/item/page  子资源前缀对齐

禁止：写 '/api/example/page'（重复）；写 '/v1/...'（无版本段）

请求方法与参数位置

方法	参数位置	说明
GET	params	查询参数（分页/筛选/路由参数）
POST/PUT	data	JSON body（AddReq/UpdateReq 结构）
DELETE	url 路径参数 或 data	/delete/:id 走路径；/batchDelete 走 data {ids:[]}

导入导出函数

// 导入：multipart（组件内组装 FormData，api 层可直接透传）
export function exampleImport(data: any) {
  return http.request({
    url: '/example/import',
    method: 'POST',
    data,            // FormData（Content-Type 自动 multipart）
  });
}

// 导出：GET + 筛选参数（导出=所见）
export function getExampleExport(params?: Record<string, any>) {
  return http.request({
    url: '/example/export',
    method: 'GET',
    params,
  });
}

编写规约

1. 一接口一函数，JSDoc 注释（参数/返回/用途）——生成器模板同款风格
2. url 从后端 gmeta path 抄写（去掉 /api 前缀），改动后端 path 同步前端
3. method 与 gmeta method 一致（大小写不敏感但团队统一大写 GET/POST/PUT/DELETE）
4. 不在 api 层做数据加工（transform 解包已完成；加工放页面/组合式函数）
5. 复杂请求（上传/下载/超时定制）用 RequestOptions 第三参数定制
6. 新增函数后对照 /api.json 核对路径与方法