🧩 TypeScript Mock 数据生成器

一个强大的 TypeScript Mock 数据生成工具，基于 JSON Schema，可以从 TypeScript 接口自动生成符合类型约束的模拟数据。

✨ 功能特点

• 🔄 从 TypeScript 接口自动生成 JSON Schema
• 🎭 基于 JSON Schema 生成符合类型约束的 Mock 数据
• ✅ 支持 TypeScript 类型验证（通过 JSON Schema 规范）
• 📏 支持丰富的验证规则（最小/最大值、模式匹配、格式等）
• 🔌 支持自定义验证关键字（如 autoIncrement、fake 等）
• 📁 支持通过文件夹组织生成的文件（schemas/mocks）
• 🛠️ 提供完整的 CLI 和 API 使用方式

📦 安装

1# 使用 npm
2npm install -g @kwayteow/typeseer
3npm install @kwayteow/typeseer --save-dev
4
5# 使用 yarn
6yarn global add @kwayteow/typeseer
7yarn add @kwayteow/typeseer --dev
8
9# 使用 pnpm
10pnpm add -g @kwayteow/typeseer
11pnpm add @kwayteow/typeseer -D

💻 命令行使用

📐 生成 Schema

1typeseer schema -f src/types.ts -s User -o user-schema.json

参数:

• -f, --file: TypeScript 文件路径（必填）
• -s, --symbol: 要生成 Schema 的类型名称（必填）
• -o, --output: 输出文件路径（可选，不提供则输出到控制台）

🎲 生成 Mock 数据

1typeseer mock -s user-schema.json -o user-mock.json -c 5

参数:

• -s, --schema: JSON Schema 文件路径（必填）
• -o, --output: 输出文件路径（可选，不提供则输出到控制台）
• -c, --count: 生成数据条数（默认为 1）

🚀 一键生成

1typeseer generate -f src/types.ts -s User -o ./output -c 5
2# 使用文件夹组织生成的文件
3typeseer generate -f src/types.ts -s User -o ./output -c 5 -u

参数:

• -f, --file: TypeScript 文件路径（必填）
• -s, --symbol: 要生成的类型名称（必填）
• -o, --output: 输出目录（默认为 ./output）
• -c, --count: 生成数据条数（默认为 1）
• -u, --use-folder: 使用文件夹组织生成的文件（将在输出目录下创建 schemas 和 mocks 文件夹）

🔌 API 使用

📐 生成 Schema

1import { generateSchema } from "@kwayteow/typeseer";
2
3// 从 TypeScript 文件生成 Schema
4const schema = generateSchema("src/types.ts", "User");
5
6// 从 TypeScript 文件生成 Schema 并保存到文件
7generateSchema("src/types.ts", "User", "user-schema.json");

🎲 生成 Mock 数据

1import { generateMock, generateMultipleMocks } from "@kwayteow/typeseer";
2
3// 从 Schema 对象生成 Mock 数据
4const schema = {
5  /* JSON Schema 对象 */
6};
7const mockData = await generateMock(schema);
8
9// 从 Schema 文件生成 Mock 数据
10const mockData = await generateMock("user-schema.json");
11
12// 生成多条 Mock 数据
13const mockDataList = await generateMultipleMocks(schema, 5);
14
15// 生成多条 Mock 数据并保存到文件
16await generateMultipleMocks(schema, 5, "user-mocks.json");

📝 类型约束和验证规则

TypeSeer 支持通过 JSDoc 注解为 TypeScript 类型添加各种约束条件，这些约束会被转换为 JSON Schema，并在生成 Mock 数据时应用。

数值约束

1interface Product {
2  /**
3   * @minimum 0
4   * @maximum 1000
5   */
6  price: number;
7
8  /**
9   * @multipleOf 0.5
10   */
11  weight: number;
12
13  /**
14   * @exclusiveMinimum 0
15   * @exclusiveMaximum 100
16   */
17  stock: number;
18
19  /**
20   * @enum {number} [0, 1, 2]
21   */
22  status: number;
23
24  /**
25   * @autoIncrement true
26   * @initialOffset 1000
27   */
28  id: number;
29}

字符串约束

