# @flatjs/mock

> ## @flatjs/mock 使用指南

Latest version **2.5.0** (published 2026-08-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @flatjs/mock
pnpm add @flatjs/mock
yarn add @flatjs/mock
bun add @flatjs/mock
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.5.0 |
| Published | 2026-08-18 |
| First published | 2021-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18.0.0 |
| Dependencies | 30 |
| Unpacked size | 66.5 KB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| Maintainers | tcsk2026, tianyingchun, shunqwang |

## Links

- npm: https://www.npmjs.com/package/@flatjs/mock
- npm.io page: https://npm.io/package/@flatjs/mock

## Dependencies (30)

- [ip](https://npm.io/package/ip.md) ^2.0.1
- [cors](https://npm.io/package/cors.md) ^2.8.6
- [listr](https://npm.io/package/listr.md) ^0.14.3
- [lodash](https://npm.io/package/lodash.md) ^4.18.1
- [mockjs](https://npm.io/package/mockjs.md) ^1.1.0
- [esbuild](https://npm.io/package/esbuild.md) ^0.28.1
- [express](https://npm.io/package/express.md) ^5.2.1
- [iterare](https://npm.io/package/iterare.md) ^1.2.1
- [chokidar](https://npm.io/package/chokidar.md) ^5.0.0
- [get-port](https://npm.io/package/get-port.md) ^7.2.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.3.3
- [type-fest](https://npm.io/package/type-fest.md) ^5.7.0
- [typescript](https://npm.io/package/typescript.md) ^6.0.3
- [body-parser](https://npm.io/package/body-parser.md) ^2.3.0
- [express-mung](https://npm.io/package/express-mung.md) ^0.5.1
- [get-tsconfig](https://npm.io/package/get-tsconfig.md) ^4.14.0
- [@flatjs/forge](https://npm.io/package/@flatjs/forge.md) 2.4.0
- [@types/mockjs](https://npm.io/package/@types/mockjs.md) ^1.0.10
- [serve-favicon](https://npm.io/package/serve-favicon.md) ^2.5.1
- [@armit/package](https://npm.io/package/@armit/package.md) ^0.3.1
- [@flatjs/common](https://npm.io/package/@flatjs/common.md) 2.3.0
- [path-to-regexp](https://npm.io/package/path-to-regexp.md) ^8.4.2
- [class-validator](https://npm.io/package/class-validator.md) ^0.15.1
- [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1
- [@armit/file-utility](https://npm.io/package/@armit/file-utility.md) ^0.3.1
- [@rollup/pluginutils](https://npm.io/package/@rollup/pluginutils.md) ^5.4.0
- [http-proxy-middleware](https://npm.io/package/http-proxy-middleware.md) ^4.1.1
- [@hyperse/config-loader](https://npm.io/package/@hyperse/config-loader.md) ^1.0.9
- [@hyperse/delete-empty-folders](https://npm.io/package/@hyperse/delete-empty-folders.md) ^1.0.1
- [@flatjs/forge-plugin-multi-input](https://npm.io/package/@flatjs/forge-plugin-multi-input.md) 2.3.0

## Recent versions

- 2.5.0 (latest) — 2026-08-18
- 2.5.0-next.0 (next) — 2026-08-03
- 2.4.2 — 2025-10-15
- 2.4.1 — 2025-07-03
- 2.4.1-next.4 — 2025-06-11
- 2.4.1-next.3 — 2025-06-10
- 2.4.1-next.2 — 2025-05-22
- 2.4.1-next.1 — 2025-05-13
- 2.4.1-next.0 — 2025-05-08
- 2.4.0 — 2025-04-22
- 2.3.7 — 2025-03-31
- 2.3.6 — 2025-03-24
- 2.3.6-next.0 — 2025-03-14
- 2.3.5 — 2025-03-06
- 2.3.4 — 2025-03-05
- … 201 more at https://npm.io/package/@flatjs/mock/versions

## README

# @flatjs/mock

## @flatjs/mock 使用指南

迅速启动本地 Mock 服务、方便快捷的模拟各种接口请求场景、模拟各种数据类型响应;

备注 1: 建议保持 Mock 数据的拟真性, 如图片尺寸、文字长短、姓名、日期、证件号码等等, 能提升理解度、美观度、也能发现 UI 的兼容性问题。
备注 2: Postman Collection: https://www.getpostman.com/collections/ae53e4a38a9de2e44b6a

### Step1: 准备工作

1. 安装 VsCode https://code.visualstudio.com;
2. 打开 VsCode, 左侧菜单选择「 Extensions 」, 查找并安装 VsCode 插件: `ESLint`, `Prettier - Code formatter`;
3. 学习 mock 数据的生成规则, 需要 VPN : https://github.com/nuysoft/Mock/wiki/Getting-Started;

### Step2: 配置本地 hosts 文件, 目录: /etc/hosts

1. `127.0.0.1 localhost dev.flatjs.com`

### Step3: 安装依赖 & 启动服务

1. `npm install -g @flatjs/cli yarn`
2. `yarn`
3. `flat mock`

### 静态文件资源

| 地址                                           |
| ---------------------------------------------- |
| http://dev.flatjs.com:40000/static/example.png |
| http://dev.flatjs.com:40000/static/banner.png  |
| http://dev.flatjs.com:40000/static/icon.png    |

### Rest & Rest-nest

| 接口名              | 接口地址                                                                                |
| ------------------- | --------------------------------------------------------------------------------------- |
| 获取产品列表        | http://dev.flatjs.com:40000/api/rest/queryProductList?page=1&pageSize=10                |
| 获取用户信息        | http://dev.flatjs.com:40000/api/rest/queryUserinfo                                      |
| 获取订单列表        | http://dev.flatjs.com:40000/api/rest/queryOrderList?page=1&pageSize=10                  |
| 获取订单详情        | http://dev.flatjs.com:40000/api/rest/queryOrderDetail?orderNo=1                         |
| 支付订单            | http://dev.flatjs.com:40000/api/rest/payOrder?orderNo=1                                 |
| 图片上传            | http://dev.flatjs.com:40000/static/upload-files.png                                     |
| 获取图片流          | http://dev.flatjs.com:40000/api/rest/showImage?fileKey=idcardEmblem                     |
| 模拟各种状态码, 500 | http://dev.flatjs.com:40000/api/rest/fake-500                                           |
| 登录 (nest)         | http://dev.flatjs.com:40000/api/rest/login/loginByUsername?username=abc&password=123456 |

### Func-simple & Func-simple-nest

| 接口名              | 接口地址                                                |
| ------------------- | ------------------------------------------------------- |
| 获取产品类目        | http://dev.flatjs.com:40000/static/func-simple.png      |
| 获取产品类目 (nest) | http://dev.flatjs.com:40000/static/func-simple-nest.png |

```json
// 请求体 Request
{
  "protocol": {
    "functionCode": "queryProductList",
    "fromPlatform": "tc_app",
    "userId": "785d680efb8515c71715a694fa0afe81"
  },
  "param": {
    "page": 1,
    "pageSize": 10
  }
}
```

```json
// 响应体 Response
{
  "code": "0000",
  "message": "success",
  "data": {}
}
```

### Others（任意未预先匹配的路径）

| 接口名  | 接口地址                              |
| ------- | ------------------------------------- |
| unknown | http://dev.flatjs.com:40000/api/a/b/c |

### Proxy (代理)

| 接口名 | 接口地址                                             |
| ------ | ---------------------------------------------------- |
| proxy  | http://dev.flatjs.com:40000/proxy/rest/queryUserinfo |

### gql

| 接口名 | 接口地址                                   |
| ------ | ------------------------------------------ |
| gql    | http://dev.flatjs.com:40000/static/gql.png |

## The usages

```sh
npm i @flatjs/mock
```

```sh
// Install the following devDependencies.
"@types/express": "^4.17.7",
"@types/express-mung": "^0.5.2",
"@types/http-proxy-middleware": "^0.19.3",
"@types/mockjs": "^1.0.3",
```

The configuration of the `flatjs.mock.js` as below example

```ts
baseCwd: join(process.cwd(), `packages/mock/mocks`),
apiContext: '/api',
hostname: 'dev.flatjs.com',
port: 4000,
staticMap: {
  '/static': 'static',
},
mockMap: {
  '/func': { type: 'FUNC', defs: ['func'], middlewares: {res: otherFuncMiddleware.forFuncApiSimpleResponse()] } },
  '/rest': { type: 'REST', defs: ['rest']},
},
```

```ts
// Tor expressjs middleware cycle
// The outer middlewares defined by user should be executed in the final phase

// e.g. Below middleware will used to simplify response for `func`
otherRestMiddleware.forFuncApiSimpleResponse();
```

## Features

- Both support .ts ,.js mock services.
- Provider class `MockBase` as base class for all mock services
- Built in support `mockjs`
- Proiders usually module `exports`.

## Examples

- The first scenario, auto instance class need `@Mockable()` for class

```ts
@mockable()
export default class MockProductService extends MockBase {
  @mockAlias('products')
  geProducts(_req: MockRequest, res: MockResponse): void {
    res.json({
      code: '0000',
      message: 'func product',
      data: ['https://www.flatjs.com/blog/img/flatjs_avatar.png'],
    });
  }
}
```

- The second scenario, auto instance class need `@Mockable()` for class

```ts
@mockable()
export class MockCatalogService extends MockBase {
  @mockAlias('catalog/list')
  getCatalogs(_req: MockRequest, res: MockResponse): void {
    res.json({
      code: '0000',
      message: 'func catalogs',
      data: ['https://www.flatjs.com/blog/img/flatjs_avatar.png'],
    });
  }
}
```

- The third scenario, use module.exports = new () the class decortor `@Mockable` is optional

```ts
class MockUserService extends MockBase {
  @mockAlias('product/list')
  getUsers(_req: MockRequest, res: MockResponse): void {
    res.json({
      data: ['https://www.flatjs.com/blog/img/flatjs_avatar.png'],
    });
  }
}
module.exports = new MockUserService();
```

- The forth scenario

```ts
export function getAds(_req: MockRequest, res: MockResponse): void {
  res.json({
    code: '0000',
    message: 'func ads',
    data: ['https://www.flatjs.com/blog/img/flatjs_avatar.png'],
  });
}
```

## Use Http Proxy `proxyMap`

```ts
 ....
  proxyMap: {
    '/proxy': {
      target: 'https://fex.qa.tcshuke.com',
      pathRewrite: { '^/proxy': '' },
      router(req) {
        switch (req.query.env) {
          case 'me':
            return 'https://dev.flatjs.com:4000';
          case 'uat':
            return `https://fex.qa.tcshuke.com`;
        }
        return 'https://fex.qa.tcshuke.com';
      },
    },
  },
  // request `/proxy/mock/api/status/200?env=uat` ---> `https://fex.qa.tcshuke.com/mock/api/status/200?env=uat`
```

## Use multer for file upload

```ts
import { mockAlias, MockBase, MockRequest, MockResponse } from '@flatjs/mock';
import fs from 'fs';
import mimeTypes from 'mime-types';
import multer from 'multer';
import { join } from 'path';

const storage = multer.diskStorage({
  destination: function (_req, _file, cb) {
    fs.mkdirSync(join(__dirname, '../static/uploads'), { recursive: true });
    cb(null, join(__dirname, '../static/uploads'));
  },
  filename: function (_req, file, cb) {
    const { mimetype, fieldname } = file || {};
    const extension = mimeTypes.extension(mimetype) as string;
    cb(null, `${fieldname}-${Date.now()}.${extension}`);
  },
});

class MockService extends MockBase {
  @mockAlias('/uploadFile')
  uploadFile(req: MockRequest, res: MockResponse): void {
    const upload = multer({
      storage,
    }).any();

    upload(req, res, () => {
      const files = (req.files as Express.Multer.File[]) || [];
      res.json({
        code: '0000',
        message: 'upload files',
        data: {
          ...req.body,
          fieldnames: files.map(
            (s) => `${this.$hostUri(req)}/static/uploads/${s.filename}`
          ),
        },
      });
    });
  }
}

module.exports = new MockService();
```

## Notes

Note, it we want to using `import` or `require` with `cache`
First we can't include this folder into `mockMap` of `flatjs.mock.js`
Second we can't use importFresh(``)
@example

```ts
mockMap: {
  '/func': { type: 'FUNC', defs: ['func'], middlewares: {} },
  '/rest': { type: 'REST', defs: ['rest'], middlewares: {} },
},
the `defs` config should not include any `folders` that we want to cache.
```

---
_Source: https://npm.io/package/@flatjs/mock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._