docs:更新文档

This commit is contained in:
dongzp 2026-06-04 12:29:26 +08:00
parent 302f2d977c
commit 6d1f97f202

View File

@ -1,15 +1,19 @@
## API Proxy Mock ## API Proxy Mock
基于 Node.js 的轻量级 **HTTP 代理 + 本地 Mock**:所有配置(路由映射、服务器参数、接口列表)统一存储在 SQLite,mock 内容保存在 `mock/` 目录文件中,其余请求按配置(HTTP/HTTPS)转发到真实后端。通过 `__admin` 管理面板进行可视化管理。 基于 Node.js 的轻量级 **HTTP 代理 + 本地 Mock**:所有配置(路由映射、服务器参数、接口列表)统一存储在 SQLite,mock 内容保存在 `mock/` 目录文件中,其余请求按配置(HTTP/HTTPS)转发到真实后端。通过 `/__admin` 管理面板进行可视化管理。
### 功能说明 ### 功能说明
- **代理转发**:未命中 Mock 的请求会转发到 `config.targetHost`(由 `targetHttps` 决定 HTTP/HTTPS,`targetPort` 可配)。 - **代理转发**:未命中 Mock 的请求会转发到 `config.targetHost`(由 `targetHttps` 决定 HTTP/HTTPS,`targetPort` 可配)。
- **本地 Mock**:命中路由时直接读取 `mock` 目录下的文件作为响应体。 - **本地 Mock**:命中路由时直接读取 `mock/` 目录下的文件作为响应体。
- **SQLite 存储**:路由列表、接口列表、服务器配置全部存储在 `data/mock-mappings.sqlite3`。 - **SQLite 存储**:路由列表、接口列表、服务器配置全部存储在 `data/mock-mappings.sqlite3`。
- **Mock 总开关**:`mockEnabled` 为 `false` 时**不拦截**任何 Mock 路由,全部走代理。 - **Mock 总开关**:`mockEnabled` 为 `false` 时**不拦截**任何 Mock 路由,全部走代理。
- **Mock 响应**:带简单 CORS 头,以及 `X-Mock-Source`、`X-Mock-Timestamp` 便于排查。 - **Mock 响应**:带简单 CORS 头,以及 `X-Mock-Source`、`X-Mock-Timestamp` 便于排查。
- **管理面板**:访问 `/__admin` 进入 Element UI 可视化管理界面。 - **管理面板**:访问 `/__admin` 进入 Element UI 可视化管理界面,支持以下功能:
- **路由配置**:增删改查路由映射,启用/禁用单条路由,已启用路由自动置顶排序。
- **Mock 数据配置**:新增/编辑/删除 Mock 文件,`mock/` 目录固定,只需输入文件名和后缀。
- **接口管理**:增删改查预置接口列表,支持 JSON 数组批量导入。
- **基础配置**:Mock 开关、默认 Content-Type(下拉选择)、代理端口(修改需重启)、目标主机/端口/HTTPS。
### 环境要求 ### 环境要求
@ -50,12 +54,12 @@ npm run typecheck
| 表名 | 用途 | | 表名 | 用途 |
| --- | --- | | --- | --- |
| `route_mappings` | 路由 → mock 文件映射 + 状态码 | | `route_mappings` | 路由 → mock 文件映射 + 状态码 + 启用状态 + 接口名称 |
| `api_list` | 接口名称清单 | | `api_list` | 预置接口清单(名称 + 路径) |
| `mock_files` | mock 文件路径 + 别名 | | `mock_files` | mock 文件路径 + 别名 |
| `server_config` | 服务器配置(端口、目标主机等) | | `server_config` | 服务器配置(端口、目标主机、Content-Type 等) |
首次启动时,如果 `mock/api-list.json` 存在,会自动迁移导入到数据库。 首次启动时,如果 `mock_files` 表为空,会自动扫描 `mock/` 目录下的文件并导入数据库。
### 管理接口 ### 管理接口
@ -66,9 +70,14 @@ npm run typecheck
| `GET` | `http://localhost:<proxyPort>/__config` | 查看当前路由与配置 | | `GET` | `http://localhost:<proxyPort>/__config` | 查看当前路由与配置 |
| `POST` | `http://localhost:<proxyPort>/__config` | 保存配置(服务器配置 + 路由) | | `POST` | `http://localhost:<proxyPort>/__config` | 保存配置(服务器配置 + 路由) |
| `POST` | `http://localhost:<proxyPort>/__reload-config` | 从数据库重新加载配置 | | `POST` | `http://localhost:<proxyPort>/__reload-config` | 从数据库重新加载配置 |
| `POST` | `http://localhost:<proxyPort>/__routes` | 动态新增单个路由与 mock 文件 | | `POST` | `http://localhost:<proxyPort>/__routes` | 新增/编辑路由映射 |
| `GET` | `http://localhost:<proxyPort>/__api-list` | 获取接口列表 | | `DELETE` | `http://localhost:<proxyPort>/__routes` | 删除路由映射 |
| `GET/POST/DELETE` | `http://localhost:<proxyPort>/__mock-files` | 管理 mock 文件 | | `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) | | `GET` | `http://localhost:<proxyPort>/__admin` | 配置管理页面(Element UI) |
#### `POST /__routes` 请求示例 #### `POST /__routes` 请求示例
@ -77,8 +86,10 @@ npm run typecheck
{ {
"route": "/api/new/mock", "route": "/api/new/mock",
"filePath": "mock/new-api.json", "filePath": "mock/new-api.json",
"fileContent": "{\"code\":0,\"message\":\"ok\"}", "apiName": "新接口",
"overwrite": false "statusCode": 200,
"enabled": true,
"useExistingFile": true
} }
``` ```
@ -97,14 +108,40 @@ npm run typecheck
} }
``` ```
#### 批量导入接口示例
通过管理面板的「批量导入」按钮,输入以下格式的 JSON 数组即可批量添加预置接口:
```json
[
{ "route": "/api/login", "name": "登录接口" },
{ "route": "/api/user/info", "name": "获取用户信息" }
]
```
### TypeScript 与编译说明 ### TypeScript 与编译说明
- 项目根目录包含 `tsconfig.json`,请使用 **`tsc -p .`** 或 **`npm run typecheck`** 做整项目检查。 - 项目根目录包含 `tsconfig.json`,请使用 **`tsc -p .`** 或 **`npm run typecheck`** 做整项目检查。
- **不要**使用 `tsc .\index.api.ts` 这类「命令行附带单个文件」的方式,否则会与 `tsconfig.json` 冲突并报 **TS5112**。 - **不要**使用 `tsc .\index.api.ts` 这类「命令行附带单个文件」的方式,否则会与 `tsconfig.json` 冲突并报 **TS5112**。
### 目录说明 ### 目录结构
- `index.api.ts`:服务入口。 ```
- `src/`:模块化源码(types、db、config、proxy、admin-handlers 等)。 ├── index.api.ts # 服务入口
- `mock/`:Mock 响应文件(文本内容原样返回,按需自行写成 JSON 等)。 ├── admin.html # 管理面板(Vue 2 + Element UI 单文件)
- `data/mock-mappings.sqlite3`:SQLite 数据库(路由映射、接口列表、服务器配置)。 ├── 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 数据库
```