# proxy-mock-server **Repository Path**: andmine/proxy-mock-server ## Basic Information - **Project Name**: proxy-mock-server - **Description**: 本地 HTTP 代理转发与 Mock 数据管理工具。核心工作流：拦截请求 → 检查 Mock 记录 → 匹配则返回录制响应 → 不匹配则按规则代理转发并录制响应。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-12 - **Last Updated**: 2026-05-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Proxy & Mock Server 本地 HTTP 代理转发与 Mock 数据管理工具。核心工作流：拦截请求 → 检查 Mock 记录 → 匹配则返回录制响应 → 不匹配则按规则代理转发并录制响应。 ## 技术栈 - **后端**：Node.js + Express + sql.js (SQLite) - **代理**：http-proxy-middleware (selfHandleResponse 模式) - **前端**：Vue 3 + Element Plus + Vite - **其他**：lodash、uuid、cors、dotenv ## 安装与运行 ### 环境要求 - Node.js >= 14.18 ### 安装依赖 ```bash # 安装所有依赖 cd server && npm install cd ../client && npm install ``` ### 开发模式 分别启动后端和前端（两个终端）： ```bash # 终端 1：启动后端服务 # - 管理 API: http://localhost:3000/api # - 代理服务: http://localhost:3001 cd server && npm start # 终端 2：启动前端开发服务器（端口 5173，自动代理 /api 到后端管理 API） cd client && npm run dev ``` 访问 `http://localhost:5173` 使用管理界面。 **注意**：你的 Web 前端项目需要将代理请求转发到 `http://localhost:3001`。 ### 生产模式 ```bash # 1. 构建前端 cd client && npm run build # 2. 启动后端（自动托管前端静态文件） cd ../server && npm start ``` 访问 `http://localhost:3000` 即可。 ## 配置说明 编辑根目录下的 `.env` 文件： | 变量 | 默认值 | 说明 | | ---------------------- | ----------------------- | ---------------------------------------- | | `PORT` | `3000` | 管理 API 服务监听端口 | | `PROXY_PORT` | `3001` | 代理服务监听端口（转发请求到目标服务器） | | `DB_PATH` | `../data/proxy-mock.db` | SQLite 数据库文件路径 | | `LOG_LEVEL` | `info` | 日志级别 (error/warn/info/debug) | | `MAX_RECORD_BODY_SIZE` | `1048576` | 最大录制响应体大小（字节，默认 1MB） | | `IGNORE_HEADERS` | `connection,host,...` | Mock 匹配时忽略的请求头 | ### 架构说明 本项目采用**双端口架构**，将管理 API 和代理服务分离： - **管理 API 端口（默认 3000）**：处理内部接口 - `/api/groups` - 分组管理 - `/api/rules` - 转发规则管理 - `/api/records` - 录制记录管理 - **代理服务端口（默认 3001）**：处理所有代理转发请求 - 根据转发规则匹配请求路径 - 将请求转发到目标服务器 - 录制请求和响应数据 - 支持 Mock 返回 ### 开发模式配置 前端开发服务器（Vite）需要配置代理，将 API 请求转发到对应的端口： ```javascript // client/vite.config.js export default { server: { proxy: { // 管理 API 请求转发到 3000 端口 '/api': { target: 'http://localhost:3000', changeOrigin: true, }, }, }, } ``` 你的 Web 前端项目需要将代理请求转发到 `http://localhost:3001`（代理端口）。 ## 使用指南 ### 1. 配置转发规则 在「转发规则」页面添加规则： - **规则名称**：便于识别 - **匹配路径**：支持前缀匹配（如 `/api`）、通配符（如 `/api/*`）和正则（以 `^` 开头） - **匹配方法**：留空匹配所有方法，或指定 GET/POST 等 - **目标地址**：转发到的目标服务器 URL - **路径重写**：如 `^/api` → 空字符串，将 `/api/users` 重写为 `/users` - **优先级**：数字越小优先级越高 ### 2. 查看录制记录 代理转发成功后，请求和响应会自动保存到「记录管理」页面： - 按分组、方法、URL 筛选记录 - 点击记录查看详情（请求头、请求体、响应头、响应体） - 编辑记录的响应内容（定制 Mock 返回） ### 3. 启用 Mock 在记录列表中开启某条记录的 Mock 开关后，后续匹配的请求将直接返回录制的响应，不再转发到目标服务器。 匹配规则：请求方法 + URL 路径精确匹配，查询参数子集匹配。 ### 4. 分组管理 - 记录默认归入「默认组」 - 可新建分组，在记录详情中修改所属分组 - 右键分组可重命名或删除 ### 5. 导入导出 在「导入导出」页面： - **导出**：选择范围后下载 JSON 文件，包含分组和记录数据 - **导入**：上传之前导出的 JSON 文件，自动处理分组合并 ## API 文档 **注意**：以下所有 API 端点都在管理 API 端口（默认 3000）上。 ### 分组 API | 方法 | 路径 | 说明 | | ------ | ------------------------------------------------------------- | ------------------------ | | GET | `http://localhost:3000/api/groups` | 获取所有分组（含记录数） | | POST | `http://localhost:3000/api/groups` | 创建分组 `{ name }` | | PUT | `http://localhost:3000/api/groups/:id` | 更新分组 `{ name }` | | DELETE | `http://localhost:3000/api/groups/:id?action=move_to_default` | 删除分组 | ### 转发规则 API | 方法 | 路径 | 说明 | | ------ | ---------------------------------------------- | ------------------------- | | GET | `http://localhost:3000/api/rules` | 获取规则列表 | | POST | `http://localhost:3000/api/rules` | 创建规则 | | PUT | `http://localhost:3000/api/rules/:id` | 更新规则 | | DELETE | `http://localhost:3000/api/rules/:id` | 删除规则 | | PATCH | `http://localhost:3000/api/rules/:id/priority` | 更新优先级 `{ priority }` | ### 记录 API | 方法 | 路径 | 说明 | | ------ | -------------------------------------------------------------------------- | --------------------------- | | GET | `http://localhost:3000/api/records?group_id=&method=&keyword=&page=&size=` | 获取记录列表（分页） | | GET | `http://localhost:3000/api/records/:id` | 获取记录详情 | | PUT | `http://localhost:3000/api/records/:id` | 编辑记录 | | DELETE | `http://localhost:3000/api/records/:id` | 删除记录 | | PATCH | `http://localhost:3000/api/records/:id/mock` | 切换 Mock `{ enabled }` | | POST | `http://localhost:3000/api/records/batch/mock` | 批量切换 `{ ids, enabled }` | | POST | `http://localhost:3000/api/records/batch/delete` | 批量删除 `{ ids }` | | POST | `http://localhost:3000/api/records/export` | 导出 `{ group_id?, ids? }` | | POST | `http://localhost:3000/api/records/import` | 导入 `{ data, mode }` | ## 项目结构 ``` proxy-mock-server/ ├── .env # 环境变量配置 ├── package.json # 根快捷脚本 ├── data/ # SQLite 数据库文件 ├── server/ │ ├── package.json │ └── src/ │ ├── index.js # 入口 │ ├── app.js # Express 应用组装 │ ├── config.js # 配置 │ ├── db/ # 数据库连接与建表 │ ├── models/ # 数据模型 (group/rule/record) │ ├── routes/ # API 路由 │ ├── middleware/ # 代理中间件 + 错误处理 │ ├── services/ # 匹配引擎 + 录制 + 代理 │ └── utils/ # 日志 + 工具函数 └── client/ ├── package.json ├── vite.config.js └── src/ ├── views/ # 页面组件 ├── components/ # 通用组件 └── api/ # 后端 API 封装 ``` ## 常见问题 **Q: 为什么有两个端口？它们的作用是什么？** A: 本项目采用双端口架构： - **3000 端口**：管理 API，用于管理分组、规则、记录等内部接口 - **3001 端口**：代理服务，用于转发你的应用请求到目标服务器 - 这样设计避免了管理接口和代理请求的路径冲突 **Q: 我的 Web 前端项目如何配置代理？** A: 在你的前端开发服务器配置中，将 API 请求代理到 `http://localhost:3001`。详见 [PROXY_USAGE.md](PROXY_USAGE.md)。 **Q: 代理转发后看不到录制记录？** A: 仅当目标服务器正常返回响应时才会录制。检查目标地址是否可达，查看终端日志排查。 **Q: Mock 匹配不生效？** A: 确认记录的 Mock 开关已开启，且请求的 method 和 URL path 与记录完全一致。 **Q: 响应体显示 `[BODY_TOO_LARGE]`？** A: 响应体超过 `MAX_RECORD_BODY_SIZE`（默认 1MB）会跳过录制。可在 `.env` 中调大限制。 **Q: 前端页面空白？** A: 开发模式需单独启动前端 (`cd client && npm run dev`)。生产模式需先构建 (`cd client && npm run build`)。