---
name: api-service-pattern
description: API 接口定义模式，包括类型定义、接口函数、分页查询、命名空间规范。

origin: ECC

API 接口定义模式

项目 API 接口开发规范，使用 namespace 组织类型和函数。

When to Use

• 创建新的 API 接口文件
• 定义接口请求/响应类型
• 编写 CRUD 接口函数
• 处理分页查询

文件结构

src/api/
└── mes/
    └── pro/
        └── workorder/
            ├── index.ts          # 工单接口
            └── bom/
                └── index.ts      # 工单 BOM 接口

接口定义模板

import type { PageParam, PageResult } from '@vben/request';

import { requestClient } from '#/api/request';

export namespace WorkOrderApi {
  /** 工单信息 */
  export interface WorkOrder {
    id?: number;                    // 编号
    code?: string;                  // 编码
    name?: string;                  // 名称
    status?: number;                // 状态
    createTime?: number;            // 创建时间
  }

  /** 分页查询参数 */
  export interface PageParams extends PageParam {
    code?: string;
    name?: string;
    status?: number;
  }
}

/** 查询工单分页 */
export function getWorkOrderPage(params: WorkOrderApi.PageParams) {
  return requestClient.get<PageResult<WorkOrderApi.WorkOrder>>(
    '/mes/pro/work-order/page',
    { params },
  );
}

/** 查询工单详情 */
export function getWorkOrder(id: number) {
  return requestClient.get<WorkOrderApi.WorkOrder>(
    `/mes/pro/work-order/get?id=${id}`,
  );
}

/** 新增工单 */
export function createWorkOrder(data: WorkOrderApi.WorkOrder) {
  return requestClient.post<number>('/mes/pro/work-order/create', data);
}

/** 修改工单 */
export function updateWorkOrder(data: WorkOrderApi.WorkOrder) {
  return requestClient.put('/mes/pro/work-order/update', data);
}

/** 删除工单 */
export function deleteWorkOrder(id: number) {
  return requestClient.delete(`/mes/pro/work-order/delete?id=${id}`);
}

/** 导出工单 */
export function exportWorkOrder(params: any) {
  return requestClient.download('/mes/pro/work-order/export-excel', { params });
}

类型定义规范

实体接口

export namespace ItemApi {
  /** 物料信息 */
  export interface Item {
    id?: number;                    // 编号（可选，新增时无）
    code: string;                   // 编码（必填）
    name: string;                   // 名称（必填）
    specification?: string;         // 规格型号
    unitMeasureId?: number;         // 单位编号
    unitMeasureName?: string;       // 单位名称（冗余字段）
    status?: number;                // 状态
    remark?: string;                // 备注
    createTime?: number;            // 创建时间
  }
}

分页参数

export namespace ItemApi {
  /** 分页查询参数 */
  export interface PageParams extends PageParam {
    code?: string;                  // 编码（模糊）
    name?: string;                  // 名称（模糊）
    status?: number;                // 状态
    categoryId?: number;            // 分类编号
    createTime?: number[];          // 创建时间范围
  }
}

列表接口

export namespace ProcessApi {
  /** 工序精简信息（下拉选择用） */
  export interface ProcessSimple {
    id: number;
    code: string;
    name: string;
  }
}

/** 查询工序列表 */
export function getProcessList(params?: ProcessApi.ListParams) {
  return requestClient.get<ProcessApi.Process[]>(
    '/mes/pro/process/list',
    { params },
  );
}

/** 查询工序精简列表 */
export function getProcessSimpleList() {
  return requestClient.get<ProcessApi.ProcessSimple[]>(
    '/mes/pro/process/simple-list',
  );
}

请求方法映射

子模块接口

子模块接口放在父模块目录下：

src/api/mes/pro/workorder/
├── index.ts          # 工单接口
└── bom/
    └── index.ts      # 工单 BOM 接口

// bom/index.ts
export namespace WorkOrderBomApi {
  export interface WorkOrderBom {
    id?: number;
    workOrderId?: number;           // 关联父表
    itemId?: number;
    itemName?: string;
    quantity?: number;
  }

  export interface PageParams extends PageParam {
    workOrderId?: number;           // 必须有父表 ID
  }
}

导入使用

// 导入类型
import type { WorkOrderApi } from '#/api/mes/pro/workorder';
import type { WorkOrderBomApi } from '#/api/mes/pro/workorder/bom';

// 导入函数
import { getWorkOrderPage, createWorkOrder } from '#/api/mes/pro/workorder';

注意事项

1. 使用 namespace 组织类型：避免类型命名冲突
2. 实体字段全部可选：适应新增/编辑/查询场景
3. 分页参数继承 PageParam：包含 pageNo、pageSize
4. 返回类型明确指定：requestClient.get<T>
5. 路径参数使用模板字符串：/module/get?id=${id}