148 lines
5.5 KiB
Markdown
148 lines
5.5 KiB
Markdown
## API Proxy Mock
|
||
|
||
基于 Node.js 的轻量级 **HTTP 代理 + 本地 Mock**：所有配置（路由映射、服务器参数、接口列表）统一存储在 SQLite，mock 内容保存在 `mock/` 目录文件中，其余请求按配置（HTTP/HTTPS）转发到真实后端。通过 `/__admin` 管理面板进行可视化管理。
|
||
|
||
### 功能说明
|
||
|
||
- **代理转发**：未命中 Mock 的请求会转发到 `config.targetHost`（由 `targetHttps` 决定 HTTP/HTTPS，`targetPort` 可配）。
|
||
- **本地 Mock**：命中路由时直接读取 `mock/` 目录下的文件作为响应体。
|
||
- **SQLite 存储**：路由列表、接口列表、服务器配置全部存储在 `data/mock-mappings.sqlite3`。
|
||
- **Mock 总开关**：`mockEnabled` 为 `false` 时**不拦截**任何 Mock 路由，全部走代理。
|
||
- **Mock 响应**：带简单 CORS 头，以及 `X-Mock-Source`、`X-Mock-Timestamp` 便于排查。
|
||
- **管理面板**：访问 `/__admin` 进入 Element UI 可视化管理界面，支持以下功能：
|
||
- **路由配置**：增删改查路由映射，启用/禁用单条路由，已启用路由自动置顶排序。
|
||
- **Mock 数据配置**：新增/编辑/删除 Mock 文件，`mock/` 目录固定，只需输入文件名和后缀。
|
||
- **接口管理**：增删改查预置接口列表，支持 JSON 数组批量导入。
|
||
- **基础配置**：Mock 开关、默认 Content-Type（下拉选择）、代理端口（修改需重启）、目标主机/端口/HTTPS。
|
||
|
||
### 环境要求
|
||
|
||
- Node.js（建议 18+）
|
||
- 依赖见 `package.json`：`typescript`、`ts-node`、`@types/node`（仅开发/类型）、`sqlite3`
|
||
|
||
### 安装与启动
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
推荐使用 npm 脚本：
|
||
|
||
```bash
|
||
npm run dev
|
||
# 或
|
||
npm start
|
||
```
|
||
|
||
等价于：
|
||
|
||
```bash
|
||
npx ts-node --project tsconfig.json ./index.api.ts
|
||
```
|
||
|
||
类型检查（不生成 JS）：
|
||
|
||
```bash
|
||
npm run typecheck
|
||
```
|
||
|
||
启动成功后，控制台会输出本地监听地址、目标主机等。
|
||
|
||
### 数据存储
|
||
|
||
所有配置统一存储在 SQLite 数据库 `data/mock-mappings.sqlite3` 中：
|
||
|
||
| 表名 | 用途 |
|
||
| --- | --- |
|
||
| `route_mappings` | 路由 → mock 文件映射 + 状态码 + 启用状态 + 接口名称 |
|
||
| `api_list` | 预置接口清单（名称 + 路径） |
|
||
| `mock_files` | mock 文件路径 + 别名 |
|
||
| `server_config` | 服务器配置（端口、目标主机、Content-Type 等） |
|
||
|
||
首次启动时，如果 `mock_files` 表为空，会自动扫描 `mock/` 目录下的文件并导入数据库。
|
||
|
||
### 管理接口
|
||
|
||
将 `<proxyPort>` 换为实际监听端口：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `GET` | `http://localhost:<proxyPort>/__config` | 查看当前路由与配置 |
|
||
| `POST` | `http://localhost:<proxyPort>/__config` | 保存配置（服务器配置 + 路由） |
|
||
| `POST` | `http://localhost:<proxyPort>/__reload-config` | 从数据库重新加载配置 |
|
||
| `POST` | `http://localhost:<proxyPort>/__routes` | 新增/编辑路由映射 |
|
||
| `DELETE` | `http://localhost:<proxyPort>/__routes` | 删除路由映射 |
|
||
| `GET` | `http://localhost:<proxyPort>/__api-list` | 获取预置接口列表 |
|
||
| `POST` | `http://localhost:<proxyPort>/__api-list` | 新增/编辑预置接口 |
|
||
| `DELETE` | `http://localhost:<proxyPort>/__api-list` | 删除预置接口 |
|
||
| `GET` | `http://localhost:<proxyPort>/__mock-files` | 获取 mock 文件列表 |
|
||
| `POST` | `http://localhost:<proxyPort>/__mock-files` | 创建/更新 mock 文件 |
|
||
| `DELETE` | `http://localhost:<proxyPort>/__mock-files` | 删除 mock 文件 |
|
||
| `GET` | `http://localhost:<proxyPort>/__admin` | 配置管理页面（Element UI） |
|
||
|
||
#### `POST /__routes` 请求示例
|
||
|
||
```json
|
||
{
|
||
"route": "/api/new/mock",
|
||
"filePath": "mock/new-api.json",
|
||
"apiName": "新接口",
|
||
"statusCode": 200,
|
||
"enabled": true,
|
||
"useExistingFile": true
|
||
}
|
||
```
|
||
|
||
#### `POST /__config` 请求示例
|
||
|
||
```json
|
||
{
|
||
"config": {
|
||
"proxyPort": 8879,
|
||
"targetHost": "192.168.3.9",
|
||
"targetPort": 8092,
|
||
"targetHttps": false,
|
||
"defaultContentType": "application/json",
|
||
"mockEnabled": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 批量导入接口示例
|
||
|
||
通过管理面板的「批量导入」按钮，输入以下格式的 JSON 数组即可批量添加预置接口：
|
||
|
||
```json
|
||
[
|
||
{ "route": "/api/login", "name": "登录接口" },
|
||
{ "route": "/api/user/info", "name": "获取用户信息" }
|
||
]
|
||
```
|
||
|
||
### TypeScript 与编译说明
|
||
|
||
- 项目根目录包含 `tsconfig.json`，请使用 **`tsc -p .`** 或 **`npm run typecheck`** 做整项目检查。
|
||
- **不要**使用 `tsc .\index.api.ts` 这类「命令行附带单个文件」的方式，否则会与 `tsconfig.json` 冲突并报 **TS5112**。
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
├── index.api.ts # 服务入口
|
||
├── admin.html # 管理面板（Vue 2 + Element UI 单文件）
|
||
├── src/
|
||
│ ├── types.ts # TypeScript 类型定义
|
||
│ ├── constants.ts # 路径常量（MOCK_DIR、DB_FILE 等）
|
||
│ ├── state.ts # 运行时内存状态
|
||
│ ├── db.ts # SQLite 数据库 CRUD
|
||
│ ├── config.ts # 配置加载/保存
|
||
│ ├── proxy.ts # HTTP 服务 + 代理转发 + Mock 响应
|
||
│ ├── admin-handlers.ts # 管理接口处理
|
||
│ ├── mock-files.ts # Mock 文件加载与管理
|
||
│ ├── route-matching.ts # 路由匹配逻辑
|
||
│ ├── api-list.ts # 预置接口列表管理
|
||
│ └── utils.ts # 工具函数
|
||
├── mock/ # Mock 响应文件（文本原样返回）
|
||
└── data/
|
||
└── mock-mappings.sqlite3 # SQLite 数据库
|
||
```
|