停止等待后端 API：推出 Fakelab，TypeScript-First Mock Server
Source: Dev.to
如果你是前端开发者，你一定遇到过这种情况：你已经准备好开发一个功能，但后端 API 还没有准备好。或者它已经准备好，但速度慢、不可靠，或者需要在本地设置的身份验证非常麻烦。你需要真实的数据来进行开发，但又不想花几个小时编写 mock 处理程序或维护与类型不同步的 JSON 固件。
我也有同样的经历。这就是我创建 Fakelab 的原因——一个直接从你的 TypeScript 接口生成真实数据的 mock API 服务器。经过数月的开发和真实场景测试，我现在发布 v1.0。
Mock API 的真实问题
我认识的大多数前端开发者都使用以下一种方式：
选项 1：硬编码 JSON 文件
- 启动快，但维护起来会变成噩梦
- 没有类型安全
- 数据会变陈旧
- 难以生成多种变体
选项 2：使用 json-server 或 MSW 等工具
json-server很好用，但仍需手动编写 JSON- MSW 功能强大，但需要为每个端点编写处理器
- 两者都要求你将模拟数据与类型分开维护
选项 3：等待后端
- 如果想要交付功能，这根本不是选项
核心问题是 重复：你在 TypeScript 中定义类型，然后在别处定义模拟数据。类型一变，模拟就会出错；模拟一改，类型可能就不对了。这始终是摩擦的来源。
为什么现有工具不够
我尝试了所有办法。json-server 很可靠，但我厌倦了编写与我的类型不匹配的 JSON。MSW 在测试时表现出色，但在开发时我想要更简单的方案——只要指向我的 TypeScript 文件就能得到一个 API。
MirageJS 接近我的需求，但对我来说显得有些笨重，且 API 感觉有点过时。我想要一种与现代 TypeScript 工作流天然契合的工具。
我真正想要的是：
- 一次定义类型，自动生成 mock 数据
- 类型安全的 mock 数据生成
- 无需手动编写即可得到真实感的数据
- 用于测试有状态操作的持久化数据库
- 用于测试边缘情况的网络模拟
- 零样板代码
于是我创建了 Fakelab。
Fakelab 是什么？
Fakelab 是一个基于 Node.js 的 mock API 服务器，它读取你的 TypeScript 接口并生成带有真实感假数据的 REST 端点。你可以使用 JSDoc 注释在类型上添加 Faker.js 指令，剩下的交给 Fakelab 来处理。
亮点
- TypeScript‑first – 您的类型是真实数据的唯一来源。无需单独的 mock 定义。
- Zero boilerplate – 为接口添加注解，启动服务器，即可获得端点。
- Persistent database – 内置数据库模式让您可以测试创建、更新和删除操作。
- Snapshot real APIs – 捕获真实 API 的响应并将其转化为可复用的 mock。
- Network simulation – 在不修改代码的情况下测试加载状态、重试和错误处理。
- Runtime API – 使用简洁的 API 在前端代码中访问 mock。
功能要点说明
TypeScript‑First 与 Faker 注解
与其手动编写模拟数据，不如在 TypeScript 接口上添加注解：
// fixtures/user.ts
export interface User {
/** @faker string.ulid */
id: string;
/** @faker person.fullName */
name: string;
/** @faker location.streetAddress */
address: string;
/** @faker phone.number */
phone: string;
/** @faker number.int({ min: 10, max: 80 }) */
age: number;
}Fakelab 会解析这些注解并使用 Faker.js 生成逼真的数据。当你请求 /api/User 时，会得到一个包含真实姓名、地址和电话号码的用户数组，而不是 "test" 或 "asdf"。
Snapshot：捕获真实 API
我最喜欢的功能之一是 snapshot 命令。有时你想从已有的 API 快速生成模拟数据：
npx fakelab snapshot https://jsonplaceholder.typicode.com/todos --name TodoFakelab 会抓取响应，推断出 TypeScript 类型，并将其保存为模拟源。以后可以刷新，或在配置中定义多个源。这在从真实 API 迁移或需要离线开发时冻结响应特别有用。
数据库模式
默认情况下，Fakelab 会在每次请求时生成全新的数据。若要测试有状态的操作，可以启用数据库模式：
// fakelab.config.ts
export default defineConfig({
database: { enabled: true },
});这样就可以种子数据、查询、更新记录，并测试应用的数据流。数据库在服务器重启之间保持持久（底层只是使用 lowdb 的 JSON 文件）。
网络模拟
当你的模拟始终瞬间成功时，测试错误状态和加载指示器会非常烦人。Fakelab 让你模拟真实的网络条件：
network: {
delay: [300, 1200], // 随机延迟 300‑1200 ms
errorRate: 0.1, // 10 % 的请求失败
timeoutRate: 0.05, // 5 % 的请求超时
errors: {
statusCodes: [400, 404, 500],
},
}你可以在不手动 mock fetch 或 axios 的情况下，测试重试逻辑、错误边界和加载状态。
运行时 API
Fakelab 提供了一个运行时 API，前端可以直接使用：
import { fakelab } from "fakelab/browser";
// 获取 10 条用户数据
const users = await fakelab.fetch("User", 10);
// 获取基础 URL
const apiUrl = fakelab.url(); // "http://localhost:50000/api"当你需要以编程方式生成数据或将 Fakelab 融入开发工作流时，这非常有用。
简短代码示例
下面是一个完整示例。首先，定义类型和配置：
// fakelab.config.ts
import { defineConfig } from "fakelab";
export default defineConfig({
sourcePath: ["./fixtures"],
server: { port: 50000 },
database: { enabled: true },
network: {
delay: [200, 800],
errorRate: 0.05,
},
});// fixtures/product.ts
export interface Product {
/** @faker string.uuid */
id: string;
/** @faker commerce.productName */
name: string;
/** @faker commerce.price */
price: number;
/** @faker commerce.department */
category: string;
}启动服务器：
npx fakelab start现在，你拥有一个运行在 http://localhost:50000/api 的完整功能模拟 API，能够提供真实的 Product 数据、持久化存储以及网络模拟——所有这些都源自单个 TypeScript 接口。
// fakelab.config.ts (alternative minimal config)
import { defineConfig } from "fakelab";
export default defineConfig({
port: 50101,
database: { enabled: true },
});启动服务器
npx fakelab serve此时你拥有：
GET /api/User– 返回用户数组GET /api/User?count=5– 返回 5 条用户数据POST /api/User– 创建新用户（前提是已启用数据库）
在 React 应用中使用
import { fakelab } from "fakelab/browser";
const users = await fakelab.fetch("User", 10);
// 或者使用普通的 fetch:
const response = await fetch("http://localhost:50000/api/User");Source: …
50101/api/User?count=10");
const users = await response.json();就是这样。没有处理程序，没有 JSON 文件，没有样板代码。
当你应该使用 Fakelab（以及何时不该使用）
使用 Fakelab 的情形：
- 你在构建前端，而后端尚未准备好。
- 你想离线开发或不依赖后端。
- 需要使用真实的数据变体进行测试。
- 想要类型安全的 mock，且能与类型保持同步。
- 正在做原型，需要快速得到一个 API。
不要使用 Fakelab 的情形：
- 需要在 mock 中实现复杂业务逻辑（此时使用 MSW）。
- 进行与真实后端的集成测试（使用真实 API）。
- 需要 GraphQL（Fakelab 目前仅支持 REST）。
- 需要认证/授权逻辑（Fakelab 故意保持简洁）。
Fakelab 是一种开发工具，而非测试框架。它旨在加快前端开发并提升独立性，而不是取代集成测试。
为谁而建
- 前端开发者，希望独立工作。
- React/Next.js 开发者，需要快速获取真实数据。
- 团队，前后端并行工作。
- 开发者，重视类型安全并希望模拟符合其类型。
如果你熟悉 MSW、json‑server 或 MirageJS，Fakelab 应该会感觉熟悉但更简洁。如果你从未使用过模拟服务器，Fakelab 可能是最容易上手的选择。
未来路线图
Fakelab v1 稳定且对大多数用例功能完整，但还有更多功能即将推出：
- GraphQL 支持 – 根据你的类型生成 GraphQL 架构。
- 自定义生成器 – 编写超出 Faker 的自定义数据生成器。
- 关系 – 定义类型之间的关系（例如，User 拥有多个 Posts）。
- Webhook 改进 – 重试机制和更好的错误处理。
- 性能 – 为更大的数据集和更快的启动进行优化。
我也欢迎功能请求。如果 Fakelab 没有满足你的需求，请打开 issue 并让我们讨论。
试一试
Fakelab 是开源的，采用 MIT 许可证。使用以下命令安装：
npm install fakelab --save-dev如果你尝试后发现它能帮助你更快发布，请告诉我。如果遇到问题或有想法，请提交 issue 或 PR。这是我为自己构建的工具，但我愿意分享，因为我认为其他开发者也会觉得它很有用。
结束语
构建 Fakelab 让我深刻了解了开发者真正需要的工具。我们不需要更多功能——我们需要的是不妨碍我们、让我们专注于构建的工具。Fakelab 并不是想要面面俱到，而是专注于做好一件事：提供一个与你的 TypeScript 类型配合使用的 mock API 服务器，而不是与之冲突。
如果这对你有用，试试看吧。如果不需要，也没关系。但如果你厌倦了等待后端 API 或者维护总是不同步的 mock 数据，Fakelab 可能正是你想要的。