1interface User {
2  /**
3   * @minLength 3
4   * @maxLength 50
5   */
6  username: string;
7
8  /**
9   * @pattern ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
10   */
11  email: string;
12
13  /**
14   * @format date
15   */
16  birthdate: string;
17
18  /**
19   * @enum {string} ["admin", "user", "guest"]
20   */
21  role: string;
22
23  /**
24   * @fake {{name.firstName}}
25   */
26  firstName: string;
27
28  /**
29   * @format uuid
30   */
31  id: string;
32}

数组约束

1interface Post {
2  /**
3   * @minItems 1
4   * @maxItems 10
5   * @uniqueItems true
6   */
7  tags: string[];
8}

对象约束

1/**
2 * @additionalProperties false
3 */
4interface Config {
5  // 只允许定义的属性，不允许额外属性
6  name: string;
7  version: string;
8}

自定义描述和默认值

1interface Settings {
2  /**
3   * @description "用户首选主题"
4   * @default "light"
5   */
6  theme: string;
7}

自定义模拟数据

可以使用 @fake 标记生成特定模拟数据（基于 faker.js）：

1interface User {
2  /**
3   * @fake {{name.firstName}}
4   */
5  firstName: string;
6
7  /**
8   * @fake {{internet.email}}
9   */
10  email: string;
11
12  /**
13   * @fake {{phone.phoneNumber}}
14   */
15  phone: string;
16}

支持的格式

使用 @format 可以生成符合特定格式的数据：

1interface Document {
2  /**
3   * @format uuid
4   */
5  id: string;
6
7  /**
8   * @format email
9   */
10  contactEmail: string;
11
12  /**
13   * @format date
14   */
15  createdAt: string;
16
17  /**
18   * @format date-time
19   */
20  updatedAt: string;
21
22  /**
23   * @format ipv4
24   */
25  serverIp: string;
26}

自增 ID 支持

可以使用 @autoIncrement 和 @initialOffset 生成自增 ID：

1interface Record {
2  /**
3   * @autoIncrement true
4   * @initialOffset 1000
5   */
6  id: number;
7
8  /**
9   * @type integer
10   * @autoIncrement true
11   * @initialOffset 1
12   */
13  sequence: number;
14}

🔧 高级配置

TypeSeer 提供了一些高级配置选项，可以通过 API 使用：

1import { generateSchema, tjsDefaultSettings } from "@kwayteow/typeseer";
2
3// 自定义 TypeScript JSON Schema 设置
4const customSettings = {
5  ...tjsDefaultSettings,
6  required: false, // 不强制要求所有属性
7  validationKeywords: [
8    ...tjsDefaultSettings.validationKeywords,
9    "customKeyword", // 添加自定义关键字
10  ],
11};
12
13// 使用自定义设置生成 Schema
14const schema = generateSchema(
15  "src/types.ts",
16  "User",
17  undefined,
18  customSettings
19);

JSON Schema Faker 配置

TypeSeer 内部使用 JSON Schema Faker 生成 Mock 数据，默认配置如下：

1JSONSchemaFaker.option({
2  // 总是为可选字段生成数据，即使该字段是可选的
3  alwaysFakeOptionals: true,
4  // 如果 schema 中定义了默认值，优先使用默认值而不是生成随机值
5  useDefaultValue: true,
6  // 当遇到 schema 中的引用($ref)找不到时，忽略错误继续执行
7  ignoreMissingRefs: true,
8  // 生成数组类型数据时的最大长度
9  maxItems: 5,
10  // 生成数组类型数据时的最小长度
11  minItems: 1,
12});

更多约束规则请参考：

• JSON Schema 规范
• typescript-json-schema 文档
• JSON Schema Faker 文档

📂 推荐的项目结构

project/
├── src/
│   ├── types/        # TypeScript 类型定义
│   ├── schemas/      # 生成的 JSON Schema
│   └── mocks/        # 生成的 Mock 数据
├── ...

这种组织方式有助于保持项目结构清晰，特别是在处理多种类型和模型时。

🧪 测试

本项目使用 Vitest 进行单元测试。

1pnpm test
2# 或
3npm run test

🛠️ 依赖

• typescript-json-schema
• json-schema-faker
• commander

🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！请遵循以下步骤：

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加某个功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📜 许可证

MIT