npm package: @lacorda/mock-fetch
Description: 一个用于 Taro 应用的请求模拟工具，支持静态数据与本地 HTTP 服务的动态数据。提供路由匹配和 `handler` 动态处理，便于在开发阶段快速构造接口返回。
Latest version: 0.0.4

# @lacorda/mock-fetch

一个用于 Taro 应用的请求模拟工具，支持静态数据与本地 HTTP 服务的动态数据。提供路由匹配和 `handler` 动态处理，便于在开发阶段快速构造接口返回。

## 安装

- 在工作区安装依赖：

```
pnpm -w install
```

> 当 `isTaro: true` 时，在使用项目中需要自行提供 Taro 实例；否则请传入 `fetchFn`。

## 说明

- 模式
  - `static`：静态模拟，按 `method:url` 返回预先设置的数据
  - `dynamic`：动态模拟，通过本地 HTTP 服务返回数据
- 路由
  - 支持 `:param` 形式的路径参数匹配，如 `/api/user/:id`
  - 可提供 `handler` 对返回数据进行动态加工（可访问 `params`、`query`、`options`、`taro`）

## 使用说明

### 1. 基本初始化

```ts
import Taro from '@tarojs/taro'
import MockFetch from '@lacorda/mock-fetch'

const mock = new MockFetch({
  mode: 'static',
  isTaro: true,
  taro: Taro
})

mock.step()
```

### 2. 静态模拟（指定路由覆盖）

```ts
// 无论全局 mode 是什么，指定路由优先走静态
mock.addStaticMock('GET', '/api/user', { id: 1, name: 'Alice' })
```

### 3. 动态模式（dynamic）

```ts
const mock = new MockFetch({ mode: 'dynamic', isTaro: true, taro: Taro })
mock.step()

// 服务端写入接口
// 将指定路由的数据写入本地服务
curl -X POST http://localhost:3000/set \
  -H 'Content-Type: application/json' \
  -d '{"method":"GET","url":"/api/user/1","data":{"id":1,"name":"Bob"}}'

// 请求时 GET 由服务返回，非 GET 写入服务端
```

### 4. 指定路由静态覆盖

```ts
// 全局为 dynamic，但指定路由返回静态数据
const mock = new MockFetch({ mode: 'dynamic', isTaro: true, taro: Taro })
mock.step()
mock.addStaticMock('GET', '/api/info', { ok: true })
```

### 5. 本地服务（dynamic）

```ts
const mock = new MockFetch({ mode: 'dynamic', serverPort: 3000, isTaro: true, taro: Taro })
mock.step()
```

- 服务端写入接口

```bash
curl -X POST http://localhost:3000/set \
  -H 'Content-Type: application/json' \
  -d '{"method":"GET","url":"/api/user/1","data":{"id":1,"name":"Carol"}}'
```

- 直接启动服务（构建后）

```bash
pnpm -w -F @lacorda/mock-fetch build
pnpm -w -F @lacorda/mock-fetch start-server
```

可用环境变量：`PORT`、`MOCK_DATA_PATH`

### 最小示例（dynamic 模式写入与读取）

```bash
# 写入：将指定路由的数据写入本地服务
curl -X POST http://localhost:3000/set \
  -H 'Content-Type: application/json' \
  -d '{"method":"GET","url":"/api/info","data":{"ok":true}}'
```

```ts
// 读取：按原始接口地址请求即可拿到服务数据
const res = await Taro.request({ method: 'GET', url: '/api/info' })
console.log(res.data) // { ok: true }
```

### 6. 非 Taro 环境（浏览器 / Node）

```ts
import MockFetch from '@lacorda/mock-fetch'

const mock = new MockFetch({
  mode: 'static',
  isTaro: false,
  fetchFn: async ({ url, method, headers, data }) => {
    const res = await fetch(url, {
      method,
      headers,
      body: data ? JSON.stringify(data) : undefined,
    })
    const json = await res.json().catch(() => ({}))
    return { data: json, statusCode: res.status, header: {}, errMsg: 'ok' }
  }
})
mock.step()
```

## API

### 选项 `MockFetchOptions`
- `mode`: `'static' | 'dynamic'`（全局配置；可选，默认 `static`）
- `serverPort`: 本地服务端口，默认 `3000`
- `routes`: 路由表（见下文）
- `isTaro`: 是否使用 Taro 环境
- `taro`: 当 `isTaro: true` 时必传，Taro 实例
- `fetchFn`: 当 `isTaro: false` 时必传，请求函数

### 路由 `Route`
- `method`: HTTP 方法
- `url`: 支持 `:param` 动态段的路径
- `data`: 路由的基础数据；若提供 `handler`，其作为 `ctx.data`
- `handler(ctx)`: 动态处理函数，返回最终数据
  - `ctx.params`: 路径参数
  - `ctx.query`: 查询参数
  - `ctx.options`: 原始请求参数
  - `ctx.taro`: Taro 实例

### 成员方法
- `step()`: 启用拦截；在 `dynamic` 模式下启动本地服务
- `reset()`: 关闭服务并恢复原始请求
- `addStaticMock(method,url,data)`: 为指定路由添加静态模拟，优先级最高，可覆盖任意全局 `mode`
- `addRoute(route)`: 添加路由并支持 `handler` 动态处理

## 目录结构

```
packages/mock
├─ src
│  ├─ index.ts
│  └─ server.ts
├─ package.json
└─ tsconfig.json
```

## 许可

MIT