Apifox-mock-generator 一键同步接口数据及类型#

背景：从脚手架到「为什么不用 Mock」#

今年 9 月入职现公司后，我接到的第一个任务是封装部门的前端脚手架。在规划能力时，我打算把 Mock 也纳入脚手架，方便大家在本地用假数据联调。结果在例会上讨论时，领导提到：这边平时很少用 Mock 工具开发。

当时心里挺好奇：不用 Mock，那接口数据和类型是怎么跟上的？不过当时没有追问。直到月底要和平台组一起搭两套通用管理平台（租户版与非租户版），才慢慢搞清楚团队的真实工作方式，也才有了后面的故事。

现状：基于 Apifox 的「手搬」工作流#

团队统一使用 Apifox 做接口管理与协作。开发流程大致是：

在 Apifox 里维护接口文档，用系统生成的响应示例作为「假数据」参考；
需要时把响应体示例复制到项目里当 Mock 或测试数据；
接口的 TypeScript 类型同样依赖 Apifox 的「生成代码」功能，生成后再手动复制到项目里。

也就是说：Mock 数据 + 接口类型 都来自 Apifox，但都靠人工复制粘贴落地到代码里。

这种模式带来几个明显问题：

操作繁琐：一个接口至少要复制两次（响应示例 + 类型定义），接口一多就很费时；
变更不敏感：接口一旦在 Apifox 里改了，项目里的类型和 Mock 不会自动更新，容易和文档脱节；
依赖人工：全凭人工搬运，容易漏改、改错，也难以和构建/脚本流程结合。

灵感：前司的 auto-mock 思路#

在前司时，我导师封装过一个 auto-mock 类工具：根据 Eolink 上的接口定义，自动生成 Mock 数据和接口类型，把「文档 → 类型 + Mock」串成一条流水线。

像 Apifox、Eolink 这类 API 平台，都会提供 Open API 给外部系统调用，用来读取项目、接口、模型等信息。既然 Eolink 可以做成 auto-mock，理论上 Apifox 也可以用同样思路做一版，把「生成示例 + 生成类型」自动化掉，减少复制粘贴和遗漏。

方案：apifox-mock-generator 的诞生#

基于上述背景，我利用几个下班时间，基于 Apifox Open API 开发了 apifox-mock-generator 工具，目标是：

从 Apifox 自动拉取接口定义与响应结构；
生成可直接使用的 Mock 数据（可与本地 Mock 服务或脚手架配合）；
生成 TypeScript 接口类型，并支持按项目约定输出到指定目录；
通过脚本/命令集成到现有工作流，减少人工复制，让接口变更更容易被感知和同步。

下面基于 apifox-mock-generator 的用法与设计做具体介绍。

apifox-mock-generator 工具概览#

apifox-mock-generator 是一个 npm 包，功能概括为：从 Apifox 拉取 API 接口定义，生成本地 Mock 数据与 TypeScript 类型文件，并内置 Mock 服务器。当前最新版本为 2.x，开源仓库：GitHub - lukemora/apifox-mock-generator。

核心能力#

能力	说明
Apifox 集成	通过 Apifox Open API 自动拉取项目内接口定义（支持 OpenAPI 3.0）
类型生成	生成 TypeScript 类型文件（.ts），支持复杂类型、嵌套对象、枚举等
Mock 规则继承	直接使用 Apifox 中配置的 mock 规则，无需在本地再配一遍，继承 Apifox 的数据生成能力
本地 Mock 服务	基于 Express 的 Mock 服务器，支持 CORS，可热重载
Mock / 代理切换	支持全局模式切换，也支持按接口粒度配置某条路由走 Mock 或走真实后端
动态代理	通过页面 URL 参数（如 `?remote=mock` 或 `?remote=https://api.xxx.com`）快速切换后端环境，无需改配置文件

整体上，把原先「在 Apifox 复制示例 + 复制类型」的手动流程，收敛为「配置一次 → 一条命令生成 → 本地服务直接可用」，接口有变更时重新执行生成即可同步。

安装与基本用法#

在任意前端项目（如 Vue / Vite）中安装：

1
pnpm add apifox-mock-generator -D

需要两个配置文件：

apifox.config.json（项目根目录）配置 Apifox 的 projectId、token，以及生成目录 mockDir、typesDir，还可通过 apiFilter 按标签、路径、方法等筛选要生成的接口。
mock.config.js（项目根目录）配置 Mock 服务器的端口、工作模式（mock / proxy）、代理目标 target，以及可选的 mockRoutes / proxyRoutes 做按接口粒度的 Mock/代理控制。

在 package.json 中增加脚本：

1
{
2
  "scripts": {
3
    "auto-mock": "apifox-mock generate",
4
    "mock": "apifox-mock serve"
5
  }
6
}

执行 pnpm auto-mock：从 Apifox 拉取接口并生成 Mock 文件 + TS 类型到配置的目录。
执行 pnpm mock：启动本地 Mock 服务器（默认端口 10000），前端通过 Vite 等代理将 /api 指向该端口即可。

生成的类型可直接在业务代码中引用，例如：

1
import type { xxx } from './src/types/mock/xxx';

工作流简述#

在 Apifox 中维护接口文档（含响应结构、Mock 规则）；
本地执行 apifox-mock generate，拉取 OpenAPI 数据并生成 mock/ 与类型目录；
启动 apifox-mock serve，前端通过代理访问 Mock 服务器；
需要联调时，在 mock.config.js 中切到 proxy 模式或通过 URL 参数 ?remote=目标地址 指向真实后端。

这样，接口变更时只需在 Apifox 更新文档并重新执行一次 generate，即可同步类型与 Mock，避免人工复制带来的遗漏与不一致。

luke's blog