---
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 接口
```

## 接口定义模板

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

## 类型定义规范

### 实体接口

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

### 分页参数

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

### 列表接口

```typescript
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',
  );
}
```

## 请求方法映射

| 操作 | 方法 | URL 格式 | 返回类型 |
|-----|------|---------|---------|
| 分页查询 | GET | `/module/page` | `PageResult<T>` |
| 列表查询 | GET | `/module/list` | `T[]` |
| 精简列表 | GET | `/module/simple-list` | `SimpleT[]` |
| 详情查询 | GET | `/module/get?id=` | `T` |
| 新增 | POST | `/module/create` | `number` |
| 修改 | PUT | `/module/update` | `void` |
| 删除 | DELETE | `/module/delete?id=` | `void` |
| 导出 | GET | `/module/export-excel` | `Blob` |

## 子模块接口

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

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

```typescript
// 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
  }
}
```

## 导入使用

```typescript
// 导入类型
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}`